AI agents

Swanmail can call local AI agents to enhance your email workflow. AI features are opt-in and only appear after you configure at least one agent.

What agents can do

• Summarize long threads into a few bullet points.
• Translate messages into another language.
• Categorize and label incoming mail automatically.
• Spam scoring to highlight likely junk.

How it works

Agents are external programs (shell commands or scripts) that receive an email as input and return JSON. Swanmail invokes them via the agent runtime and stores the results in SQLite.

Because agents are local commands, you stay in control of the model and data. No email content is sent to third-party APIs unless you configure an agent that does so.

Configuring an agent

1. Open Settings → AI Agents.
2. Add a new agent with:
   • Name
   • Provider type (echo, claude, kimi, codex, pi, or custom)
   • Command and optional arguments template
   • Timeout and concurrency limits
3. Enable the agent for one or more accounts.

For testing, the built-in echo provider returns a simple response without calling an external model.

Agent output format

Agents should return JSON matching the expected schema. The exact fields depend on the task:

{
  "category": "Travel",
  "labels": ["Flight", "Booking"],
  "spamScore": 0.1,
  "summary": "Your flight is confirmed for tomorrow.",
  "translation": "..."
}

Missing fields are ignored.

LLM API provider

In addition to local CLI agents, Swanmail supports OpenAI-compatible chat completions endpoints and the native Anthropic Messages API. This covers hosted APIs such as OpenAI and Groq, plus local servers such as Ollama.

To configure an LLM API agent:

1. Open Settings → LLM API.
2. Choose OpenAI or Anthropic, then enter the API URL — the base URL of the selected endpoint. OpenAI configs use ${apiUrl}/chat/completions; Anthropic configs use ${apiUrl}/messages.
   • OpenAI: https://api.openai.com/v1
   • Ollama: http://localhost:11434/v1
3. Enter your API key. It is encrypted with Swanmail's credentials key (see Privacy) and is never exposed to the renderer. The current configuration requires a non-empty key, including for local endpoints.
4. Enter the model name, for example gpt-4o or llama3.2.
5. Enable Allow private/local endpoint if your API URL points to localhost or a private IP (required for local Ollama).

The endpoint must return the standard OpenAI response shape:

{
  "choices": [{ "message": { "content": "..." } }]
}

All existing agent tasks (classify, spam check, summarize, translate, custom filter, and test) work with this provider.

CLI

You can also test agents from the command line:

pnpm cli agents test --id <agentId> --prompt "Your prompt here" --json

The CLI also supports agents list, agents add, agents remove, agents jobs, agents run-filter, and agents set-account. CLI agent configuration is for local command providers; configure OpenAI or Anthropic API agents in the app's AI Agents settings.