Webhooks

Webhooks allow you to get all information about your deliverability almost real-time. They help integrate Mailtrap more deeply into your system or app. And there’s no need to request a piece of information, you just get it.

The event data you receive include:

Delivery
Bounce
Unsubscribe
Spam Complaint
Reject
Soft Bounce
Suspension
Open
Click

To find out more about the event specifics, check the Statuses and Events article.

How to set up webhooks

Navigate to Sending Domains, choose one of your domains, and select the Webhooks tab.

Click the “Add New Webhook” button, then take the following steps.

1. Put in a valid URL

Use a password and username as an extra security layer. It’s a basic authorization that prevents others from sending information to that endpoint. You can also use a token as a query parameter.

2. Select events and test

Select one or more event types by ticking the corresponding box. Use ready-made code to test the webhook setup. The code represents a dummy payload of the webhook structure and how to read it correctly. After the test, you get an in-app notification, and you can check the webhooks on your website.

If your endpoint responds correctly (200 code), you’ll see a confirmation of that in the app, all other response codes show an error during a test.

One of the popular ways to test webhooks outside your system is https://webhook.site/, but don’t leave it for production.

3. Create webhook

Lastly, hit the “ Create Webhook” button. All info will be sent to your webhook endpoint. Note that you also have options to pause, edit, or delete a webhook. They’re available for active webhooks in the Domain Settings menu.

Events structure and message ID

All the stats are built on the events, and you get most of the event information from Mailtrap UI. Webhook structure is available in our API docs, and you’ll be able to see the event:

Category
Custom variables
Message ID*
Event ID
Response

Important Note:

*As you send email via Mailtrap both SMTP & API respond with that ID so your system can record it and match all other events, as Webhooks also have that ID.

With SMTP, the response is as follows:

Ok: queued as <message ID> - if there’s one user
Ok: queued as <first message ID> and 2 more - if there are multiple users

With API, the response is:

{success: true, message_ids: [array,of,message,ids]}

Retry schedule and batches

Retry schedule

If your endpoint is down and doesn’t respond with 200OK there are retries to provide you with the webhook info. The scheduling logic is as follows:

Retry - 40 retries every 5 minutes. The webhook is gone, if we don’t receive 200OK with all retries.
Timeout - 30 seconds - if your endpoint doesn’t respond in that time, we treat it as a fail and the webhook event batch will go to the retry schedule.

Batches

You have the option to send webhooks in batches - within one object, the information we send can be grouped.

For example, you can group up to 500 events and send that as a batch. The benefit is that you don’t need to make 500 requests to us and there’s less computing on your side. This is very beneficial for high-volume senders.

In an array of events, we collect and batch events every 30 seconds, after that time everything that was grouped will be sent to you. Also, we create the webhook URL and support TSL 1.2, which we strongly recommend you use.