Receiving email.

Set up receiving

• Use a domain you have verified for sending. Receiving on a subdomain such as in.example.com is the safe choice: the MX record you add replaces any existing MX for that name, and your main domain’s mailboxes keep working.
• Turn it on: in the dashboard open the domain, then Configuration, Receive email. Or with the API (below).
• Publish the MX record it shows at your DNS provider: host in.example.com, priority 10, value inbound-smtp.us-east-1.amazonaws.com. Check MX now on the same page tells you when public DNS points at us.
• Send a message to any address at that name. It shows under Received within seconds and is posted to your webhooks as email.received.

1curl -X PATCH https://mailtruss.com/api/v1/domains/$DOMAIN_ID \
2  -H "Authorization: Bearer $MAILTRUSS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{ "receiving": true }'

The email.received event

Subscribe an endpoint to email.received under Webhooks. The event is signed and retried like every other. It holds the sender, recipients, subject, threading fields, the attachment list and the authentication results, but not the bodies, so it stays small. Fetch the bodies with the API when you need them.

1{
2  "type": "email.received",(highlighted line)
3  "created_at": "2026-11-15T10:02:11.402Z",
4  "data": {
5    "email_id": "87e7fba7-e5c5-4aa6-9fa1-539eb5a62597",
6    "from": "ana.novak@fabrikam.com",
7    "from_name": "Ana Novak",
8    "to": ["support@in.example.com"],
9    "cc": [],
10    "recipients": ["support@in.example.com"],
11    "subject": "Order 1042 never arrived",
12    "message_id": "<CA+f3k2@mail.fabrikam.com>",
13    "in_reply_to": null,
14    "thread_id": "<CA+f3k2@mail.fabrikam.com>",
15    "reply_to_email_id": null,
16    "attachments": [
17      { "id": "4c0e…", "filename": "receipt-1042.pdf", "content_type": "application/pdf", "size": 48213, "inline": false, "content_id": null }
18    ],
19    "spam_verdict": "pass",
20    "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },
21    "received_at": "2026-11-15T10:02:11.000Z"
22  }
23}

1// app/api/webhooks/mailtruss/route.ts
2import { verifyWebhook } from "mailtruss";
3​
4export async function POST(req: Request) {
5  const event = await verifyWebhook(await req.text(), req.headers, process.env.MAILTRUSS_WEBHOOK_SECRET!);
6  if (event.type === "email.received") {(highlighted line)
7    // The webhook carries who, what and the attachment list. Fetch the bodies when you need them.
8    const res = await fetch(`https://mailtruss.com/api/v1/inbound/${event.data.email_id}`, {
9      headers: { Authorization: `Bearer ${process.env.MAILTRUSS_API_KEY}` },
10    });
11    const email = await res.json(); // email.text, email.html, email.headers, email.attachments
12    await createSupportTicket({ from: email.from, subject: email.subject, body: email.text });
13  }
14  return new Response(null, { status: 200 });
15}

Reading messages with the API

1curl https://mailtruss.com/api/v1/inbound?q=1042 \
2  -H "Authorization: Bearer $MAILTRUSS_API_KEY"
3​
4curl https://mailtruss.com/api/v1/inbound/87e7fba7-e5c5-4aa6-9fa1-539eb5a62597 \
5  -H "Authorization: Bearer $MAILTRUSS_API_KEY"
6​
7# one attachment, base64 in "content"
8curl https://mailtruss.com/api/v1/inbound/87e7fba7-…/attachments/4c0e… \
9  -H "Authorization: Bearer $MAILTRUSS_API_KEY"

These need a full-access API key. Sending-only keys cannot read received mail.

Replies and threads

When someone replies to an email you sent through Mailtruss, the received message carries reply_to_email_id: the ID of your sent email. Messages in the same conversation share a thread_id, built from the standard In-Reply-To and References headers, so you can show a ticket’s history without parsing headers yourself.

Safety, limits and retention

• Messages flagged as carrying a virus are dropped and never stored. Messages flagged as spam are kept and marked (spam_verdict: "fail") so you can decide.
• The authentication results (spf, dkim, dmarc) are what the receiving server found. A failed DMARC check means the sender may not be who the From line says; treat such a message with care before acting on it.
• Each received message counts as one email toward your monthly plan, like a send. Received mail is never refused for quota: it has already arrived.
• Messages up to 40 MB are accepted, attachments included.
• Received mail is kept for 30 days, then deleted with its attachments and original. Copy anything you need to keep.
• In the dashboard, a message’s HTML is shown in a sandbox with scripts off and remote images blocked until you load them, so opening it does not tell the sender.