Receive emails and attachments with Webhook Push

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 accross many addresses.

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

About webhooks

Email API webhook

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:

  • NEW_EMAIL (or EMAIL_RECEIVED) - triggered when an inbox receives a new email
  • NEW_CONTACT - triggered when a new recipient or sender is encountered on an incoming email
  • NEW_ATTACHMENT - 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.

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.

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

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 messageId to differentiate between events. Store the messageId 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.

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

/**
 * define your endpoint
 * here your webhook url should include the full protocol and domain.
 * i.e.: https://myserver.com/my-webhook-endpoint
 */
app.post("/my-webhook-endpoint", function (request, response) {
  // access the data on request body
  console.log(request.body.inboxId);

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

app.listen(80);

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

NEW_EMAIL

This payload is sent via HTTP POST to your webhook URL when a new email is received by MailSlurp that matches optional filters. You can provide filters when creating the webhook. Use the EmailController with the emailId to fetch the body of the email or headers. To receive attachments or use the NEW_ATTACHMENT webhook.

NameTypeNullableDescription
messageIdjava.lang.StringfalseIdempotent message ID. Store this ID locally or in a database to prevent message duplication.
webhookIdjava.util.UUIDfalseID of webhook entity being triggered
eventNamecom.mailslurp.lib.dtos.webhook.WebhookEventNamefalseName of the event type webhook is being triggered for.
webhookNamejava.lang.StringtrueName of the webhook being triggered
inboxIdjava.util.UUIDfalseId of the inbox that received an email
emailIdjava.util.UUIDfalseID of the email that was received. Use this ID for fetching the email with the EmailController.
createdAtjava.time.InstantfalseDate time of event creation
tojava.util.List<java.lang.String>falseList of To recipient email addresses that the email was addressed to. See recipients object for names.
fromjava.lang.StringfalseWho the email was sent from. An email address - see fromName for the sender name.
ccjava.util.List<java.lang.String>falseList of CC recipients email addresses that the email was addressed to. See recipients object for names.
bccjava.util.List<java.lang.String>falseList of BCC recipients email addresses that the email was addressed to. See recipients object for names.
subjectjava.lang.StringtrueThe subject line of the email message as specified by SMTP subject header
attachmentMetaDatasjava.util.List<com.mailslurp.lib.dtos.attachment.AttachmentMetaData>falseList of attachment meta data objects if attachments present

NEW_CONTACT

Triggered when a new contact is found. If the addNewContacts setting is enabled for your account MailSlurp will parse any new recipients or senders for a received email and save them to your contacts. Saved contacts are sent via HTTP POST to your webhook URL using this payload.

NameTypeNullableDescription
messageIdjava.lang.StringfalseIdempotent message ID. Store this ID locally or in a database to prevent message duplication.
webhookIdjava.util.UUIDfalseID of webhook entity being triggered
webhookNamejava.lang.StringtrueName of the webhook being triggered
eventNamecom.mailslurp.lib.dtos.webhook.WebhookEventNamefalseName of the event type webhook is being triggered for.
contactIdjava.util.UUIDfalse
groupIdjava.util.UUIDfalse
firstNamejava.lang.Stringfalse
lastNamejava.lang.Stringfalse
companyjava.lang.Stringfalse
primaryEmailAddressjava.lang.Stringfalse
emailAddressesjava.util.Set<java.lang.String>false
tagsjava.util.Set<java.lang.String>false
metaDatacom.fasterxml.jackson.databind.JsonNodefalse
optOutjava.lang.Booleanfalse
createdAtjava.time.Instantfalse

NEW_ATTACHMENT

When a new email is received by MailSlurp the attachments are parsed and saved to storage. If a NEW_ATTACHMENT webhook is enabled for the receiving inbox this payload will be sent via HTTP POST to the webhooks URL. An attachment ID, name, and meta data are included. Use the attachmentId with the AttachmentController to access the file content as byte stream or base64 encoded string to download the file.

NameTypeNullableDescription
messageIdjava.lang.StringfalseIdempotent message ID. Store this ID locally or in a database to prevent message duplication.
webhookIdjava.util.UUIDfalseID of webhook entity being triggered
webhookNamejava.lang.StringtrueName of the webhook being triggered
eventNamecom.mailslurp.lib.dtos.webhook.WebhookEventNamefalseName of the event type webhook is being triggered for.
attachmentIdjava.lang.StringfalseID of attachment. Use the AttachmentController to
namejava.lang.StringfalseFilename of the attachment if present
contentTypejava.lang.StringfalseContent type of attachment such as ‘image/png’ or ‘application/pdf
contentLengthlongfalseSize of attachment in bytes

EMAIL_READ

This payload is sent via HTTP POST to your webhook URL when an email is read. This is when the email is requested from the API in full format or is viewed in the dashboard

NameTypeNullableDescription
messageIdjava.lang.StringfalseIdempotent message ID. Store this ID locally or in a database to prevent message duplication.
webhookIdjava.util.UUIDfalseID of webhook entity being triggered
eventNamecom.mailslurp.lib.dtos.webhook.WebhookEventNamefalseName of the event type webhook is being triggered for.
webhookNamejava.lang.StringtrueName of the webhook being triggered
emailIdjava.util.UUIDfalseID of the email that was received. Use this ID for fetching the email with the EmailController.
inboxIdjava.util.UUIDfalseId of the inbox that received an email
emailIsReadbooleanfalseIs the email read
createdAtjava.time.InstantfalseDate time of event creation

EMAIL_OPENED

This payload is sent via HTTP POST to your webhook URL when an email containing a tracking pixel is opened. Triggered for pixels in emails sent from the inbox that the webhook is attached to

NameTypeNullableDescription
messageIdjava.lang.StringfalseIdempotent message ID. Store this ID locally or in a database to prevent message duplication.
webhookIdjava.util.UUIDfalseID of webhook entity being triggered
eventNamecom.mailslurp.lib.dtos.webhook.WebhookEventNamefalseName of the event type webhook is being triggered for.
webhookNamejava.lang.StringtrueName of the webhook being triggered
inboxIdjava.util.UUIDfalseId of the inbox that received an email
pixelIdjava.util.UUIDfalseID of the tracking pixel
sentEmailIdjava.util.UUIDfalseID of sent email
recipientjava.lang.StringfalseEmail address for the recipient of the tracking pixel
createdAtjava.time.InstantfalseDate time of event creation

EMAIL_RECEIVED

Legacy webhook payload for EMAIL_RECEIVED webhooks or webhooks with no defined event type. Use the NEW_EMAIL webhook instead as it sends you a full EmailDto.

NameTypeNullableDescription
messageIdjava.lang.StringfalseIdempotent message ID. Store this ID locally or in a database to prevent message duplication.
webhookIdjava.util.UUIDfalseID of webhook entity being triggered
webhookNamejava.lang.StringtrueName of the webhook being triggered
eventNamecom.mailslurp.lib.dtos.webhook.WebhookEventNamefalseName of the event type webhook is being triggered for.
inboxIdjava.util.UUIDfalseId of the inbox that received an email
emailIdjava.util.UUIDfalseID of the email that was received. Use this ID for fetching the email with the EmailController.
createdAtjava.time.InstantfalseDate time of event creation
tojava.util.List<java.lang.String>falseList of To recipient email addresses that the email was addressed to. See recipients object for names.
fromjava.lang.StringfalseWho the email was sent from. An email address - see fromName for the sender name.
ccjava.util.List<java.lang.String>falseList of CC recipients email addresses that the email was addressed to. See recipients object for names.
bccjava.util.List<java.lang.String>falseList of BCC recipients email addresses that the email was addressed to. See recipients object for names.
subjectjava.lang.StringtrueThe subject line of the email message as specified by SMTP subject header
attachmentMetaDatasjava.util.List<com.mailslurp.lib.dtos.attachment.AttachmentMetaData>falseList of attachment meta data objects if attachments present