Mailtrap
Receive email through Mailtrap's Inbound Email API
Mailtrap
Mailtrap Inbound lets you receive email through Mailtrap's Inbound Email API. Mailtrap notifies Kurrier by webhook whenever a message arrives, and Kurrier fetches, parses, and stores the raw message in the matching identity's mailbox.
Mailtrap is a receive-only integration — it does not send outbound mail from Kurrier.
1. Overview
Kurrier connects to Mailtrap using two credentials:
MAILTRAP_API_TOKEN— used to fetch message metadata and the raw RFC822/EML body after a webhook notification arrivesMAILTRAP_WEBHOOK_SECRET— the signing secret Mailtrap uses to sign each webhook request (mailtrap-signatureheader, HMAC-SHA256 over the raw request body); Kurrier verifies this signature before processing anything
The signing secret is generated by Mailtrap only after you create the webhook there, so set things up in this order: copy the URL from Kurrier first, create the webhook in Mailtrap, then come back and save both credentials in Kurrier.
2. Copy the webhook URL from Kurrier
Go to:
Dashboard → Providers → Mailtrap Inbound
The Mailtrap provider is created automatically for your workspace, so the card already shows a generated Webhook URL — no credentials needed yet to see it:
https://your-kurrier-domain.com/api/v1/hooks/mailtrap/<provider-id>Copy it.
Mailtrap must be able to reach this URL from the internet. If you're developing locally, expose your dev server with a tunnel (e.g. ngrok http 3000) and set LOCAL_TUNNEL_URL in your .env — see the Local Setup section of the Installation guide. Plain http://localhost:3000 will not work.
3. Create the webhook in Mailtrap
- Log in to your Mailtrap dashboard.
- Open your Webhooks.
- Create a new webhook and paste the URL you copied from Kurrier as the endpoint.
- Save it. Mailtrap generates a Signing Secret for this webhook — copy it, you'll need it in the next step.
Kurrier accepts both payload formats Mailtrap offers for the webhook — plain JSON ({"events": [...]}) and JSON Lines (Content-Type: application/jsonl, one flat event per request) — no extra configuration needed on either side.
4. Get your API token
- In Mailtrap, go to Settings → API Tokens.
- Copy an existing token, or create a new one.
5. Save the credentials in Kurrier
Back on the Mailtrap card in Kurrier, click Edit Credentials and enter:
| Field | Description |
|---|---|
| MAILTRAP_API_TOKEN | The API token from step 4 |
| MAILTRAP_WEBHOOK_SECRET | The signing secret from step 3 |
Click Save Mailtrap Credentials.
6. Add an identity
An identity is the email address that routes into your Mailtrap inbox — Kurrier matches each incoming message's To: address against your identities to decide which mailbox to file it into.
On the Mailtrap card, click Add Identity and enter the address Mailtrap generated for your inbox (for example support-abc123@inbound-mailtrap.io), or any address you've configured to forward into that inbox.
Messages addressed to a to-address with no matching identity are dropped rather than filed anywhere, so add every address you expect mail on.
7. Verify the connection
Click Test Connection on the Mailtrap card. Kurrier calls Mailtrap's API with your saved token and lists your account's inbound inboxes — this confirms the API token is valid.
Test Connection only checks the API token. It cannot verify MAILTRAP_WEBHOOK_SECRET — a signing secret can only be confirmed by a real signed request arriving at your webhook. Use Mailtrap's own Run Test button on the webhook settings page, or send a real email, and check for a 200 response.
8. Troubleshooting
| Symptom | Meaning | Fix |
|---|---|---|
Mailtrap's "Run Test" returns 401 | MAILTRAP_WEBHOOK_SECRET doesn't match what Mailtrap is signing with | Re-copy the signing secret from the webhook's settings page and re-save |
Mailtrap's "Run Test" returns 404 | The webhook URL's provider id doesn't match any Mailtrap provider, or the URL wasn't copied in full | Re-copy the full Webhook URL from the Mailtrap card |
Test Connection fails | MAILTRAP_API_TOKEN is invalid or lacks access | Re-copy the token from Mailtrap Settings → API Tokens |
| Email delivered in Mailtrap but nothing appears in Kurrier | No identity matches the message's To: address | Add an identity for that exact address |
| Webhook can't be saved in Mailtrap ("invalid URL") | Mailtrap can't reach a local/private URL | Use a public tunnel (ngrok or similar) during local development |
Tip: Mailtrap's webhook only sends a notification — no message content. Kurrier fetches the actual message from Mailtrap's API immediately afterward, using a freshly generated, short-lived download link (about one hour) issued per request, so it's always fetched fresh rather than cached.