Documentation

Getting started

Create an API key under API Keys in the dashboard, then send. You can send from a sandbox key straight away; a real domain needs its DNS records first.

curl https://api.maillog.dev/v1/emails \
  -H "Authorization: Bearer ma_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Maillog <[email protected]>",
    "to": ["[email protected]"],
    "subject": "hello world",
    "html": "<p>it works</p>"
  }'

The answer carries the id of the message. Use it on GET /v1/emails/:id to see how delivery went.

Authentication

Every call carries Authorization: Bearer <key>. A key belongs to one team, and you see the full key exactly once: at creation. After that we only keep a hash, so a lost key is replaced, never recovered.

A sandbox key is a throwaway: mail sent with it never leaves the server and lands in a web inbox of its own. Handy for testing without touching a real domain.

Sending mail

Either html or text is required; sending both is fine and preferred. Everything else is optional.

Batch takes an array of the same objects and answers per message, so one rejected address does not sink the rest of the batch.

Domain setup

A domain has three layers that are switched on separately. Ownership first; without it the other two stay closed.

DNS spreads slowly. POST /v1/domains/:id/verify checks right now instead of waiting for the next scheduled run.

Webhooks

We POST JSON to your HTTPS URL when something happens to a message. The secret you receive at creation signs every call, so you can tell our calls from anyone else's.

// Node: check the signature before you trust the body
import crypto from "node:crypto";

const expected = crypto
  .createHmac("sha256", process.env.MAILLOG_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  return res.status(401).end();
}

Compare with timingSafeEqual and not with ===: a normal comparison stops at the first wrong character, and the time it took gives away how far someone guessed correctly.

Errors

Failures answer with a JSON body carrying statusCode and either message or a list of errors per field.

Sending

One call sends one email. The batch call takes up to a hundred at a time and answers per message, so one bad address does not sink the rest.

Domains

A domain sits above sending and receiving. Prove ownership first; sending and receiving are separate switches after that.

API keys

A key is shown once, at creation. After that we only keep a hash, so a lost key is replaced, never recovered.

Webhooks

We POST an event to your URL. Only HTTPS, and every call carries an HMAC signature made with the secret you get at creation.

Suppressions

Addresses we refuse to send to. Bounces and complaints land here on their own; you can add and remove by hand.

Inbound

Mailboxes are the buckets, addresses are the name plates on the door, and routes decide what happens to mail that arrives.

Contacts, segments and broadcasts

Contacts belong to your team, segments are filters over them, and a broadcast is one mail to a segment.

Secure portal

Instead of the message, the recipient gets a link. The body stays encrypted with us and is handed over only against a token, and optionally a PIN.

Account and monitoring

Your team, your workspaces, and what the API did.