Skip to content

Webhook Documentation

Webhooks are a feature that allow you to receive event payloads sent directly to your server in response to predefined events such as new emails, inbound SMS messages, or account bounces. Webhooks can be attached to inboxes, phone numbers, or to your account. See the event type payloads below for schema examples.

webhooks

About

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.

Webhook Event types

Webhook events are listed below. Each event type indicates the triggering action for the webhook. For instance NEW_EMAIL webhooks are triggered when an inbox they are attached to receives a new email.

  • BOUNCE
  • BOUNCE_RECIPIENT
  • DELIVERY_STATUS
  • EMAIL_OPENED
  • EMAIL_READ
  • EMAIL_RECEIVED
  • NEW_ATTACHMENT
  • NEW_CONTACT
  • NEW_EMAIL
  • NEW_SMS

See the event documentation for details on each type.

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.

Message payload

When a webhook is triggered for its event type a corresponding JSON payload is posted to the webhook's URL via HTTP. See the event type documentation below for schemas. 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.

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

Or for simpler usage parse the request body into your expected payload:

const newEmail: WebhookNewEmailPayload = JSON.parse(requestBody);
console.log(`New email from ${newEmail.from} with subject ${newEmail.subject}`)

Custom payload and redirect

You can customize the shape of the event payload for use with other services such as Slack or Teams by providing a requestBodyTemplate property containing templated JSON.

await mailslurp.webhookController.createWebhook({
  inboxId: inbox.id,
  createWebhookOptions: {
    eventName: CreateWebhookOptionsEventNameEnum.NEW_EMAIL,
    url: slackIncomingWebhookUrl,
    // custom request body for slack uses {{subject}} to insert
    // the subject from the standard NEW_EMAIL payload
    requestBodyTemplate: `{"text":"New message: {{subject}}"}`
  },
});

Use mustache style templating to insert properties from the standard payload for the event into your custom payload.

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.

You can add custom headers when you create a webhook and these header name value pairs will be sent with every request. Use these static headers in your application if required. See the static header section for more information.

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 phone number 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.

const inbox = await mailslurp.createInbox();
const webhook = await mailslurp.webhookController.createWebhook({
  inboxId: inbox.id!,
  createWebhookOptions: {
    eventName: CreateWebhookOptionsEventNameEnum.NEW_EMAIL,
    url: testEndpoint.url!!,
  },
});

Account scoped webhooks

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

const webhook = await mailslurp.webhookController.createAccountWebhook({
  createWebhookOptions: {
    eventName: CreateWebhookOptionsEventNameEnum.BOUNCE,
    url: testEndpoint.url!!,
  },
});

Account based webhooks are useful for processing events for every inbox or your whole account. For example: you can use a single account webhook with the NEW_EMAIL type to receive all inbound emails across each of your inboxes with one webhook.

Phone based webhooks

SMS related events support phone number scoping like so:

await mailslurp.webhookController.createWebhookForPhoneNumber({
    phoneNumberId: phone.id,
    createWebhookOptions: {
        eventName: CreateWebhookOptionsEventNameEnum.NEW_SMS,
        url: testEndpoint.url!!,
    },
});

Set static headers

MailSlurp can send static headers with each HTTP header. Use the includeHeaders option when creating the webhook and POST requests to your server will include the provided name value key pairs.

// create webhook
const createWebhookOptions: CreateWebhookOptions = {
  name: 'my-webhook',
  url: 'https://your.server',
  includeHeaders: {
    headers: [
      { name: 'x-test-header', value: '123'}
    ]
  }
};
const webhook = await webhookController.createWebhook({
  inboxId: inbox.id!!,
  createWebhookOptions: createWebhookOptions,
});

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.

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:

import { WebhookNewSmsPayload } from "mailslurp-client";

import bodyParser from "body-parser"
import express from "express";

// create a server
const app = express();
app.use(bodyParser());

/**
 * Define an endpoint on your server for the NEW_SMS webhook event
 */
app.post("/inbound/new-sms", (request, response) => {
    // access the data on request body
    // and cast to the expected event type take action
    const sms = request.body as WebhookNewSmsPayload
    // access the entity
    console.log(`New SMS from ${sms.fromNumber}`)
    // return a 2xx status code so MailSlurp knows you received it
    response.sendStatus(200);
});

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();

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 or 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 Email sent to recipients
sender String Sender causing bounce
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.
{"messageId":"test-message-id","webhookId":"c9cb550e-41b5-4ef5-bd2b-3c46a1e64ecc","eventName":"BOUNCE","webhookName":"test-webhook-name","bounceId":"90155ccd-2c00-40d3-b224-dcd07d5efde8","sentToRecipients":["a@b.com","c@d.com"],"sender":"test@sender.com","bounceRecipients":["a@b.com"]}
{"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","DELIVERY_STATUS","BOUNCE","BOUNCE_RECIPIENT","NEW_SMS"]},"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","description":"Email sent to recipients","items":{"type":"string"}},"sender":{"type":"string","required":true,"description":"Sender causing bounce"},"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.
{"messageId":"test-message-id","webhookId":"fc32d6d1-e907-402b-9122-f17fc224293d","eventName":"BOUNCE_RECIPIENT","webhookName":"test-webhook-name","recipient":"test@receiver.com"}
{"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","DELIVERY_STATUS","BOUNCE","BOUNCE_RECIPIENT","NEW_SMS"]},"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."}}}

DELIVERY_STATUS

This payload is sent via HTTP POST to your webhook URL when an email is sent and a delivery status is obtained. A delivery status can be a successful send or a failure.

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
id UUID ID of delivery status
userId UUID User ID of event
sentId UUID ID of sent email
remoteMtaIp String IP address of the remote Mail Transfer Agent
inboxId UUID Id of the inbox
reportingMta String Mail Transfer Agent reporting delivery status
recipients List Recipients for delivery
smtpResponse String SMTP server response message
smtpStatusCode Integer SMTP server status
processingTimeMillis Long Time in milliseconds for delivery processing
received Instant Time event was received
subject String Email subject
{"messageId":"test-message-id","webhookId":"ded815ad-14d8-4f75-8dfb-e8b844feacb6","eventName":"NEW_CONTACT","webhookName":"webhook-name","id":"c7079d62-68e0-4a96-b247-3d61de065f85","userId":"85015ea7-e781-4f76-bc5f-5088ea72c581","sentId":"c2cda2f1-c0dc-409d-b5c5-c3845c1a87e3","remoteMtaIp":"1.1.1.1","inboxId":"908cd03e-38cb-48cd-b551-fc42df1510b0","reportingMta":"reporting-server","recipients":["test@gmail.com"],"smtpResponse":"200 OK","smtpStatusCode":200,"processingTimeMillis":123,"received":"1970-01-01T00:00:00.000Z","subject":"test-subject"}
{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:webhook:payload:WebhookDeliveryStatusPayload","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","DELIVERY_STATUS","BOUNCE","BOUNCE_RECIPIENT","NEW_SMS"]},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"id":{"type":"string","required":true,"description":"ID of delivery status","format":"uuid"},"userId":{"type":"string","required":true,"description":"User ID of event","format":"uuid"},"sentId":{"type":"string","description":"ID of sent email","format":"uuid"},"remoteMtaIp":{"type":"string","description":"IP address of the remote Mail Transfer Agent"},"inboxId":{"type":"string","description":"Id of the inbox","format":"uuid"},"reportingMta":{"type":"string","description":"Mail Transfer Agent reporting delivery status"},"recipients":{"type":"array","description":"Recipients for delivery","items":{"type":"string"}},"smtpResponse":{"type":"string","description":"SMTP server response message"},"smtpStatusCode":{"type":"integer","description":"SMTP server status"},"processingTimeMillis":{"type":"integer","description":"Time in milliseconds for delivery processing"},"received":{"type":"any","description":"Time event was received"},"subject":{"type":"string","description":"Email subject"}}}

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
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":"a31427ba-8af2-40ab-a466-6edbc8aa3f24","eventName":"EMAIL_OPENED","webhookName":"test-webhook-name","inboxId":"b9574917-d547-40ee-8ade-5611a8c8a6da","pixelId":"3cba1fc4-a29e-4ae9-ad0f-fc803cdd5c53","sentEmailId":"407288be-1ee0-4466-baa2-69bb43a1eccd","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","DELIVERY_STATUS","BOUNCE","BOUNCE_RECIPIENT","NEW_SMS"]},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"inboxId":{"type":"string","required":true,"description":"Id of the inbox","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_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
emailIsRead boolean Is the email read
createdAt Instant Date time of event creation
{"messageId":"test-message-id","webhookId":"3b8dde38-cb0d-441b-8d75-7f5cd3438658","eventName":"EMAIL_READ","webhookName":"test-webhook-name","emailId":"f6b1905a-53ab-458a-8dbe-f5358292c850","inboxId":"2316138a-b101-4c84-860f-72305f6248db","emailIsRead":true,"createdAt":"1970-01-01T00:00:00.000Z"}
{"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","DELIVERY_STATUS","BOUNCE","BOUNCE_RECIPIENT","NEW_SMS"]},"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","format":"uuid"},"emailIsRead":{"type":"boolean","required":true,"description":"Is the email read"},"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
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":"6f378186-6e32-4223-9058-833520057076","webhookName":"test-webhook","eventName":"EMAIL_RECEIVED","inboxId":"0b3130a3-689a-4caf-961d-339336ab7f5d","emailId":"eebc8310-d86e-44c5-8520-5fd5ae7f852b","createdAt":"2022-09-29T23:59:21.143Z","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","DELIVERY_STATUS","BOUNCE","BOUNCE_RECIPIENT","NEW_SMS"]},"inboxId":{"type":"string","required":true,"description":"Id of the inbox","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_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
{"messageId":"test-message-id","webhookId":"4fce48e5-4485-41ee-9da1-6493eea67f88","webhookName":"webhook-name","eventName":"NEW_ATTACHMENT","attachmentId":"attachment-id","name":"attachment-name","contentType":"text/plain","contentLength":123}
{"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","DELIVERY_STATUS","BOUNCE","BOUNCE_RECIPIENT","NEW_SMS"]},"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"}}}

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 Contact ID
groupId UUID Contact group ID
firstName String Contact first name
lastName String Contact last name
company String Contact company name
primaryEmailAddress String Primary email address for contact
emailAddresses List Email addresses for contact
tags List Tags for contact
metaData JsonNode Meta data for contact
optOut boolean Has contact opted out of emails
createdAt Instant Date time of event creation
{"messageId":"test-message-id","webhookId":"7cd513f0-b185-48a4-8661-fb13ee7d7dab","webhookName":"webhook-name","eventName":"NEW_CONTACT","contactId":"5c61cbcd-d3d4-4490-9e82-6a707b6e2a05","groupId":"22dcbe2c-2e1d-4721-9620-e82b0efdb295","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","DELIVERY_STATUS","BOUNCE","BOUNCE_RECIPIENT","NEW_SMS"]},"contactId":{"type":"string","required":true,"description":"Contact ID","format":"uuid"},"groupId":{"type":"string","description":"Contact group ID","format":"uuid"},"firstName":{"type":"string","description":"Contact first name"},"lastName":{"type":"string","description":"Contact last name"},"company":{"type":"string","description":"Contact company name"},"primaryEmailAddress":{"type":"string","description":"Primary email address for contact"},"emailAddresses":{"type":"array","required":true,"description":"Email addresses for contact","items":{"type":"string"}},"tags":{"type":"array","required":true,"description":"Tags for contact","items":{"type":"string"}},"metaData":{"type":"any","description":"Meta data for contact"},"optOut":{"type":"boolean","required":true,"description":"Has contact opted out of emails"},"createdAt":{"type":"any","required":true,"description":"Date time of event creation"}}}

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
domainId UUID Id of the domain 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":"80e8f3da-af4c-43d1-a2b1-8343173ceddc","eventName":"NEW_EMAIL","webhookName":"test-webhook","inboxId":"9f75d392-94de-437d-9423-e2ebfc20da15","domainId":null,"emailId":"6b51f1db-5071-4811-9435-82ad5878b62a","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","DELIVERY_STATUS","BOUNCE","BOUNCE_RECIPIENT","NEW_SMS"]},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"inboxId":{"type":"string","required":true,"description":"Id of the inbox","format":"uuid"},"domainId":{"type":"string","description":"Id of the domain 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_SMS

This payload is sent via HTTP POST to your webhook URL when a new SMS message is received by one of your phone numbers.

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
smsId UUID ID of SMS message
userId UUID User ID of event
phoneNumber UUID ID of phone number receiving SMS
toNumber String Recipient phone number
fromNumber String Sender phone number
body String SMS message body
read boolean SMS has been read
{"messageId":"test-message-id","webhookId":"c9ef1d27-572e-4707-8d46-82adeaa17eea","eventName":"NEW_SMS","webhookName":"webhook-name","smsId":"df7f1f2a-11e9-49a3-afba-6b9ce6374460","userId":"e47021bd-db7b-4c5e-b842-e3f7c6062e18","phoneNumber":"da58551f-506a-470c-b32f-0b42dcc1551e","toNumber":"+14155552671","fromNumber":"+442071838750","body":"sms-message-body","read":false}
{"type":"object","id":"urn:jsonschema:com:mailslurp:lib:dtos:webhook:payload:WebhookNewSmsPayload","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","DELIVERY_STATUS","BOUNCE","BOUNCE_RECIPIENT","NEW_SMS"]},"webhookName":{"type":"string","description":"Name of the webhook being triggered"},"smsId":{"type":"string","required":true,"description":"ID of SMS message","format":"uuid"},"userId":{"type":"string","required":true,"description":"User ID of event","format":"uuid"},"phoneNumber":{"type":"string","required":true,"description":"ID of phone number receiving SMS","format":"uuid"},"toNumber":{"type":"string","required":true,"description":"Recipient phone number"},"fromNumber":{"type":"string","required":true,"description":"Sender phone number"},"body":{"type":"string","required":true,"description":"SMS message body"},"read":{"type":"boolean","required":true,"description":"SMS has been read"}}}