Agents - Skickamejl

API base URL

https://skickamejl.se

Local development usually runs at http://localhost:5121.

Authentication

Send the server API token in X-Api-Key.

MCP clients use Authorization: Bearer <server-api-token>.

Never put this token in browser JavaScript or public client code.

Send endpoint

POST /api/messages

Successful requests return 202 Accepted.

Agent checklist

Do this first

These steps are enough for a clean first integration.

1

Create or select a server

In the Skickamejl UI, create a server. Each server has message streams and one server API token.

2

Use the transactional stream by default

For receipts, login codes, password resets, order updates, and operational mail, use messageStream: "transactional".

3

Send plain addresses only

Use from@example.se, not Name <from@example.se>. Display names belong in your message content or templates, not the API address fields.

4

Provide text or HTML body

At least one of textBody or htmlBody is required. Sending both is recommended.

5

Handle accepted, failed, and suppressed states

A 202 means Skickamejl accepted the message for delivery. Store the returned messageId for support and diagnostics.

MCP

Use MCP when the caller is an AI agent

MCP is the recommended path when an AI assistant, coding agent, or automation tool can connect to remote MCP servers. REST is still the right choice for normal backend code and product integrations.

Why MCP exists here

The Skickamejl MCP server exposes email actions as explicit tools, so agents do not have to guess endpoint paths, headers, payload shapes, or retry behavior. Use it to send test transactional emails and inspect email workflows from an agent.

Endpoint: https://skickamejl.se/mcp
Auth: Authorization: Bearer <server-api-token>
Main use case: Connect AI agents to send and inspect transactional emails.

mcp.json

{
  "mcpServers": {
    "skickamejl": {
      "type": "http",
      "url": "https://skickamejl.se/mcp",
      "headers": {
        "Authorization": "Bearer <server-api-token>"
      }
    }
  }
}

Safe first test

Use the Skickamejl MCP server to send a test transactional email to <recipient@example.com> with subject "MCP test" and text body "This was sent through MCP."

Before the first call to a sending tool, ask the human for approval. Sending email is an external action and should not happen silently.

Send request

The minimal correct API call

Replace <server-api-token> with the token from the selected server.

curl "https://skickamejl.se/api/messages" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <server-api-token>" \
  -d '{
    "from": "no-reply@example.se",
    "to": "customer@example.com",
    "subject": "Your receipt",
    "textBody": "Thanks for your purchase.",
    "htmlBody": "<p>Thanks for your purchase.</p>",
    "messageStream": "transactional",
    "tag": "receipt",
    "metadata": {
      "orderId": "12345"
    }
  }'

Request fields

from: Required. Plain email address, max 320 characters.
to: Required. Plain recipient email address, max 320 characters.
subject: Required. Max 200 characters.
textBody: Optional if htmlBody is present. Max 10,000 characters.
htmlBody: Optional if textBody is present. Max 20,000 characters.
replyTo: Optional. Plain email address.
messageStream: Optional. Defaults to transactional. Do not use inbound streams for sending.
tag: Optional. Max 120 characters. Use stable values such as welcome, receipt, or password-reset.
metadata: Optional object with up to 20 string keys. Keys may contain letters, numbers, dots, colons, hyphens, and underscores.

Response shape

{
  "messageId": "msg_...",
  "deliveryId": "...",
  "jobId": "...",
  "serverId": "00000000-0000-0000-0000-000000000000",
  "status": "queued",
  "messageStream": "transactional",
  "queuedAtUtc": "2026-06-25T12:00:00+00:00"
}

Persist messageId. It is the best support reference for later troubleshooting.

Error contract

How agents should react

Skickamejl uses standard HTTP status codes and a JSON problem response with a code extension when possible.

Status	Code	Agent action
`400`	`invalid_message_stream`, `recipient_suppressed`, validation errors	Fix the request. Do not retry unchanged.
`401`	`missing_api_key`, `invalid_api_key`	Ask for a valid server token. Do not invent credentials.
`404`	`unknown_message_stream`	Use `transactional` or a stream key that exists on the server.
`413`	Request body too large	Reduce body size below 64 KB.
`429`	Rate limited	Retry with backoff.
`502`	`backend_send_failed`	Retry later or alert an operator if repeated.

Sender domains and DNS

For production sending, add a sender domain in Skickamejl and follow the DNS settings shown in the UI.

DKIM is verified through a TXT record.
Return-Path is verified through a CNAME record.
DMARC is detected through a TXT record at _dmarc.your-domain.
New domains start as pending until DNS verification succeeds.

Rules for AI agents

Never expose X-Api-Key in frontend code.
Prefer server-side sending from backend code, jobs, or trusted serverless functions.
Use stable tags and metadata so humans can debug deliveries later.
Validate inputs before sending. Do not retry validation errors.
Keep transactional mail separate from marketing mail.
Link humans to Swagger when they need the full OpenAPI view.

Integrate Skickamejl without guessing