Sign inGet started

Inbound email

Postilon can receive email for you: replies to your notifications, support requests, documents sent by email. Point a domain's MX record at Postilon and every message to any address there is checked, stored and sent to your webhooks as email.received.

Turn it on

Inbound works on a verified domain or a subdomain of it. Use a subdomain such as reply.acme.com: an MX record on acme.com itself moves all of its mail, including your team's mailboxes, to Postilon.

Turn it on in the dashboard under Domains → your domain → Inbound, or with the API:

curl -X PATCH https://api.postilon.com/v1/domains/dom_8hT2kLm9QpX4vZ7nR3sW \
  -H "Authorization: Bearer $POSTILON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_domain": "reply.acme.com"}'

The response's inbound_record is the record to add at your DNS provider:

Type Host Value Priority
MX reply.acme.com inbound.postilon.com 10

Postilon accepts mail for the domain as soon as inbound is on; the MX record is what makes senders deliver it here. inbound_record.status turns verified once the record can be seen in DNS. Send {"inbound_domain": ""} to turn inbound off: new mail is then refused, and emails already received stay.

An inbound domain belongs to one workspace. Names that start with bounces., feedback., fbl. or notify. cannot be used, because Postilon's mail server keeps them for bounce and complaint reports.

The email.received event

Subscribe a webhook to email.received:

{
  "id": "evt_7tY3uI9oP2aS5dF8gH1j",
  "type": "email.received",
  "created_at": "2026-10-27T09:14:02Z",
  "workspace_id": "ws_6qR9sT2uV5wX8yZ1aB4c",
  "data": {
    "inbound_id": "inb_K292Jv5t7hx1As07SLp5",
    "from": "\"Jane Doe\" <jane@example.com>",
    "to": ["support@reply.acme.com"],
    "cc": [],
    "reply_to": "",
    "recipient": "support@reply.acme.com",
    "subject": "Re: Receipt for order #123",
    "message_id": "<CAF1x9@mail.example.com>",
    "in_reply_to": "<msg_4kQ9wZ2xT7bLmN3pR8sV@acme.com>",
    "text": "Thanks, it arrived.",
    "html": "<p>Thanks, it arrived.</p>",
    "body_truncated": false,
    "attachments": [{ "filename": "photo.jpg", "content_type": "image/jpeg", "size": 48213 }],
    "auth": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },
    "spam": false,
    "received_at": "2026-10-27T09:14:02Z"
  }
}
  • recipient is the address the message was delivered to. A message sent to two addresses at your inbound domain arrives as two inbound emails, one for each.
  • text and html are included up to 256 KB together; above that both are empty, body_truncated is true, and you fetch the email for its bodies.
  • Attachments are listed without their content; download them with the API.
  • in_reply_to matches the Message-ID of the email it answers, so you can tie a reply to the email you sent.

Spam and authentication

Postilon checks SPF, DKIM and DMARC for every message and reports each as pass, fail, softfail (SPF), none, temperror or permerror. spam is true when the sender's domain failed DMARC and asks receivers to quarantine or reject such mail, which usually means someone else used that domain. Postilon still delivers these to your webhook, marked, and you decide what to do with them. There is no content filter or virus scan, so treat attachments as untrusted.

Read it with the API

Method Path Description
GET /v1/inbound List received email, newest first; q searches subject, sender and recipient.
GET /v1/inbound/{id} One email, with its headers.
GET /v1/inbound/{id}/attachments/{index} Download an attachment; index counts from 0 in attachments.
GET /v1/inbound/{id}/raw The message as received (message/rfc822).

These need a full-access API key; a key bound to a domain sees only that domain's mail. See the API reference for every field.

Limits and cost

  • Each received email costs 1 credit, like sending one. When the workspace has no credits left, or its sending is paused, Postilon answers senders with a temporary error, so they try again later.
  • Messages are limited to 10 MB.
  • Each inbound domain takes up to 60 messages a minute, and each sending server up to 300 a minute; senders over the limit are asked to retry.
  • Bodies, headers, attachments and the raw message are deleted after 30 days; the rest of the email after 90 days.
NextAPI Reference