- What's new
Easier and Faster Implementation with Our Updated SDKs
So, I had a few thoughts while working on this update to the API – and maybe you’ve had them, too:
Webhooks are great! Everyone should use them.
Having the same data across similar APIs and JSON payload are 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.
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 APIand 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 temporary 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.
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:
1curl -s --user ‘api:YOUR_API_KEY’2https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks3-X POST4-F id=clicked5-F url="https://api.your.domain.com/v1/mg/clicked"6-F url="https://api.your.domain.com/v2/mg/clicked"7-F url="https://api.partner.com/v1/you/clicked"
Where, “id” – the webhook name, only one webhook per request “url” – your url, up to 3 urls per request And the response message:
1{23"message": "Webhook has been created",45"webhook": {67 "urls": [89 "https://api.your.domain.com/v1/mg/clicked",1011 "https://api.your.domain.com/v2/mg/clicked",1213 "https://api.partner.com/v1/you/clicked"1415 ]1617 }1819}
The received data on your url/urls should be:
1{23 “signature”: 45 {67 "timestamp": "1529006854",89 "token": "a8ce0edb2dd8301dee6c2405235584e45aa91d1e9f979f3de0",1011 "signature": "d2271d12299f6592d9d44cd9d250f0704e4674c30d79d07c47a66f95ce71cf55"1213 }1415 “event-data”: 1617 {1819 "timestamp": 1529006854.329574,2021 "id": "DACSsAdVSeGpLid7TN03WA",2223 "event": "delivered",2425 "tags": [...],2627 "user-variables": {...},2829 "message": {3031 "headers": {3233 "message-id": "20180618211821.example.org"3435 }3637 },3839 …4041 }4243}
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).
That’s it.
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 how 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 http://bin.mailgun.net and consume events at the same time.
Here’s a look at what happens using a test API as well, using the following curl command:
1curl -s --user ‘api:YOUR_API_KEY’ \23https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/HOOK_NAME/test \45-X PUT \67-F url=YOUR_URL
Where, “url” – is your url (one per request) “HOOK_NAME” – is a webhook name (see the list above) one per request as well And the response message:
1 {2 "code" : null,3 "message": "{\"message\":\"Post received. Thanks!\"4 }
Where, “code”- the received HTTP code from your side (null means 200 OK) “message”- the received HTTP body from your side or the error message
Mailgun users that are looking forward to migrate to the new Webhooks API, you don’t need to worry: both APIs can be used at the same time. You’ll be notified by the legacy webhooks and the new webhooks. But don’t forget to remove the legacy url as soon as you migrate your app to the new API!
Not a Mailgun user? No problem, it only takes a few seconds to sign up.
It's easy to get started. And it's free.
See what you can accomplish with the world’s best email delivery platform.
Enjoy!
Last updated on August 28, 2020
Easier and Faster Implementation with Our Updated SDKs
The Difference Between SMTP and API
When Should You Use An Email API?
How To Use Parallel Programming
How we built a Lucene-inspired parser in Go
Gubernator: Cloud-native distributed rate limiting for microservices
What Toasters And Distributed Systems Might Have In Common
Together At Last: Postman Meets Mailgun
Pseudonymization And You – Optimizing Data Protection
Sending Email Using The Mailgun PHP API
Easier and Faster Implementation with Our Updated SDKs
We stand with the AAPI community
The Difference Between SMTP and API
The Basics of Email Dark Mode
COVID-19 Survey: How the Pandemic Has Affected Email Sending
Mailgun Validations Features Improved Performance for EU Customers
International Women’s Day: How Pathwire’s Female Leaders Choose To Challenge
The Top Email Clients and Email Apps of 2021
How To Build An Email List The Right Way
The Path To Email Engagement In 2021: Key Learnings
We stand with the AAPI community
The Difference Between SMTP and API
The Basics of Email Dark Mode
Preparing Your Email Infrastructure Correctly
4 Tips To Improve Your Email Deliverability In 2020
COVID-19 Email Communications Dos and Don’ts
How To Use Parallel Programming
Mailgun’s COVID-19 Plan of Action
Password Meters Are Not For Humans
Send Your Emails at the Perfect Time with Send Time Optimization
Always be in the know and grab free email resources!
By sending this form, I agree that Mailgun may contact me and process my data in accordance with its Privacy Policy.