How to effectively use webhook for email delivery

Learn what a webhook is, when you should use it, and what the differences are between webhooks and APIs. Then, we’ll leave you with nine common questions about using webhooks with Mailgun.



At Mailgun, we’re all for automation and improving how you design and deliver your email program. So, if data is the new gold, what does this mean for your email workflow if you can get email data regarding customer journey touchpoints in real time? Glad you asked. The good news is that this isn’t science fiction. It’s just webhooks.

What are webhooks?

A webhook is a user-defined Hypertext Transfer Protocol (HTTP) callback typically triggered by an event. Simply put, a webhook acts like a bridge between two apps. Once an event happens in one app, a webhook delivers data that notifies you of this event to another app. This means that you get data in real time.

Webhooks are pretty useful in email tracking, analyzing email deliverability data, and monitoring email bounces. They’re also helpful for interfacing with customer relationship management (CRM) platforms. For instance, whenever a customer event occurs, a webhook can deliver notifications to your app that you can then act upon.

Sound a little vague? Let’s dive into the technical nitty-gritty.

After an event occurs, a webhook makes an HTTP request to your application’s API endpoint. This usually takes the form of a POST request with the data attached as a JSON or XML. Then, it’s up to you to interpret the message.

Webhook scripts can be written in almost any scripting language, like C#, PHP, Python, Node.js, Java, Go, and curl. Check out our API guide for a refresher on all that acronym salad we just waded through: HTTP, API, JSON, POST, XML, and more.

Why should you use email webhooks?

Whew, that’s a lot of jargon. Let’s take a brief step back from the tech stuff and discuss why email webhooks are essential to your email marketing program.

Webhooks are the bridge or integration between the various apps you use for your email program. For instance, let’s say you’ve built out an app (App A), and now you’re relying on an email service provider (ESP) to send out your emails (App B). Finally, your company uses a CRM (App C) to improve the customer journey and specific user touchpoints. A webhook pushes notifications of events between your apps so you can react.

Remember, you can use webhooks to keep a tab on not only how customers interact with your emails but also how your emails perform. By tracking email messages sent from your app, you can:

  • Quickly respond to any issues.

  • Maintain your sender reputation and IP reputation.

  • Keep your email deliverability high.

What are the differences between webhook and API?

If both webhooks and email APIs move data between your app and a third-party app (like an ESP), what’s the difference, and why do you need both?

Think of it like the difference between an automated text message reminder and a phone conversation to request more information. In other words, a webhook enables an app (like your ESP) to send data to you, while an API enables an app to deliver data to you upon request. To go back to our analogy, a webhook is like an automated text message that’s sent out as soon as an event happens. With an API, you need to have a “phone conversation” that goes back and forth with an ESP to check if an event has happened and if there’s data you can work with. APIs also support other functions beyond just messaging data.

How can I use webhooks with Mailgun?

Webhooks help you build better email programs. With Mailgun, you can use webhooks to track:

  • Clicks

  • Spam complaints

  • Email delivery

  • Email opens

  • Email hard and soft bounces

  • Unsubscribes

You can also use webhooks with Mailgun, involving common parameters like headers and authentication methods.

What are the 9 common questions about using webhooks with Mailgun?

Now that we have the basics out of the way, let’s go over nine common questions that we’ve come across about using webhooks with Mailgun. Got a question we haven’t covered? Let’s see what our Support Team can do for you.

1. Should I use a webhook with Mailgun to get real-time email delivery notifications?

No. We recommend using our Email API to monitor delivery notifications when you send a large number of emails. However, if your email sending is below a certain threshold, a webhook can also fit your needs. This threshold can change depending on the environment where you host your webhook URL (endpoint).

2. Can I use webhooks to create opt-in forms on my landing page without using third-party plugins/services?

Unfortunately, no. Webhooks work across events that occur in emails that you have already sent out. In other words, you can’t use a webhook to collect a form submitter’s first name from your website.

3. How can I test a webhook call?

Glad you asked. Testing is important to “get it right.” We have a Test Webhook button for every Webhook event type described above. We recommend testing your webhook when configuring its endpoint.

You can find the data sent in each webhook in our documentation. We also have a tool that you can use to send your requests and view the data that was sent. We also suggest checking out Runscope for testing webhooks; it provides a bit more information about your requests.

4. Can I set up my website to send emails via Mailgun on the same domain name I might be using with another email service provider (ESP)?

Yes and no. You can use the same domain name for sending over different ESPs but not for receiving. Only one email server can receive messages for a given domain name. If you’d like to register your domain at multiple servers for sending but don’t want to receive an email at Mailgun, don’t configure your MX records to point to Mailgun.

If you’re receiving emails elsewhere with your domain, we recommend using a subdomain at Mailgun so you can also receive emails at Mailgun. This helps improve deliverability and allows us to easily deal with any issues with recipient email servers.

5. Is polling the API when sending at scale the only option?

Polling the API would be the only option at the moment. Our Events API is great for this, as you can poll for specific time ranges, events, and other user data.

6. Can I use webhooks to have people directly respond to my forum by replying to the email sent to them from the forum?

Webhooks aren’t the right solution to this problem. Instead, we recommend using our Routes feature, which works almost like a webhook. We’ll POST information about these messages to your endpoint. However, while webhooks work across different events that occur in your email messages, Routes obtains data from incoming emails.

7. Does Mailgun have ​​logs of what webhook callbacks were made to my API?

We currently don’t have much logging for our Webhooks feature. Right now, we only log data about the Webhook whenever it fails to POST to the endpoint. The Event data associated with that Webhook event should be in the logs. However, it’ll not contain all the information that a webhook might.

8. Is there a way to get the response in a JSON or XML format for a delivered Webhook?

Unfortunately not; our Webhook will post the URL-encoded data or in multipart (depending on the content of the Webhook).

9. What’s the email threshold when I should move to a polled model rather than a webhook model?

This is a tricky one, as this can change based on how much you want to put into your app infrastructure and what webhooks you’re interested in.

Consider this when deciding whether to implement a polled or webhook model: Each email you send can have several associated events (delivered, clicked, opened, etc.). If there are at least three events associated with each email you send, would your infrastructure be able to handle X emails times three per hour/day? If not, you would want to look into a polled model (API) instead. When determining this, you may also want to see how many requests/minute your infrastructure network can handle.

If you’re sending many messages, all within a short time, keep in mind that Mailgun will try to deliver the Delivery Webhook events as quickly as they occur. However, if your infrastructure can’t handle thousands of requests per minute, the requests may time out and drop. When you receive the Webhook POST, are you storing that data in a database? Sometimes, the influx of traffic will cause the database to run slower, causing the requests to slow or time out.

Wrapping up

Hopefully, the FAQ answers most of your webhook-related questions. But, if you still have unclear thoughts, consider reaching out to our Support Team for further assistance. Until then, if you’re interested in learning more about webhooks, check out our webinar, “How to Effectively Use Webhooks for Email Delivery,” linked below.

Related readings

The basics of SPF records

SPF doesn’t refer to how long you can wait before you have to reapply your sunblock (seriously, go get some). Instead, the term “SPF” refers to a security measure that helps...

Read more

Email validation – Why is it vital for your inbox?

We all have those moments when we get nervous and need to double-check ourselves. Did we fill in the right answer bubbles on a test? Did we type in the right password when...

Read more

What is DKIM: Learn how it works and why it’s necessary

Are you who you say you are, or are you a spoofer in disguise? Answering this question is what DKIM is all about. As email usage and capabilities continue to grow, it’s important to...

Read more

Popular posts

Email inbox.

Build Laravel 10 email authentication with Mailgun and Digital Ocean

When it was first released, Laravel version 5.7 added a new capability to verify user’s emails. If you’ve ever run php artisan make:auth within a Laravel app you’ll know the...

Read more

Mailgun statistics.

Sending email using the Mailgun PHP API

It’s been a while since the Mailgun PHP SDK came around, and we’ve seen lots of changes: new functionalities, new integrations built on top, new API endpoints…yet the core of PHP...

Read more

Statistics on deliverability.

Here’s everything you need to know about DNS blocklists

The word “blocklist” can almost seem like something out of a movie – a little dramatic, silly, and a little unreal. Unfortunately, in the real world, blocklists are definitely something you...

Read more

See what you can accomplish with the world's best email delivery platform. It's easy to get started.Let's get sending
CTA icon