Getting started

This guide takes you from a fresh account to your first delivered email. You will create an API token, register and verify a sending domain, and send a transactional email — all in about ten minutes plus DNS propagation time.

Create an account

Sign up at minimailer.app. Every account starts on the free Spark tier: 5,000 emails per month with a 1,000-per-day cap, no credit card required. The guided onboarding walks you through the same steps as this page.

Create an API token

In the dashboard, open API Tokens and create a token. Two decisions matter here:

• Scopes — grant only what the integration needs. For this guide: domains:write, domains:read, and emails:send.
• Duration — tokens expire after 1, 6, or 12 months. Expiry is a feature: a leaked token dies on its own.

The token value is shown once, at creation. Store it in your secrets manager, and send it as a bearer header on every request — never in a URL.

API basics

The API lives at https://api.minimailer.app — no /api or version path prefix. It speaks JSON:API: requests and responses use the application/vnd.api+json media type, and request bodies wrap attributes in a data object. A request with the wrong Content-Type is rejected with 415.

curl https://api.minimailer.app/domains \
  -H "Authorization: Bearer $MINIMAILER_TOKEN" \
  -H "Accept: application/vnd.api+json"

Register a sending domain

Email is sent from domains you own and verify. Register one, choosing a purpose of transactional or marketing — the purpose separates reputation and lets recipients' mail providers see consistent traffic per domain:

curl https://api.minimailer.app/domains \
  -X POST \
  -H "Authorization: Bearer $MINIMAILER_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "domains",
      "attributes": {
        "name": "mail.example.com",
        "purpose": "transactional"
      }
    }
  }'

A subdomain (mail.example.com, tx.example.com) is usually the right choice: it isolates email DNS from your web apex and lets you run separate transactional and marketing domains later.

Add the DNS records

The response includes the domain's identifier. Fetch the DNS records you need to publish:

curl https://api.minimailer.app/domains/{domain}/records \
  -H "Authorization: Bearer $MINIMAILER_TOKEN" \
  -H "Accept: application/vnd.api+json"

Each record comes with a record_type, name, value, and (for MX) priority. You will typically publish:

Publish them at your DNS provider, then wait. Verification runs automatically every 15 minutes — no button to press. When all records check out, the domain flips to active and a domain.verified webhook fires (if you have one configured). Each record's verified flag in the API shows you exactly which ones are still pending, which makes chasing a typo painless.

Send your first email

Once the domain is active:

curl https://api.minimailer.app/outbound-emails \
  -X POST \
  -H "Authorization: Bearer $MINIMAILER_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "outbound-emails",
      "attributes": {
        "from": "hello@mail.example.com",
        "to": "you@example.com",
        "subject": "Hello from MiniMailer",
        "html": "<p>It works.</p>",
        "text": "It works."
      },
      "relationships": {
        "domain": {
          "data": { "type": "domains", "id": "dom_01JZX8K7Q2M3N4P5R6S7T8V9W0" }
        }
      }
    }
  }'

A 201 response means the email was accepted and queued for delivery; the response body carries its identifier and status. Two things can stop a send with a 422: a validation error in the document, or a recipient on your suppression list — suppressed recipients are blocked automatically so a bad address can't hurt your reputation twice.

Where to go next

• Sending — idempotency, tracking, campaigns, and rate limits.
• Receiving — parse inbound email into your app via webhooks.
• Webhooks — delivery events, signatures, and retries.
• MCP — connect AI agents to your account without writing integration code.
• API Reference — every endpoint, generated from the OpenAPI spec.