Receiving

Receive inbound email on a verified domain: add one MX record, enable receiving, and fetch HTML, attachments, and raw downloads via the Receiving API.

Enable receiving on a domain

Receiving is off by default on every domain. Turn it on from the dashboard's domain detail page, or set capabilities.receiving to "enabled" on POST /domains or PATCH /domains/:id — the same capabilities object Resend's API uses. Sending and receiving are independent: a domain can receive without sending, or do both.

Request

curl -X PATCH https://api.irisend.com/domains/dom_4kP1qR9zL7vT2yB6wC0nS3x \
  -H "Authorization: Bearer $IRISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "capabilities": { "receiving": "enabled" } }'

ResponseJSON

{ "object": "domain", "id": "dom_4kP1qR9zL7vT2yB6wC0nS3x" }

Add the MX record

Enabling receiving adds a RECEIVING record to GET /domains/:id's records array: an MX record at @ (the domain apex) pointing at inbound-smtp.<region>.amazonaws.com with priority 10, where <region> is the domain's own sending region. It's optional — it never blocks domain verification the way the DKIM/SPF records do.

DNS (eu-west-1 example)cURL

@  IN  MX  10  inbound-smtp.eu-west-1.amazonaws.com.

If the domain already has an MX record (a real mailbox), mail is only delivered to the lowest-priority MX record it finds — adding this one alongside an existing, lower-priority record means you won't receive anything here. Use a subdomain instead (e.g. inbound.yourdomain.com) and enable receiving on that domain, or forward from your existing mail service to an address on a domain where receiving is already verified.

GET/emails/receivingList received emails

Cursor-paginated, newest first. Omits html/text — fetch a single email for the body.

Request

curl https://api.irisend.com/emails/receiving?limit=20 \
  -H "Authorization: Bearer $IRISEND_API_KEY"

ResponseJSON

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
      "to": ["[email protected]"],
      "from": "[email protected]",
      "created_at": "2026-11-03T14:37:40.951Z",
      "subject": "Question about my order",
      "bcc": [],
      "cc": [],
      "reply_to": [],
      "message_id": "<[email protected]>",
      "attachments": [
        { "id": "2a0c9ce0-3112-4728-976e-47ddcd16a318", "filename": "receipt.pdf", "content_type": "application/pdf", "content_disposition": "attachment", "content_id": null, "size": 48213 }
      ]
    }
  ]
}

GET/emails/receiving/:idRetrieve a received email

html_format controls how inline images inside html are referenced: data_uri (default) inlines them as base64 data: URIs; cid keeps the original src="cid:..." references so you can correlate them with content_id on attachments. The response always echoes the format actually served as html_format. raw.download_url is a signed, 1-hour link to the original MIME file — no API key required to fetch it.

Request

curl https://api.irisend.com/emails/receiving/4ef9a417-02e9-4d39-ad75-9611e0fcc33c \
  -H "Authorization: Bearer $IRISEND_API_KEY"

Request (cid)

curl https://api.irisend.com/emails/receiving/4ef9a417-02e9-4d39-ad75-9611e0fcc33c?html_format=cid \
  -H "Authorization: Bearer $IRISEND_API_KEY"

ResponseJSON

{
  "object": "email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "to": ["[email protected]"],
  "from": "[email protected]",
  "created_at": "2026-11-03T14:37:40.951Z",
  "subject": "Question about my order",
  "html": "<p>Hi, when will my order ship? <img src=\"data:image/png;base64,iVBORw0...\" /></p>",
  "html_format": "data_uri",
  "text": "Hi, when will my order ship?",
  "headers": { "from": "Jane <[email protected]>", "mime-version": "1.0" },
  "bcc": [],
  "cc": [],
  "reply_to": [],
  "received_for": ["[email protected]"],
  "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },
  "message_id": "<[email protected]>",
  "raw": {
    "download_url": "https://api.irisend.com/receiving/files/4ef9a417-02e9-4d39-ad75-9611e0fcc33c/raw?expires=1793456260951&signature=MfKzB3n2Rp9vQwL7xC1sH5tY",
    "expires_at": "2026-11-03T15:37:40.951Z"
  },
  "attachments": [
    { "id": "2a0c9ce0-3112-4728-976e-47ddcd16a318", "filename": "receipt.pdf", "content_type": "application/pdf", "content_disposition": "attachment", "content_id": null, "size": 48213 }
  ]
}

GET/emails/receiving/:id/attachmentsList attachments

Each attachment carries its own signed, 1-hour download_url and expires_at — re-list or re-fetch the attachment once it expires to get a fresh URL.

Request

curl https://api.irisend.com/emails/receiving/4ef9a417-02e9-4d39-ad75-9611e0fcc33c/attachments \
  -H "Authorization: Bearer $IRISEND_API_KEY"

ResponseJSON

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "2a0c9ce0-3112-4728-976e-47ddcd16a318",
      "filename": "receipt.pdf",
      "content_type": "application/pdf",
      "content_disposition": "attachment",
      "content_id": null,
      "size": 48213,
      "download_url": "https://api.irisend.com/receiving/files/4ef9a417-02e9-4d39-ad75-9611e0fcc33c/attachments/2a0c9ce0-3112-4728-976e-47ddcd16a318?expires=1793456260951&signature=MfKzB3n2Rp9vQwL7xC1sH5tY",
      "expires_at": "2026-11-03T15:37:40.951Z"
    }
  ]
}

GET/emails/receiving/:id/attachments/:aidRetrieve an attachment

Request

curl https://api.irisend.com/emails/receiving/4ef9a417-02e9-4d39-ad75-9611e0fcc33c/attachments/2a0c9ce0-3112-4728-976e-47ddcd16a318 \
  -H "Authorization: Bearer $IRISEND_API_KEY"

ResponseJSON

{
  "object": "attachment",
  "id": "2a0c9ce0-3112-4728-976e-47ddcd16a318",
  "filename": "receipt.pdf",
  "content_type": "application/pdf",
  "content_disposition": "attachment",
  "content_id": null,
  "size": 48213,
  "download_url": "https://api.irisend.com/receiving/files/4ef9a417-02e9-4d39-ad75-9611e0fcc33c/attachments/2a0c9ce0-3112-4728-976e-47ddcd16a318?expires=1793456260951&signature=MfKzB3n2Rp9vQwL7xC1sH5tY",
  "expires_at": "2026-11-03T15:37:40.951Z"
}

Downloading the raw email

raw.download_url and every attachment's download_url point at GET /receiving/files/:id/raw and GET /receiving/files/:id/attachments/:aid — public, unauthenticated routes whose ?expires=&signature= query string is the authorization, so no API key goes in the request.

Download the raw MIME filecURL

# No API key needed — the signature in the URL is the authorization.
curl -o email.eml 'https://api.irisend.com/receiving/files/4ef9a417-02e9-4d39-ad75-9611e0fcc33c/raw?expires=1793456260951&signature=MfKzB3n2Rp9vQwL7xC1sH5tY'

email.received webhook

Fires once per team an inbound email was delivered for. Like every Irisend webhook, the body carries metadata only — no html, text, headers, or attachment content — call the receiving API above to fetch those. Subscribe to it on any webhook endpoint alongside your other event types.

email.receivedJSON

{
  "type": "email.received",
  "created_at": "2026-11-03T14:37:41.112Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "created_at": "2026-11-03T14:37:40.951Z",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "bcc": [],
    "cc": [],
    "received_for": ["[email protected]"],
    "message_id": "<[email protected]>",
    "subject": "Question about my order",
    "attachments": [
      { "id": "2a0c9ce0-3112-4728-976e-47ddcd16a318", "filename": "receipt.pdf", "content_type": "application/pdf", "content_disposition": "attachment", "content_id": null }
    ]
  }
}

POST/dev/inbox/receiveSimulate an inbound email (sandbox)

Only available when EMAIL_PROVIDER=log (sandbox mode). Feeds a synthetic message straight into the same processing pipeline a real SES delivery uses — received_emails rows get created, attachments get stored, and the email.received webhook fires — without any mail actually crossing the internet or a domain needing receiving enabled at all. Returns one id per team the recipient resolved to.

Request

curl -X POST https://api.irisend.com/dev/inbox/receive \
  -H "Authorization: Bearer $IRISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Question about my order",
    "text": "Hi, when will my order ship?"
  }'

ResponseJSON

{ "data": [{ "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }] }