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.
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.
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.
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.
Property | Type | Description |
---|---|---|
messageId | String | Idempotent message ID. Store this ID locally or in a database to prevent message duplication. |
webhookId | UUID | ID of webhook entity being triggered |
eventName | WebhookEventName | Name of the event type webhook is being triggered for. |
webhookName | String | Name of the webhook being triggered |
bounceId | UUID | ID of the bounce email record. Use the ID with the bounce controller to view more information |
sentToRecipients | List | |
sender | String | |
bounceRecipients | List | Email addresses that resulted in a bounce or email being rejected. Please save these recipients and avoid emailing them in the future to maintain your reputation. |
{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:webhook:payload:WebhookBouncePayload","properties":{"messageId":{"type":"string","required":true,"description":"Idempotent message ID. Store this ID locally or in a database to prevent message duplication."},"webhookId":{"type":"string","required":true,"description":"ID of webhook entity being triggered","format":"uuid"},"eventName":{"type":"string","required":true,"description":"Name of the event type webhook is being triggered for.","enum":["EMAIL_RECEIVED","NEW_EMAIL","NEW_CONTACT","NEW_ATTACHMENT","EMAIL_OPENED","EMAIL_READ","BOUNCE","BOUNCE_RECIPIENT"]},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"bounceId":{"type":"string","required":true,"description":"ID of the bounce email record. Use the ID with the bounce controller to view more information","format":"uuid"},"sentToRecipients":{"type":"array","items":{"type":"string"}},"sender":{"type":"string","required":true},"bounceRecipients":{"type":"array","description":"Email addresses that resulted in a bounce or email being rejected. Please save these recipients and avoid emailing them in the future to maintain your reputation.","items":{"type":"string"}}}}
BOUNCE_RECIPIENT
This payload is sent via HTTP POST to your webhook URL for each new recipient bounce. This means the recipient you emailed rejected your message. You must avoid emailing the recipient again to protect your account reputation.
Property | Type | Description |
---|---|---|
messageId | String | Idempotent message ID. Store this ID locally or in a database to prevent message duplication. |
webhookId | UUID | ID of webhook entity being triggered |
eventName | WebhookEventName | Name of the event type webhook is being triggered for. |
webhookName | String | Name of the webhook being triggered |
recipient | String | Email address that caused a bounce. Make note of the address and try not to message it again to preserve your reputation. |
{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:webhook:payload:WebhookBounceRecipientPayload","properties":{"messageId":{"type":"string","required":true,"description":"Idempotent message ID. Store this ID locally or in a database to prevent message duplication."},"webhookId":{"type":"string","required":true,"description":"ID of webhook entity being triggered","format":"uuid"},"eventName":{"type":"string","required":true,"description":"Name of the event type webhook is being triggered for.","enum":["EMAIL_RECEIVED","NEW_EMAIL","NEW_CONTACT","NEW_ATTACHMENT","EMAIL_OPENED","EMAIL_READ","BOUNCE","BOUNCE_RECIPIENT"]},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"recipient":{"type":"string","required":true,"description":"Email address that caused a bounce. Make note of the address and try not to message it again to preserve your reputation."}}}
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.
Property | Type | Description |
---|---|---|
messageId | String | Idempotent message ID. Store this ID locally or in a database to prevent message duplication. |
webhookId | UUID | ID of webhook entity being triggered |
eventName | WebhookEventName | Name of the event type webhook is being triggered for. |
webhookName | String | Name of the webhook being triggered |
inboxId | UUID | Id of the inbox that received an email |
emailId | UUID | ID of the email that was received. Use this ID for fetching the email with the EmailController . |
createdAt | Instant | Date time of event creation |
to | List | List of To recipient email addresses that the email was addressed to. See recipients object for names. |
from | String | Who the email was sent from. An email address - see fromName for the sender name. |
cc | List | List of CC recipients email addresses that the email was addressed to. See recipients object for names. |
bcc | List | List of BCC recipients email addresses that the email was addressed to. See recipients object for names. |
subject | String | The subject line of the email message as specified by SMTP subject header |
attachmentMetaDatas | List | List of attachment meta data objects if attachments present |
{"messageId":"test-message-id","webhookId":"83f3b247-a14e-4564-b62d-074405d67cf8","eventName":"NEW_EMAIL","webhookName":"test-webhook","inboxId":"b256812f-11fb-40f1-8cf4-c5c9e0eb522d","emailId":"760982f5-6912-4741-8f1e-d3404dbcf990","createdAt":"1970-01-01T00:00:00.000Z","to":["to@address.com"],"from":"from@address.com","cc":[],"bcc":[],"subject":"test-subject","attachmentMetaDatas":[{"name":"file-name","contentType":"text/plain","contentLength":123,"id":"attachment-id"}]}
{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:webhook:payload:WebhookNewEmailPayload","properties":{"messageId":{"type":"string","required":true,"description":"Idempotent message ID. Store this ID locally or in a database to prevent message duplication."},"webhookId":{"type":"string","required":true,"description":"ID of webhook entity being triggered","format":"uuid"},"eventName":{"type":"string","required":true,"description":"Name of the event type webhook is being triggered for.","enum":["EMAIL_RECEIVED","NEW_EMAIL","NEW_CONTACT","NEW_ATTACHMENT","EMAIL_OPENED","EMAIL_READ","BOUNCE","BOUNCE_RECIPIENT"]},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"inboxId":{"type":"string","required":true,"description":"Id of the inbox that received an email","format":"uuid"},"emailId":{"type":"string","required":true,"description":"ID of the email that was received. Use this ID for fetching the email with the `EmailController`.","format":"uuid"},"createdAt":{"type":"any","required":true,"description":"Date time of event creation"},"to":{"type":"array","required":true,"description":"List of `To` recipient email addresses that the email was addressed to. See recipients object for names.","items":{"type":"string"}},"from":{"type":"string","required":true,"description":"Who the email was sent from. An email address - see fromName for the sender name."},"cc":{"type":"array","required":true,"description":"List of `CC` recipients email addresses that the email was addressed to. See recipients object for names.","items":{"type":"string"}},"bcc":{"type":"array","required":true,"description":"List of `BCC` recipients email addresses that the email was addressed to. See recipients object for names.","items":{"type":"string"}},"subject":{"type":"string","description":"The subject line of the email message as specified by SMTP subject header"},"attachmentMetaDatas":{"type":"array","required":true,"description":"List of attachment meta data objects if attachments present","items":{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:attachment:AttachmentMetaData","properties":{"name":{"type":"string","required":true},"contentType":{"type":"string","required":true},"contentLength":{"type":"integer","required":true},"id":{"type":"string","required":true}}}}}}
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.
Property | Type | Description |
---|---|---|
messageId | String | Idempotent message ID. Store this ID locally or in a database to prevent message duplication. |
webhookId | UUID | ID of webhook entity being triggered |
webhookName | String | Name of the webhook being triggered |
eventName | WebhookEventName | Name of the event type webhook is being triggered for. |
contactId | UUID | |
groupId | UUID | |
firstName | String | |
lastName | String | |
company | String | |
primaryEmailAddress | String | |
emailAddresses | List | |
tags | List | |
metaData | JsonNode | |
optOut | Boolean | |
createdAt | Instant |
{"messageId":"test-message-id","webhookId":"5b21f8b2-c88d-4274-9c02-c6bf4c7824d5","webhookName":"webhook-name","eventName":"NEW_CONTACT","contactId":"7422d680-4232-4607-bfd2-61d7f55abba4","groupId":"670a81a1-a18e-4d29-a18a-e330d298e788","firstName":"first-name","lastName":"last-name","company":"company","primaryEmailAddress":"test@address.com","emailAddresses":["test@address.com"],"tags":[],"metaData":null,"optOut":false,"createdAt":"1970-01-01T00:00:00.000Z"}
{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:webhook:payload:WebhookNewContactPayload","properties":{"messageId":{"type":"string","required":true,"description":"Idempotent message ID. Store this ID locally or in a database to prevent message duplication."},"webhookId":{"type":"string","required":true,"description":"ID of webhook entity being triggered","format":"uuid"},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"eventName":{"type":"string","required":true,"description":"Name of the event type webhook is being triggered for.","enum":["EMAIL_RECEIVED","NEW_EMAIL","NEW_CONTACT","NEW_ATTACHMENT","EMAIL_OPENED","EMAIL_READ","BOUNCE","BOUNCE_RECIPIENT"]},"contactId":{"type":"string","required":true,"format":"uuid"},"groupId":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"primaryEmailAddress":{"type":"string"},"emailAddresses":{"type":"array","required":true,"items":{"type":"string"}},"tags":{"type":"array","required":true,"items":{"type":"string"}},"metaData":{"type":"any"},"optOut":{"type":"boolean"},"createdAt":{"type":"any","required":true}}}
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.
Property | Type | Description |
---|---|---|
messageId | String | Idempotent message ID. Store this ID locally or in a database to prevent message duplication. |
webhookId | UUID | ID of webhook entity being triggered |
webhookName | String | Name of the webhook being triggered |
eventName | WebhookEventName | Name of the event type webhook is being triggered for. |
attachmentId | String | ID of attachment. Use the AttachmentController to |
name | String | Filename of the attachment if present |
contentType | String | Content type of attachment such as 'image/png' or 'application/pdf |
contentLength | long | Size of attachment in bytes |
{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:webhook:payload:WebhookNewAttachmentPayload","properties":{"messageId":{"type":"string","required":true,"description":"Idempotent message ID. Store this ID locally or in a database to prevent message duplication."},"webhookId":{"type":"string","required":true,"description":"ID of webhook entity being triggered","format":"uuid"},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"eventName":{"type":"string","required":true,"description":"Name of the event type webhook is being triggered for.","enum":["EMAIL_RECEIVED","NEW_EMAIL","NEW_CONTACT","NEW_ATTACHMENT","EMAIL_OPENED","EMAIL_READ","BOUNCE","BOUNCE_RECIPIENT"]},"attachmentId":{"type":"string","required":true,"description":"ID of attachment. Use the `AttachmentController` to"},"name":{"type":"string","required":true,"description":"Filename of the attachment if present"},"contentType":{"type":"string","required":true,"description":"Content type of attachment such as 'image/png' or 'application/pdf"},"contentLength":{"type":"integer","required":true,"description":"Size 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
Property | Type | Description |
---|---|---|
messageId | String | Idempotent message ID. Store this ID locally or in a database to prevent message duplication. |
webhookId | UUID | ID of webhook entity being triggered |
eventName | WebhookEventName | Name of the event type webhook is being triggered for. |
webhookName | String | Name of the webhook being triggered |
emailId | UUID | ID of the email that was received. Use this ID for fetching the email with the EmailController . |
inboxId | UUID | Id of the inbox that received an email |
emailIsRead | boolean | Is the email read |
createdAt | Instant | Date time of event creation |
{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:webhook:payload:WebhookEmailReadPayload","properties":{"messageId":{"type":"string","required":true,"description":"Idempotent message ID. Store this ID locally or in a database to prevent message duplication."},"webhookId":{"type":"string","required":true,"description":"ID of webhook entity being triggered","format":"uuid"},"eventName":{"type":"string","required":true,"description":"Name of the event type webhook is being triggered for.","enum":["EMAIL_RECEIVED","NEW_EMAIL","NEW_CONTACT","NEW_ATTACHMENT","EMAIL_OPENED","EMAIL_READ","BOUNCE","BOUNCE_RECIPIENT"]},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"emailId":{"type":"string","required":true,"description":"ID of the email that was received. Use this ID for fetching the email with the `EmailController`.","format":"uuid"},"inboxId":{"type":"string","required":true,"description":"Id of the inbox that received an email","format":"uuid"},"emailIsRead":{"type":"boolean","required":true,"description":"Is the email read"},"createdAt":{"type":"any","required":true,"description":"Date 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
Property | Type | Description |
---|---|---|
messageId | String | Idempotent message ID. Store this ID locally or in a database to prevent message duplication. |
webhookId | UUID | ID of webhook entity being triggered |
eventName | WebhookEventName | Name of the event type webhook is being triggered for. |
webhookName | String | Name of the webhook being triggered |
inboxId | UUID | Id of the inbox that received an email |
pixelId | UUID | ID of the tracking pixel |
sentEmailId | UUID | ID of sent email |
recipient | String | Email address for the recipient of the tracking pixel |
createdAt | Instant | Date time of event creation |
{"messageId":"test-message-id","webhookId":"9237f10c-31ca-4a7b-a294-a3ab00580de0","eventName":"EMAIL_OPENED","webhookName":"test-webhook-name","inboxId":"34275ae9-2dd7-4c54-a846-30d9a230f323","pixelId":"db9cabaf-495f-49d6-a16d-77cfa161785d","sentEmailId":"d44a0dc0-318f-42df-aef3-ffc46e6d82a2","recipient":"test@recipient.com","createdAt":"1970-01-01T00:00:00.000Z"}
{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:webhook:payload:WebhookEmailOpenedPayload","properties":{"messageId":{"type":"string","required":true,"description":"Idempotent message ID. Store this ID locally or in a database to prevent message duplication."},"webhookId":{"type":"string","required":true,"description":"ID of webhook entity being triggered","format":"uuid"},"eventName":{"type":"string","required":true,"description":"Name of the event type webhook is being triggered for.","enum":["EMAIL_RECEIVED","NEW_EMAIL","NEW_CONTACT","NEW_ATTACHMENT","EMAIL_OPENED","EMAIL_READ","BOUNCE","BOUNCE_RECIPIENT"]},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"inboxId":{"type":"string","required":true,"description":"Id of the inbox that received an email","format":"uuid"},"pixelId":{"type":"string","required":true,"description":"ID of the tracking pixel","format":"uuid"},"sentEmailId":{"type":"string","required":true,"description":"ID of sent email","format":"uuid"},"recipient":{"type":"string","required":true,"description":"Email address for the recipient of the tracking pixel"},"createdAt":{"type":"any","required":true,"description":"Date 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.
Property | Type | Description |
---|---|---|
messageId | String | Idempotent message ID. Store this ID locally or in a database to prevent message duplication. |
webhookId | UUID | ID of webhook entity being triggered |
webhookName | String | Name of the webhook being triggered |
eventName | WebhookEventName | Name of the event type webhook is being triggered for. |
inboxId | UUID | Id of the inbox that received an email |
emailId | UUID | ID of the email that was received. Use this ID for fetching the email with the EmailController . |
createdAt | Instant | Date time of event creation |
to | List | List of To recipient email addresses that the email was addressed to. See recipients object for names. |
from | String | Who the email was sent from. An email address - see fromName for the sender name. |
cc | List | List of CC recipients email addresses that the email was addressed to. See recipients object for names. |
bcc | List | List of BCC recipients email addresses that the email was addressed to. See recipients object for names. |
subject | String | The subject line of the email message as specified by SMTP subject header |
attachmentMetaDatas | List | List of attachment meta data objects if attachments present |
{"messageId":"message-id-123","webhookId":"da9bf94c-27df-45f1-91d1-4d72028761a4","webhookName":"test-webhook","eventName":"EMAIL_RECEIVED","inboxId":"d45b65c8-7de4-4142-839d-7ba7eeb1badd","emailId":"f41d98b1-0502-43f0-b5c0-0bd080f6f702","createdAt":"2022-05-19T06:14:14.066Z","to":["a@b.com"],"from":"test@gmail.com","cc":[],"bcc":[],"subject":"Test email received","attachmentMetaDatas":[]}
{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:webhook:payload:WebhookPayload","properties":{"messageId":{"type":"string","required":true,"description":"Idempotent message ID. Store this ID locally or in a database to prevent message duplication."},"webhookId":{"type":"string","required":true,"description":"ID of webhook entity being triggered","format":"uuid"},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"eventName":{"type":"string","required":true,"description":"Name of the event type webhook is being triggered for.","enum":["EMAIL_RECEIVED","NEW_EMAIL","NEW_CONTACT","NEW_ATTACHMENT","EMAIL_OPENED","EMAIL_READ","BOUNCE","BOUNCE_RECIPIENT"]},"inboxId":{"type":"string","required":true,"description":"Id of the inbox that received an email","format":"uuid"},"emailId":{"type":"string","required":true,"description":"ID of the email that was received. Use this ID for fetching the email with the `EmailController`.","format":"uuid"},"createdAt":{"type":"any","required":true,"description":"Date time of event creation"},"to":{"type":"array","required":true,"description":"List of `To` recipient email addresses that the email was addressed to. See recipients object for names.","items":{"type":"string"}},"from":{"type":"string","required":true,"description":"Who the email was sent from. An email address - see fromName for the sender name."},"cc":{"type":"array","required":true,"description":"List of `CC` recipients email addresses that the email was addressed to. See recipients object for names.","items":{"type":"string"}},"bcc":{"type":"array","required":true,"description":"List of `BCC` recipients email addresses that the email was addressed to. See recipients object for names.","items":{"type":"string"}},"subject":{"type":"string","description":"The subject line of the email message as specified by SMTP subject header"},"attachmentMetaDatas":{"type":"array","required":true,"description":"List of attachment meta data objects if attachments present","items":{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:attachment:AttachmentMetaData","properties":{"name":{"type":"string","required":true},"contentType":{"type":"string","required":true},"contentLength":{"type":"integer","required":true},"id":{"type":"string","required":true}}}}}}