Using an LLM API

Swanmail can call cloud LLM APIs directly as AI agents. Two provider families are supported:

• OpenAI-compatible chat completions APIs — OpenAI, Groq, local Ollama, etc.
• Anthropic Messages API — Claude models.

This lets you use hosted services or a local model server without writing a CLI wrapper.

When to use LLM API

Use the LLM API tab when:

• You already have access to an OpenAI, Groq, or Anthropic API key.
• You run a local model server such as Ollama.
• You want to try AI features without installing a local agent CLI.

For local-only / offline use, Ollama is the simplest choice because your email content never leaves your machine.

Supported tasks

LLM API configs work with all existing agent tasks:

• classify — assign a category and labels to a message.
• spam_check — estimate a spam score.
• summarize — summarize a thread.
• translate — translate message text.
• custom_filter — run a user-defined prompt over a set of messages.
• test — send an arbitrary prompt and inspect the JSON output.

Configuration

1. Open Settings → LLM API.

2. Click Add API config and choose OpenAI or Anthropic.

3. Fill in the three required fields (the current UI and runtime require a non-empty API key even for local endpoints):

   Field	Example
   API URL	https://api.openai.com/v1 or https://api.anthropic.com/v1
   API Key	sk-...
   Model	gpt-4o, claude-sonnet-4-20250514, etc.

4. Save and enable the config for one or more accounts (in Settings → AI Agents).

Example setups

OpenAI

• API URL: https://api.openai.com/v1
• API Key: your OpenAI API key
• Model: gpt-4o-mini or gpt-4o

Anthropic

• API URL: https://api.anthropic.com/v1
• API Key: your Anthropic API key
• Model: claude-sonnet-4-20250514 or another Claude model

Groq

• API URL: https://api.groq.com/openai/v1
• API Key: your Groq API key
• Model: llama3-8b-8192 or another Groq model

Ollama (local)

Make sure Ollama is running and the model is pulled, for example:

ollama pull llama3.2
ollama serve

Then configure Swanmail:

• API URL: http://localhost:11434/v1
• API Key: enter a non-empty placeholder if the local server ignores authentication
• Model: llama3.2
• Allow private/local endpoint: enable this toggle, because localhost is otherwise blocked by the SSRF filter.

Request format

OpenAI-compatible

Swanmail sends:

{
  "model": "your-model",
  "messages": [{ "role": "user", "content": "<rendered prompt>" }],
  "temperature": 0.3
}

The endpoint must return:

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

Anthropic

Swanmail sends:

{
  "model": "your-model",
  "messages": [{ "role": "user", "content": "<rendered prompt>" }],
  "max_tokens": 1024
}

The endpoint must return:

{
  "content": [{ "type": "text", "text": "..." }]
}

The content should contain parseable JSON. Swanmail extracts the JSON object automatically and applies the result to the message (category, labels, spam score, etc.).

Security notes

• Your API key is encrypted with the key held in the data directory on macOS, protected by DPAPI on Windows, or held in the Secret Service on Linux.
• The raw key is never sent to the app's interface.
• The renderer only sees a hasApiKey boolean so it can show whether a key is stored.
• LLM API URLs are validated before each request: non-HTTP(S) protocols, embedded credentials, and private/loopback addresses are rejected by default.
• To use a local server such as Ollama, enable Allow private/local endpoint in the config. This is opt-in per LLM API configuration.