Receiving mail

Mail sent to your verified domains is stored and readable through the API. Use it for reply handling, support inboxes, and anything that needs to act on what a person sent back.

React to arrival

Subscribe an endpoint to email.received and we post as soon as a message is stored.

{
  "id": "evt_01J8K2P...",
  "type": "email.received",
  "created_at": "2026-08-19T14:52:00Z",
  "data": {
    "inbound_id": "9c1f...",
    "domain_id": "3a7b...",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Re: your order",
    "message_id": "<[email protected]>",
    "spam_score": 0.4,
    "spam_action": "no_action",
    "size_bytes": 18422,
    "attachment_count": 1,
    "received_at": "2026-08-19T14:52:00Z"
  }
}

The payload carries metadata, never the body. That is on purpose: webhook payloads are stored so they can be replayed, and putting message content in one would mean storing your correspondents' mail in plain text. The body stays encrypted at rest and is fetched over the API when you want it.

Note inbound_id rather than email_id. This event is not about a message you sent, so handlers that assume email_id is always present need a branch for it.

Read the content

curl https://api.epostix.com/v1/inbound/{inbound_id}/content \
  -H "Authorization: Bearer $EPOSTIX_API_KEY"

Returns the parsed html, text and headers, decrypted on read.

For the original message exactly as it arrived, ask for the raw form:

curl https://api.epostix.com/v1/inbound/{inbound_id}/raw \
  -H "Authorization: Bearer $EPOSTIX_API_KEY" \
  -o message.eml

That is the RFC 5322 source, suitable for feeding to your own parser or storing for audit. It is the right choice if you care about headers we do not surface, or about signatures.

Spam verdicts

Every message carries spam_score and spam_action. Filter on it when listing:

curl "https://api.epostix.com/v1/inbound?spam_action=quarantine" \
  -H "Authorization: Bearer $EPOSTIX_API_KEY"

Messages the filter refused do not fire email.received. They are stored so you can review them, but announcing them would mean asking your integration to act on mail we already judged unwanted. Poll the list for those, or release one and handle it from there:

curl -X POST https://api.epostix.com/v1/inbound/{inbound_id}/release \
  -H "Authorization: Bearer $EPOSTIX_API_KEY"

Several recipients

to is an array. A message addressed to two of your addresses records both, so a handler that reads only the first will mis-route mail sent to a team alias and an individual at once.

Attachments

attachment_count tells you how many a message has, and the content endpoint lists their filenames, types and sizes. Fetching attachment bytes individually is not available yet; take the raw message and parse it if you need the file itself.

What this is not

This is the API view. The dashboard's inbound screen is the human view of the same mail, including the quarantine review flow.