Webhook Documentation

Use MailSlurp webhooks to receive new emails, contacts, or attachments as they arrive via HTTP POST to your server.

Email Webhooks

How does it work?

You can create webhooks for different event and attach them to an inbox. This means that when the given event is triggered a payload is sent to your webhook URL. You server can then process the event and take further actions.

See the webhook guide for more information.

Delivery

A payload is sent via HTTP POST to your server. If it responds with a 200 or 201 status code within 30 seconds the webhook event is marked as successfully processed. If the server does not respond in time or throws an exception the event will be retried until it is successfully handled and you will receive a notification via email of failure.

Webhook creation

You can create a webhook for any MailSlurp inbox using the WebhookController.

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

Event name can be NEW_EMAIL, NEW_CONTACT, NEW_ATTACHMENT. If omitted the legacy EMAIL_RECEIVED event is used. The payloads sent to your server depend on the event name you use.

Endpoint URL

Provide MailSlurp with a reachable URL endpoint to POST event payloads to. It must be reachable to outside servers. You can provide basic auth credentials for a username and password if required.

Inbox scope

Webhooks are attached to inboxes using the WebhookController and their events are trigger per inbox.

Event types

Webhook have event types that determine the payload that will be sent to your endpoint.

Legacy webhooks use the EMAIL_RECEIVED event and they are sent the associated payload. You can create a webhook for other events such as NEW_EMAIL, NEW_CONTACT, and NEW_ATTACHMENT. For integration with Google Drive and other services please see our Zapier plugin.

Get test payloads

You can fetch test payloads for every event type using the /webhooks/test endpoint.

$ curl api.mailslurp.com/webhooks/test?eventName=EMAIL_RECEIVED
> {"messageId":"message-id-123","webhookId":"d3d7eff1-d2a6-4b8b-b112-e08c9f0f144b","webhookName":"test-webhook","eventName":"EMAIL_RECEIVED","inboxId":"94a2be75-4350-48b1-b53d-92183b1fa52d","emailId":"13b21e2b-0a29-406c-a4c0-0251171d6417","createdAt":"2021-05-14T02:19:25.826Z","to":["a@b.com"],"from":"test@gmail.com","cc":[],"bcc":[],"subject":"Test email received","attachmentMetaDatas":[]}

Deserializing webhook data

Consult the schema documentation below or use the Webhook payload classes to deserialize JSON payloads in your server.

Documentation

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.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 recipients that email was addressed to
fromjava.lang.StringfalseWho the email was sent from
ccjava.util.List<java.lang.String>falseList of CC recipients email was addressed to
bccjava.util.List<java.lang.String>falseList of BCC recipients email was addressed to
subjectjava.lang.StringtrueThe subject line of the email message
attachmentMetaDatasjava.util.List<com.mailslurp.lib.dtos.AttachmentMetaData>falseList of attachment meta data objects if attachments present

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.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 recipients that email was addressed to
fromjava.lang.StringfalseWho the email was sent from
ccjava.util.List<java.lang.String>falseList of CC recipients email was addressed to
bccjava.util.List<java.lang.String>falseList of BCC recipients email was addressed to
subjectjava.lang.StringtrueThe subject line of the email message
attachmentMetaDatasjava.util.List<com.mailslurp.lib.dtos.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.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.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

Testing webhooks

You can use the MailSlurp dashboard to test webhooks. You can also see your webhook history in the dashboard.

Further reading

Please see the Webhooks guide for more information and examples.