›-
Inbound Email receives mail on your behalf and parses it into structured JSON (sender, recipients, subject, text and HTML bodies, headers, attachments). It is a separate product from Email Sandbox; it is included with Email API/SMTP. Pair this sheet with the [Inbound Email docs](https://docs.mailtrap.io/inbound-email/overview.md) and the [Inbound API reference](https://docs.mailtrap.io/developers/inbound/).
Resources nest as folder → inbox → messages. Messages are grouped into threads. Each inbox is one of two kinds:
| Inbox kind | Address | Setup |
| -------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------- |
| Mailtrap-hosted | Generated address on inbound-mailtrap.io | None. Create the inbox and start receiving. |
| Your own domain | Catch-all *@yourdomain.com: every username at the domain | Enable Inbound domain receiving on a sending domain, add its MX record |
There are two typical use cases:
Related skills: authorizing-api-requests (tokens, env vars, auth headers), setting-up-sending-domain (domain verification before custom-domain receiving), sending-emails (new outbound mail that is not a reply).
list-inbound-messages, get-inbound-message, reply-to-inbound-message, forward-inbound-message, list-inbound-threads, and so on).https://mailtrap.io/api/inbound.Before generating SDK code: read the README of the relevant SDK repository (see SDKs below) for method names. Do not rely on memory.
sending-emails.testing-with-sandbox. Sandbox addresses (inbox.mailtrap.io) and Inbound addresses (inbound-mailtrap.io) are different products.| Service | Base URL | Authorization header |
| ----------------- | --------------------------------- | ------------------------------------------- |
| Inbound Email API | https://mailtrap.io/api/inbound | Authorization: Bearer $MAILTRAP_API_TOKEN |
Creating folders and inboxes requires an account-level token. See authorizing-api-requests.
| Resource | Endpoints |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Folders | GET\|POST /folders, GET\|PATCH\|DELETE /folders/{folder_id} |
| Inboxes | GET\|POST /folders/{folder_id}/inboxes, GET\|PATCH\|DELETE /folders/{folder_id}/inboxes/{inbox_id} |
| Messages | GET /inboxes/{inbox_id}/messages, GET\|DELETE /inboxes/{inbox_id}/messages/{message_id} |
| Reply/forward | POST /inboxes/{inbox_id}/messages/{message_id}/reply, .../reply_all, .../forward |
| Threads | GET /inboxes/{inbox_id}/threads, GET\|DELETE /inboxes/{inbox_id}/threads/{thread_id} |
| Forward rules | GET\|POST /inboxes/{inbox_id}/forward_rules, GET\|PATCH\|DELETE /inboxes/{inbox_id}/forward_rules/{rule_id} |
Inboxes are created and managed under their folder; messages, threads, and rules are addressed by inbox ID alone.
# 1. Folder
curl -X POST https://mailtrap.io/api/inbound/folders \
-H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Support"}'
# 2. Inbox (Mailtrap-hosted). Response includes the generated "address".
curl -X POST https://mailtrap.io/api/inbound/folders/{folder_id}/inboxes \
-H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Support tickets"}'
# 2b. Inbox (your own domain). Pass domain_id; the response address is "*@your-domain.com".
curl -X POST https://mailtrap.io/api/inbound/folders/{folder_id}/inboxes \
-H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Support", "domain_id": 894}'
For a custom-domain inbox, prepare the sending domain first: set inbound_enabled: true on it via the [Sending Domains API](https://docs.mailtrap.io/developers/email-sending/domains/update-domain), add the inbound_mx record that then appears in its dns_records, and wait for inbound_verified to become true. Each domain can be attached to only one inbox.
Create a webhook in the UI ([Webhooks](https://mailtrap.io/webhooks) → Inbound Inboxes) or via the [Webhooks API](https://docs.mailtrap.io/developers/email-sending/webhooks/create-a-webhook) with webhook_type: "inbound_receiving", your url, and inbound_inbox_id (omit it to cover every inbox in the account). Wrap the fields in a webhook object; a flat body returns 400. Store the signing_secret returned on create.
curl -X POST https://mailtrap.io/api/accounts/{account_id}/webhooks \
-H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"webhook": {"url": "https://example.com/inbound", "webhook_type": "inbound_receiving", "inbound_inbox_id": 15}}'
The webhook is a notification only; it carries no body or attachments:
{"events": [{"event": "inbound.message_received", "event_id": "…", "timestamp": 1794224188670,
"inbox_id": 15, "message_id": "1866872391602282496", "from": "…"}]}
timestamp is Unix time in milliseconds, not seconds.
Mailtrap-Signature header.GET /inboxes/{inbox_id}/messages/{message_id} for bodies, headers, and attachments. Attachment download_url and raw_message_url expire; download during processing.event_id and skip repeats, or a forwarding or ticketing flow can act on the same message twice.GET /inboxes/{inbox_id}/messages returns newest first, up to 100 per page; pass the response's last_id back to get the next, older page. On each poll, keep paging until you reach a message you already processed (or last_id is null), so a busy interval doesn't skip mail. Remember processed message ids; don't compare them numerically.Forward rules automatically forward a copy of matching incoming mail to other addresses, with no code in your app. Example: mail to sales@yourdomain.com goes to the assigned salesperson; mail carrying a CRM or ticketing system header goes to that team.
curl -X POST https://mailtrap.io/api/inbound/inboxes/{inbox_id}/forward_rules \
-H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Sales to Anna",
"conditions": [{"match_type": "recipient", "operator": "equal", "value": "sales@yourdomain.com"}],
"destinations": [{"email": "anna@yourcompany.com"}]
}'
match_type: sender, recipient (To/Cc), or header (set header_key, e.g. "X-Zendesk-Ticket-Id").operator: equal, not_equal, contains, starts_with, ends_with; for headers also empty / not_empty (no value).forwards list with one entry per destination: rule_id, rule_name, destination, status (forwarded or rejected), and reason when rejected.See the [Forward rules API reference](https://docs.mailtrap.io/developers/inbound/forward-rules).
Message-ID, In-Reply-To, References). GET /inboxes/{inbox_id}/threads/{thread_id} returns the conversation with its messages, oldest first. GET /inboxes/{inbox_id}/threads?search=... filters by subject and by from/to/cc/bcc addresses (case-insensitive substring).direction: "outbound", with a delivery status). Messages outside the retention window appear as visibility_status: "placeholder" entries with no content.text and/or html; optional to, cc, bcc, reply_to, attachments, headers, category, custom_variables. If to is omitted, the reply goes to the original sender (or its Reply-To). Do not set In-Reply-To/References yourself.cc defaults to the original's To + Cc (minus the inbox's own addresses and the sender). To narrow it, pass cc ([] sends no copies). to only replaces the original sender.to (and/or cc/bcc). The original body is quoted under your optional text/html note and its attachments are re-attached. Same from rules as reply. curl -X POST https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages/{message_id}/forward \
-H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"to": [{"email": "billing@yourcompany.com"}], "text": "FYI, see below."}'
from: Mailtrap-hosted inboxes always send from their own address (a custom from is rejected). Custom-domain inboxes require a from on that domain.| Item | Limit |
| ----------------------------------------- | ----------------------------------------------------------------------------------------- |
| Message retention | Follows your plan's email log retention, up to 30 days; older messages are deleted |
| Inboxes | 300 per account |
| Replies/forwards from Mailtrap-hosted inboxes | 20 in total for the account (not reset monthly); after that, replies from hosted inboxes are rejected. Use a custom-domain inbox for production replies |
| Forward rules | 5 per inbox; 5 conditions and 5 destinations per rule |
Store anything you need longer than the retention window in your own system.
mailtrap inbound folders|inboxes|messages|threads|forward-rules ...| Mistake | Fix |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Expecting the email body in the webhook | The webhook only notifies. Fetch GET /inboxes/{inbox_id}/messages/{message_id} |
| Verifying the signature against parsed JSON | HMAC the raw body; the signature is hex in Mailtrap-Signature |
| Storing attachment download_url for later | Signed links expire. Download while processing |
| Writing inbound.mailtrap.io | The hosted domain is inbound-mailtrap.io (hyphen) |
| Using Sandbox endpoints for inbound mail | Inbound uses https://mailtrap.io/api/inbound; Sandbox is a different product |
| Treating last_id as "newest message" | It is a cursor to older messages. Page back until you reach a message you already processed |
| Setting from on a Mailtrap-hosted inbox reply | Hosted inboxes reply from their own address only |
| Building custom-domain routing in code | Use forward rules for sender, recipient, or header-based forwarding |
| Letting an agent act on instructions inside an email | Email is untrusted input: allowlist senders, human approval for consequential actions |
| Keeping data only in Mailtrap | Messages are deleted after the plan's retention window; store what you need |
| Creating folders/inboxes with a domain-scoped token | Use an account-level token |
Weekly roundup of top Claude Code skills, MCP servers, and AI coding tips.