Receiving

MiniMailer can receive email as well as send it. Incoming messages to addresses you define are parsed — headers, HTML and plain-text bodies — stored on your account, and announced to your application through a webhook. Inbound email is always free: it is never counted against your sending quota, on any tier.

Support inboxes, reply-to-app flows, and AI agents that read their own mail all build on the same three pieces: a verified domain, an inbox, and a webhook.

Point the MX record

Receiving uses the same domain you verified for sending. Among the DNS records for your domain is an inbound MX record — publish it to route the domain's incoming mail to MiniMailer. If you only ever send, skip the MX record and nothing changes; the records endpoint tells you per record what is verified.

Mail providers cache MX records, so after publishing expect up to the record's TTL before all senders see the change.

Create an inbox

An inbox binds a receiving address on your domain to your account:

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

Mail to support@mail.example.com now lands in this inbox. Create as many inboxes as you need — one per function (support@, orders@, one per agent) keeps routing in your application trivial.

What happens when mail arrives

An incoming message is parsed and stored, and an inbound_email.received webhook fires to any webhook on the domain subscribed to it. The webhook payload is a notification, not the message itself:

{
    "type": "inbound_email.received",
    "timestamp": "2026-07-15T08:30:00+00:00",
    "data": {
        "inbound_email_id": "01k02w9k3f7m8n5p6q7r8s9t0v",
        "inbox_id": "01k02w9k3f7m8n5p6q7r8s9t0w",
        "from": "customer@example.org",
        "to": "support@mail.example.com",
        "subject": "Order question",
        "status": "received",
        "received_at": "2026-07-15T08:29:58+00:00"
    }
}

Keeping bodies out of the webhook keeps deliveries small, retriable, and safe to log; fetch the full content when you actually process the message. Verify the delivery's signature like any other webhook — Webhooks →

Read the message

curl https://api.minimailer.app/inbound-emails/{inboundEmail} \
  -H "Authorization: Bearer $MINIMAILER_TOKEN" \
  -H "Accept: application/vnd.api+json"

The resource carries the parsed message: envelope fields, subject, and the HTML and plain-text bodies. To browse instead of react:

• GET /inbound-emails — everything received across your account, filterable.
• GET /inboxes/{inbox}/inbound-emails — one inbox's messages.

Reading inbound email requires the inbound:read token scope. AI agents can do the same through the MCP tools list-inbound-emails-tool and get-inbound-email-tool — same data, no HTTP client required.