Email webhooks enable the forwarding of incoming emails to custom server endpoints. Webhooks are configured so that mailservers can forward received emails directly to subscribing servers. This allows your system to respond to emails and attachments as they arrive without long-polling or continual checking of email inboxes.

Webhook features

MailSlurp provides many ways to receive an email. One popular method is using webhooks. Webhooks enable you to receive emails and attachments directly to your server when they arrive without the need to call MailSlurp directly. Webhooks must be created using the dashboard or API and assigned to an inbox. You can attach a single webhook to multiple inboxes if you wish to receive emails and attachments across many addresses.

See the Webhoook developer documentation for model schemas, event types and examples.

How webhooks work

Email webhook API

Every MailSlurp inbox can be connected to a webhook. Webhooks are rules that forward a payload to an HTTP endpoint that is publicly accessible on your server or system. MailSlurp will post a JSON payload to your server when a webhook event is triggered.

Webhook event types

Webhooks can be setup to trigger for different events:

  • (or ) - triggered when an inbox receives a new email
  • - triggered when a new recipient or sender is encountered on an incoming email
  • - triggered when a new attachment is received in an email

Payloads for webhooks

Each Webhook has an associated triggering event. The event type determines what type of JSON payload will be sent to your server.

  • - sent when a webhook is triggered.
  • - sent when a webhook is triggered.
  • - sent when a webhook is triggered.

Webhook response

When webhooks are triggered a JSON payload will be sent via HTTP POST to your server URL. Your server must return a 200 or 201 response status within 30 seconds. If so the webhook is marked as successfully processed. If not the webhook will be placed in a queue and retried until a success is obtained.

Creating a webhook

First create an inbox. Then you can create a webhook online in the webapp or using the API or SDKs. You must define a URL for the webhook that can be called by MailSlurp servers using HTTP POST method.

Use the WebhookControllerAPI endpoints or the methods available in the SDKs to create and manage webhooks.

You can also create a webhook using the dashboard:

email webhook

You can share a webhook across multiple inboxes by attaching the same webhook ID to each new inbox you create.

Monitoring webhook results

In the MailSlurp dashboard you can monitor your webhook history to see how your webhooks are being handled.

email testing

Testing webhooks

We recommend you use a service like ngrok.io to test webhooks. It allows you to tunnel a localhost to a publicly accessible url so that MailSlurp can call your local test machine.

Idempotency

Webhooks are guaranteed to be sent at least once. Efforts are made to deliver only once but they may occasionally be sent multiple times due to the distribute queue system used. To mitigate duplication use the event to differentiate between events. Store the and acknowledge but do not process the event if you encounter the same ID again.

Usage

Expose an endpoint on your server and create a MailSlurp webhook using the URL. Listen for incoming events and return a 200.

NodeJS Express example

Let's see how a webhook fits together with an example Javascript server using Express.

Note: you can use any framework or language you like with webhooks.

Using SDK models for deserialization

The WebhookPayload class is included in the MailSlurp SDKs and can be used to deserialize the webhook payload. For instance:

Webhook Payloads

See the developer webhook documentation for payload schemas.