Email webhooks

Webhooks are a feature that allow you to receive email payloads sent directly to your server in response to predefined events. Webhooks can be attached to inboxes or to your account.

webhooks

Motivation

Why use webhooks? Webhooks let you respond to events when they occur. They remove the need to continually poll the MailSlurp API to request the latest emails. This mitigates rate-limiting errors. Webhooks also enable graceful error handling because they are backed by a queue and can be retried over time when your server is down or throwing exceptions.

Delivery and idempotency

MailSlurp webhooks are guaranteed to be delivered at least once - this means the same payload could be sent to your endpoint twice. For this reason it is important to use the messageId unique to all payloads to avoid processing a message twice. Save this idempotency key on your server and perform a lookup when new messages arrive and discard those you have already processed.

Sent headers

Each webhook is sent via HTTP with the following headers:

Header	Example	Description
x-from	api.mailslurp.com	Header identifying the server sending the webhook. Is always equal to api.mailslurp.com
x-event	NEW_EMAIL	Webhook event type for the payload. What triggered the event.
x-signature	sig-29s033if2	Signature for the event. Use this with webhook signature verify endpoint to verify payload.
x-message-id	38547638	Unique ID for the webhook payload. Use this ID to avoid processing a webhook multiple times.
Authorization	Basic xdsf924	Basic authentication. Only set if your webhook was created with a username and password.

Setup your server

To receive webhook payloads you must expose a public HTTP/S endpoint on your server that responses with a 200-299 status code. If you respond with a 3xx or error code the payload will be placed on a queue and retried with a backoff period.

Example handler

You can use any framework or server you wish to handle MailSlurp webhooks. Here is an example using NodeJS to illustrate:

const express = require("express");
const app = express.createServer();
app.use(express.bodyParser());

app.post("/my-webhook-endpoint", (request, response) => {
  // access the data on request body and take action
  console.log(request.body.inboxId);

  // return a 2xx status code so MailSlurp knows you received it
  response.sendStatus(200);
});

app.listen(80);

Verify webhook signature

MailSlurp sends an x-signature header that can be used with the x-message-id header to verify a webhook payload.

const signature = request.header("x-signature")
const messageId = request.header("x-message-id")
const { isValid } = await mailslurp.webhookController.verifyWebhookSignature({
    verifyWebhookSignatureOptions: { signature, messageId },
});
expect(isValid).toBeTruthy();

Strong types for payloads

Each MailSlurp library contains webhook payload types that extend AbstractWebhookPayload. Use the eventName property or the x-event header to cast the event to an appropriate concrete type.

// every webhook payload extends abstract payload
function handleWebhookPayload(body: AbstractWebhookPayload) {
    // use the event name to cast the event
    if (body.eventName === AbstractWebhookPayloadEventNameEnum.NEW_EMAIL) {
      const event = body.eventName as unknown as WebhookNewEmailPayload
      // now access event properties and process
      console.log(event.emailId)
    } else {
      throw new Error("Unexpect webhook event")
    }
}

Create and manage webhooks

Webhooks can be created in the MailSlurp dashboard or using the API WebhookController. Webhooks can be attached to an inbox or created without one depending on the event type.

Create email webhook

Here is an example creating an inbox related webhook using the MailSlurp Javascript client.

mailslurp.webhookController.createWebhook(inboxId, {
    url: "https://my-server.com/webhooks/new-email",
    eventName: "NEW_EMAIL"
})

Or for account based events such as BOUNCE pass null for the inbox ID:

mailslurp.webhookController.createWebhook(null, {
  url: "https://my-server.com/webhooks/bounce",
  eventName: "BOUNCE"
})

Authentication

If you with to secure your endpoint you can add basic authentication headers to the request by specifying a username and password upon webhook creation. These will be passed in an Authorization header with the value Basic <credentials> where the credentials are a base64 encoded string containing the username and password separated by a colon.

Results and redrive

You can view webhook delivery results in the dashboard webhooks page. Webhooks are backed by a queue system that will retry payload posting when error response codes are returned.

webhook history

Event types

Each webhook you create responds to a single event type. Webhooks are triggered when the webhook's inbox your account triggers the corresponding event. MailSlurp will send a JSON payload to the URL specified for your webhook via HTTP/S POST. Each event has a different payload as documented below.

BOUNCE

This payload is sent via HTTP POST to your webhook URL when an email bounces. This means the recipient you emailed rejected your message. You must avoid emailing the recipient again to protect your account reputation.