Mail Service API

A small HTTP API for sending transactional email. You send a JSON request, the service queues it and returns 202 Accepted straight away, and background workers deliver the mail over SMTP.

Quick start

1. Get an API key. Request one from the home page. Keys look like msk_ followed by 64 hex characters.
2. Store it as a secret. Put it in an environment variable on your server, never in client-side code.
3. Send a request with the key in the X-API-Key header:

export API_KEY="msk_your_key_here"

curl -X POST {{BASE}}/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"to": "ada@example.com", "subject": "Hello", "body": "It works!"}'

A 202 Accepted response with the body mail queued means the mail is in the delivery queue.

Base URL & format

All endpoints are relative to this server:

{{BASE}}

• Send request bodies as JSON with Content-Type: application/json.
• Request bodies are limited to 1 MB.
• Successful send calls answer with plain text such as mail queued.
• Authentication and rate-limit errors answer with JSON containing an error field. Validation errors are plain text. See Errors.
• Use HTTPS in production so your API key is never sent in clear text.

Authentication

Every endpoint except /health and /api/status needs a valid API key. Send it in either header; X-API-Key is checked first.

POST /send HTTP/1.1
Content-Type: application/json
X-API-Key: msk_3f9c…

POST /send HTTP/1.1
Content-Type: application/json
Authorization: Bearer msk_3f9c…

How keys are checked

1. The key must exist. Unknown keys get 401 invalid API key.
2. The key must be active. Keys an administrator has disabled get 403 API key is disabled.
3. Your IP must be allowed by the key (see IP restrictions), otherwise 403.
4. The request must fit within the key's rate limits, otherwise 429.

IP restrictions

Each key has an allow list of client addresses. It can be:

Requests from other addresses are rejected before any limit is checked:

{
  "error": "IP address 198.51.100.7 is not allowed for this API key"
}

Ask for IP restrictions when you request your key. They make a leaked key useless from anywhere else.

Rate limits

Each key can have up to four limits. They count mails, not HTTP requests: a bulk request to 20 recipients uses 20.

• Windows are rolling: usage from 61 minutes ago no longer counts towards the hourly limit.
• A request that would exceed any limit is rejected as a whole. Nothing from it is queued or counted.
• Rejected and invalid requests do not use up your limits.
• Limits are enforced atomically, so parallel requests cannot go over a limit.

When a limit is reached

You get 429 Too Many Requests with a Retry-After header in seconds and a JSON body describing the limit:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1834

{
  "error": "Hourly limit exceeded: 98 of 100 mails already used in the last hour and this request needs 5 more. Try again after 2026-09-18T17:23:08Z",
  "window": "hour",
  "limit": 100,
  "used": 98,
  "requested": 5,
  "retry_at": "2026-09-18T17:23:08Z"
}

Errors

These can be returned by any authenticated endpoint. JSON errors always have an error string.

{
  "error": "invalid API key"
}

Delivery behaviour

• 202 means queued, not delivered. Mails are delivered by background workers shortly afterwards.
• Each API key can have its own SMTP server. Mail sent with your key goes out through the server and From address an administrator assigned to it. Keys without one use the service's default server. See Your own SMTP server.
• The queue lives in memory. Mails still in the queue are lost if the service restarts, so resend anything critical if you see an outage on the status panel.
• Bodies are sent as plain UTF-8 text. HTML is not rendered. Line breaks in subject are replaced with spaces.
• Delivery failures (for example, a rejected address) are recorded on the server. They are not reported back to the caller. An administrator can see them and send failed mail again.
• Every mail is recorded. The service keeps each mail's sender, recipient, subject, body and delivery status so administrators can trace and troubleshoot delivery.
• When delivery is simulation, mails are only logged. Use this for testing.

Your own SMTP server

By default, mail goes out through the service's own SMTP server. You can ask for your key to use your own mail host instead, so mail is sent from your domain and address. The API calls stay exactly the same.

How to request it

1. In the request form, tick Send through my own SMTP server and fill in the details below.
2. An administrator reviews the request. If it is approved, they contact you by email to get the SMTP password privately.
3. Once the server is set on your key, every mail sent with that key goes through it.

Already have a key? Send a new request with the same details and mention your existing key in the message.

Details we need

Code examples

Sending one email and handling rate limits correctly.

curl -i -X POST {{BASE}}/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "to": "ada@example.com",
    "subject": "Password reset",
    "body": "Use this link to reset your password: https://example.com/reset/abc123"
  }'

// Node.js 18+ (built-in fetch)
const BASE_URL = "{{BASE}}";

async function sendMail(to, subject, body) {
  const res = await fetch(`${BASE_URL}/send`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.MAIL_API_KEY,
    },
    body: JSON.stringify({ to, subject, body }),
  });

  if (res.status === 202) return;

  if (res.status === 429) {
    const err = await res.json();
    const wait = Number(res.headers.get("Retry-After") || 60);
    throw new Error(`${err.error} (retry in ${wait}s)`);
  }

  const text = await res.text();
  throw new Error(`Mail API ${res.status}: ${text}`);
}

await sendMail("ada@example.com", "Welcome", "Your account is ready.");

# pip install requests
import os
import requests

BASE_URL = "{{BASE}}"

def send_mail(to, subject, body):
    res = requests.post(
        f"{BASE_URL}/send",
        headers={"X-API-Key": os.environ["MAIL_API_KEY"]},
        json={"to": to, "subject": subject, "body": body},
        timeout=10,
    )
    if res.status_code == 202:
        return
    if res.status_code == 429:
        err = res.json()
        wait = int(res.headers.get("Retry-After", 60))
        raise RuntimeError(f"{err['error']} (retry in {wait}s)")
    raise RuntimeError(f"Mail API {res.status_code}: {res.text}")

send_mail("ada@example.com", "Welcome", "Your account is ready.")

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

const baseURL = "{{BASE}}"

func sendMail(to, subject, body string) error {
	payload, _ := json.Marshal(map[string]string{"to": to, "subject": subject, "body": body})
	req, err := http.NewRequest(http.MethodPost, baseURL+"/send", bytes.NewReader(payload))
	if err != nil {
		return err
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", os.Getenv("MAIL_API_KEY"))

	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()

	if res.StatusCode == http.StatusAccepted {
		return nil
	}
	msg, _ := io.ReadAll(res.Body)
	if res.StatusCode == http.StatusTooManyRequests {
		return fmt.Errorf("rate limited, retry after %ss: %s", res.Header.Get("Retry-After"), msg)
	}
	return fmt.Errorf("mail API %d: %s", res.StatusCode, msg)
}

func main() {
	if err := sendMail("ada@example.com", "Welcome", "Your account is ready."); err != nil {
		fmt.Println(err)
	}
}

Bulk send in batches

Keep each bulk request within your hourly limit and back off when you hit it:

async function sendBulk(recipients, subject, body, batchSize = 50) {
  for (let i = 0; i < recipients.length; i += batchSize) {
    const batch = recipients.slice(i, i + batchSize);
    for (;;) {
      const res = await fetch("{{BASE}}/send/bulk", {
        method: "POST",
        headers: { "Content-Type": "application/json", "X-API-Key": process.env.MAIL_API_KEY },
        body: JSON.stringify({ recipients: batch, subject, body }),
      });
      if (res.status === 202) break;
      if (res.status !== 429) throw new Error(`Mail API ${res.status}: ${await res.text()}`);

      const err = await res.json();
      if (err.retry_at === null) throw new Error("Batch larger than limit: " + err.error);
      const wait = Number(res.headers.get("Retry-After") || 60);
      await new Promise((r) => setTimeout(r, wait * 1000));
    }
  }
}

Best practices

Postman collection

The repository includes postman_collection.json with requests for every endpoint. Import it, open the collection's Variables tab and set apiKey to your key. Every mail request then sends it as X-API-Key.