Back to main menu


Same API, new tricks: Get event notifications just in time with webhooks

We’ve updated our webhooks API to give you more choices to communicate with Mailgun and see the details of what’s happening with your messages.



So, we had a few thoughts while working on this update to the API - and maybe you’ve had them, too:

  1. Webhooks are great! Everyone should use them.

  2. Pulling sending data directly from my messages is a time saver.

Honestly, the Mailgun webhook API has been around a long time now. But with this update, you have more choices to communicate with us and see the details of what’s happening with your messages.

Let’s dive into the details.

What’s new?

So what is this update all about?

Mailgun can help you receive notifications just in time so you can see when something has happened to your message. You have the choice to use event polling via the Events API, or let us push events to you via the Webhooks API. These alerts have the same data as the event API and are sent to your URL/URLs by HTTP POST.

Now, you get

  • ‘Application/JSON' payload

  • Up to 3 URLs per event

  • Data on the following type of events:

    • opened – every time a user opens one of your messages

    • clicked – every time a user clicks on a link in your messages

    • unsubscribed  when a user unsubscribes, either from all messages, a specific tag or a mailing list

    • complained – when a user reports one of your emails as spam. Note that not all ESPs provide this feedback.

    • delivered – when the recipient email server responds that it has accepted the message. 

    • permanent_fail – there are several reasons why Mailgun stops attempting to deliver messages and drops them including hard bounces, messages that reached their retry limit, previously unsubscribed/bounced/complained addresses, or addresses rejected by an ESP.

    • temporary_fail – when a message is temporarily rejected by an ESP

The good thing about this is that your code for business logic can be used for either option. The difference is in how you connect to Mailgun. And since each event has its own unique ID, if it turns out that your http endpoint has died for some reason, you can easily pull events and get them sorted out using this unique ID. Of course, we always recommend handling webhooks in an asynchronous manner so events spikes won’t be an issue.

How can I use the API?

Now let’s see how to configure a domain with the ‘clicked’ webhook. It’s really a one-step process that you can complete by setting up URL/URLs using curl or your preferred programming language via our HTTP API.

For instance, using the curl command:

Here, “id” should be the webhook name (only one webhook per request) and “url” should indicates your URL (up to 3 URLs per request).

And the response message:

The received data on your URL/URLs should be:

The “event-data” portion is the same as what the Events API returns and contains: event timestamp, unique event id, event name, message-id, your tags and variables, etc. As a best practice, don’t forget to verify the “signature” portion (see here how it’s done).

And that’s it. Easy, right?

Can I send events to multiple endpoints?

Yes, you can! If you need to migrate your application to a new version, or you need to send events to your partner site, it can be done for up to 3 endpoints.

If you want to see what your event looks like or you have a question for our support team, it’s easy to configure a webhook with a temporary URL to our request bin at and consume events at the same time.

Here’s a look at what happens when using a test API as well, using the following curl command:

Here, “url” is your URL (one per request) and “HOOK_NAME”  is a webhook name (see the list above – one per request as well).

And the response message:

Here, “code” indicates the received HTTP code from your side (null means 200 OK) and “message” shows the received HTTP body from your side or the error message

I’m a Mailgun user, can I migrate easily to the new API?

Yes. And all legacy webhooks will need to be migrated to this new version. The legacy webhooks API endpoint has been made read only as of April 15, 2023, concluding a deprecation process that began in March 2022.

Product updates are important, and being an email company, we’re pretty good at sending updates to keep you in the loop. Want to explore the why and how behind our moves? Be sure to subscribe to our newsletter for more content like this.

Keep me posted! Get the latest from Mailgun delivered to your inbox.

Send me the newsletter. I expressly agree to receive the newsletter and know that I can easily unsubscribe at any time.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Related readings

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

How to send transactional email in a NodeJS app using the Mailgun API

Sending transactional emails is easy regardless of your tools. If you use a NodeJS helper library, this walkthrough will help you get set up in Mailgun. Read more...

Read more

An expanded Mailgun product suite to transform email deliverability

Today marks a special day for Sinch Mailgun. For over a decade, our focus has been to provide the best email experience for businesses all around the world. Now, we take...

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