Mailaki Documentation

Send transactional emails, receive inbound email, and manage deliverability — all through a simple REST API.

Quickstart

Get from zero to sending your first email in under 5 minutes.

curl -X POST https://mailaki.com/v1/messages \
  -H "Authorization: Bearer mf_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "YOUR_DOMAIN_UUID",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Welcome to our app!",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
    "text": "Welcome! Thanks for signing up."
  }'

You'll get back a message ID confirming it's queued for delivery:

{
  "ids": ["0193abc0-1234-7000-8000-000000000001"],
  "status": "queued",
  "dropped": []
}

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer mf_live_your_api_key

You can also use the x-api-key header:

x-api-key: mf_live_your_api_key

Your API key is shown once when you create your account. You can create additional keys in the portal under API Keys.

Base URL

https://mailaki.com/v1

Send your first email

Before sending, you need your domain_id. Find it in the portal under Domains, or via the API:

curl https://mailaki.com/v1/domains \
  -H "Authorization: Bearer mf_live_..."

Then send:

curl -X POST https://mailaki.com/v1/messages \
  -H "Authorization: Bearer mf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "019d7397-ca06-7781-b212-726e03ecb96b",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Hello from Mailaki",
    "text": "This is a test email sent via the Mailaki API.",
    "html": "
This is a test email sent via the Mailaki API.
"
  }'

Send via JSON

POST /v1/messages

Request body

Response

{
  "ids": ["0193abc0-..."],
  "status": "queued",
  "dropped": []
}

If a recipient is on the suppression list, they'll appear in dropped with a reason.

HTML emails

Include both text and html fields. Mailaki sends a multipart/alternative message so email clients can pick their preferred format.

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Your weekly report",
  "text": "Your report is ready. Visit https://app.example.com/reports",
  "html": "<h2>Your weekly report</h2><p>Visit <a href='https://app.example.com/reports'>your dashboard</a>.</p>"
}

Templates

Create reusable templates with {{variable}} substitution.

curl -X POST https://mailaki.com/v1/templates \
  -H "Authorization: Bearer mf_live_..." \
  -d '{
    "name": "welcome",
    "subject": "Welcome, {{name}}!",
    "html": "<h1>Hi {{name}}</h1><p>Thanks for joining {{company}}.</p>"
  }'

curl -X POST https://mailaki.com/v1/messages \
  -H "Authorization: Bearer mf_live_..." \
  -d '{
    "domain_id": "...",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "template_id": "TEMPLATE_UUID",
    "variables": {"name": "Alice", "company": "Acme Inc"}
  }'

Open & click tracking

Mailaki automatically tracks opens (via tracking pixel) and clicks (via link rewriting). Both are enabled by default.

Disable tracking per message:

{
  "tracking": {"opens": false, "clicks": false}
}

Inbound email setup

Receive emails at your domain and process them via the API or webhooks.

DNS setup

Inbound routes

Routes match incoming email addresses against patterns and perform actions.

curl -X POST https://mailaki.com/v1/routes \
  -H "Authorization: Bearer mf_live_..." \
  -d '{
    "pattern": "[email protected]",
    "action": "store"
  }'

Patterns support wildcards: *@yourdomain.com catches all addresses.

Reading emails

GET /v1/stored-messages — list stored inbound messages

GET /v1/stored-messages/:id — get full message content

curl https://mailaki.com/v1/stored-messages \
  -H "Authorization: Bearer mf_live_..."

[
  {
    "id": "0193abc1-...",
    "from_addr": "[email protected]",
    "to_addr": "[email protected]",
    "subject": "Help with my order",
    "body_text": "Hi, I need help...",
    "raw_size": 1234,
    "created_at": "2026-04-13T10:00:00Z"
  }
]

Add a domain

Add your domain in the portal under Domains, then configure the DNS records we provide.

DNS records

After adding a domain, set up these DNS records:

Event webhooks

Get notified when emails are delivered, bounced, opened, or clicked.

curl -X POST https://mailaki.com/v1/webhooks \
  -H "Authorization: Bearer mf_live_..." \
  -d '{
    "url": "https://yourapp.com/webhooks/email",
    "event_types": ["delivered", "bounced", "opened", "clicked"],
    "secret": "whsec_your_webhook_secret"
  }'

Events are signed with HMAC-SHA256. Verify the X-Mailaki-Signature header:

import hmac, hashlib

def verify(payload_bytes, signature, secret):
    expected = hmac.new(secret.encode(), payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Event types

Python SDK

pip install mailaki

from mailaki import Mailaki

client = Mailaki(api_key="mf_live_...")

# Send an email
result = client.messages.send(
    domain_id="YOUR_DOMAIN_UUID",
    from_addr="[email protected]",
    to=["[email protected]"],
    subject="Welcome!",
    text="Thanks for signing up.",
    html="<h1>Welcome!</h1><p>Thanks for signing up.</p>"
)
print(result["ids"])  # ['0193abc0-...']

# Create an inbox for receiving
inbox = client.inboxes.create(address="[email protected]")

# Read inbound emails
messages = client.inboxes.list_messages(inbox["id"])

TypeScript SDK

npm install mailaki

import { Mailaki } from "mailaki";

const client = new Mailaki("mf_live_...");

// Send an email
const result = await client.messages.send({
  domain_id: "YOUR_DOMAIN_UUID",
  from: "[email protected]",
  to: ["[email protected]"],
  subject: "Welcome!",
  text: "Thanks for signing up.",
  html: "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
});

// Create an inbox
const inbox = await client.inboxes.create({
  address: "[email protected]"
});

// Read emails
const messages = await client.inboxes.listMessages(inbox.id);

cURL

No SDK needed — the API is a standard REST JSON API. Set two headers and you're done:

curl -X POST https://mailaki.com/v1/messages \
  -H "Authorization: Bearer mf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain_id":"...","from":"[email protected]","to":["[email protected]"],"subject":"Hi","text":"Hello"}'

Full API Reference

See the complete interactive API reference with all endpoints, request/response schemas, and try-it-out functionality:

Open API Reference →