Integrate Skickamejl without guessing

This page is written for AI agents, coding assistants, and automation tools that need to add transactional email to a product. Use it as the source of truth for sending email through Skickamejl.se.

Förbered projektets avsändardomän

Öppna projektet och välj fliken Avsändardomäner. Kontoägaren eller en kontoadministratör skapar en domän eller väljer Koppla befintlig domän. Domänen och signaturerna tillhör kontot och kan delas av flera projekt.

Byt from i kodexemplen till en adress på den kopplade domänen och använd samma projekts API-token. Kopplingen krävs för REST, SDK, mallar, MCP, kampanjer och Home Assistant, även i sandlåda. Vid byte till ett annat projekt behöver domänen vara kopplad även där.

En oregistrerad eller okopplad domän ger HTTP 400 med sender_domain_not_linked. Inget meddelande sparas eller skickas. Rätta projektkopplingen eller avsändaradressen innan du försöker igen.

Do this first

These steps are enough for a clean first integration.

1

Create or select a project

In the Skickamejl UI, create a project. Each project has message types and its own API token.

2

Use the transactional stream by default

For receipts, login codes, password resets, order updates, and operational mail, use messageType: "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.

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.

The minimal correct API call

Ersätt <server-api-token> med det valda projektets token och from med en adress på projektets kopplade avsändardomän.

curl "https://skickamejl.se/api/meddelanden" \
  -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>",
    "messageType": "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.
messageType
Optional. Defaults to transactional. Do not use inbound message types 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",
  "messageType": "transactional",
  "queuedAtUtc": "2026-06-25T12:00:00+00:00"
}

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

Let Home Assistant react to Skickamejl events

Use the Home Assistant integration when a smart home, operations dashboard, or local automation should know that Skickamejl queued, delivered, bounced, or failed a transactional email.

Integration contract

Repository
MRCCollective/home-assistant-skickamejl
Projektets avsändardomän
Koppla avsändardomänen till samma projekt vars API-token används i Home Assistant. Befintliga projekt-ID:n, API-token och webhookformat behålls.
Home Assistant event
skickamejl_email_event
Webhook URL source
Copy the copy_to_skickamejl attribute from sensor.skickamejl_webhook_url.
Public URL rule
For hosted Skickamejl.se, use a public HTTPS webhook URL. Home Assistant Cloud/Nabu Casa cloudhooks are preferred when available.

Skickamejl webhook setup

  1. Install the Home Assistant integration through HACS as a custom repository.
  2. Configure Skickamejl in Home Assistant and open the Webhook-URL entity.
  3. Copy copy_to_skickamejl. Do not use a local 192.168.x.x URL for hosted Skickamejl.se.
  4. Paste that URL into the project or stream webhook settings in Skickamejl.
  5. Enable Skickat/köat for send events, and add delivery, bounce, open, click, or subscription events when those automations matter.

Webhook payload fields

{
  "event": "email.sent",
  "eventType": "Queued",
  "templateId": "account-created",
  "templateAlias": "account-created",
  "messageId": "msg_...",
  "deliveryId": "...",
  "recipient": "customer@example.com",
  "deliveryStatus": "Queued"
}

Agents should prefer stable template identifiers, aliases, tags, and metadata when creating Home Assistant automations.

Automation example

alias: React when Skickamejl sends an account email
triggers:
  - trigger: event
    event_type: skickamejl_email_event
conditions:
  - condition: template
    value_template: "{{ trigger.event.data.template_id == 'account-created' }}"
actions:
  - action: persistent_notification.create
    data:
      title: "Skickamejl"
      message: "Account email was sent to {{ trigger.event.data.recipient_address }}."

Use trigger.event.data.template_id, delivery_id, message_id, recipient_address, and status for reliable automation conditions.

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 sender_domain_not_linked Be kontoägaren eller en kontoadministratör koppla domänen under projektets Avsändardomäner, eller välj en avsändare från en kopplad domän. Kravet gäller även sandlåda. Försök igen först när kopplingen eller avsändaren har rättats.
400 invalid_message_type, recipient_suppressed, validation errors Fix the request. Do not retry unchanged.
401 missing_api_key, invalid_api_key Ask for a valid project token. Do not invent credentials.
404 unknown_message_type Use transactional or a stream key that exists in the project.
413 Request body too large Reduce body size below 8 MB. Attachments: at most four XLSX, PDF, CSV or TXT files, 5 MB each and 5 MB total.
429 Rate limited Retry with backoff.
502 backend_send_failed Retry later or alert an operator if repeated.

Sender domains and DNS

Domänen måste vara kopplad till projektet för alla utskick, även i sandlåda. För riktiga leveranser följer du DNS-inställningarna i projektets flik Avsändardomäner och kontrollerar DNS. Samma kontodomän kan kopplas till flera projekt.

Automatisk DNS-konfiguration via BeeByte är inte tillgänglig ännu. Projektets token används för REST, SDK och MCP; utgående SMTP-inloggning med den token stöds inte ännu.

  • 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.