Notification of a delivery failure in Mailgun

When you use an email service provider like Gmail, you get delivery failure emails. These emails are great because it enables you to reach out to your intended recipient in another way, or just retry the email later on.

Because I use Mailgun with Gmail’s Send Mail As feature for my custom domains, I needed to implement a solution that handles delivery failures.


I’m cheap, so I host my domains with Cloudflare as they don’t charge a markup – I pay what they pay. Cloudflare recently introduced email forwarding which is great. I used to send and forward emails with Mailgun on their free plan, but they removed the forwarding feature right around the time Cloudflare introduced theirs, lucky me.

I ran into the situation of sending multiple chaser emails to someone because I thought they’d just not got back to me. It turned out my emails just weren’t getting through but I didn’t know. I then started down this path.

Mailgun offers webhooks for many different events. Now I just had to build something to handle the delivery failed event. I’d built some Lambda functions before and Netlify functions but Cloudflare Workers was new at the time, so I decided to build it on that instead.

How I built it

To start, I installed Wrangler, Cloudflare’s development CLI, and got a project set up. A Cloudflare Worker runs a short snippet of code on the edge. I wanted to use Node, because JavaScript is a language I’m most comfortable in, so had to enable the node_compat flag on the worker to allow various methods inside the crypto functions to work. I also set up CI using a GitHub action so each time I push changes to GitHub, the worker gets built and deployed to the global Cloudflare network. I used the cloudflare/wrangler-action package to do this.

A simple overview of how it works is the worker receives a request and parses its body. If there is no request body, then the worker returns a 405 bad request status code. With the body, we create a hmacDigest from the body timestamp, token, and a special signing key that we get from the Mailgun dashboard. I’m using the crypto-js library to do this. We compare this calculated digest with the signature in the request body to make sure they match. This authenticates the request to ensure only our Mailgun account can send webhooks to this Worker. We also cache this digest, along with the URL so that we can see whether it has been used before. Mailgun wouldn’t send a webhook event twice, so it must be someone trying to get information by replaying an old webhook event. By validating whether we’ve processed the digest before, we can prevent replay attacks.

// Make sure a body is included
let body
try {
    body = await request.json()
} catch(e) {
    return new Response("Bad request", { status: 405 })
// Verify that the Mailgun Signature matches the one that they sent us
const hmacDigest = hex.stringify(hmacSHA256(body.signature.timestamp + body.signature.token, env.MAILGUN_SIGNING_KEY))
// Load Cloudflare Cache
const cache = caches.default
// Set Cache Key for this signature = https://worker.domain/signature
const cacheKey = request.url + hmacDigest
// Ensure the signature has not been used already
const alreadyUsedSignature = await cache.match(cacheKey)
if (alreadyUsedSignature !== undefined) {
    return new Response("This is a replay attack. The signature has been used before", { status: 401 })
if (hmacDigest !== body.signature.signature) {
    return new Response("Could not verify signature", { status: 406 })

Now we have all of the security out of the way, we get to actually processing the error message received from Mailgun. First, we get the recipient, so we know who we need to email back seeing as they didn’t receive our message. Then we grab the sender, as it may be you manage more than 1 domain so you need to know who sent the email. The email subject helps too as it may be you sent more than 1 email to the same person. We also want to be informed of the error message, so we get that too.

To allow us to send mail, we use Mailgun’s HTTP API, configured using env variables. We have one for what email should send these notifications, and one for who the notifications should go to. We then just need a Mailgun API key to allow us to send the email. This API key should match the domain you’d like to send email from.

// Set up the email to send
const mailOptions = {
    from: `Galexia Mail Reporting <info@${env.DOMAIN}>`,
    subject: "New delivery failure in Mailgun",
    text: `
An email to:


With a subject of:

Has failed.

The error message was:
${body['event-data']['delivery-status'].description || body['event-data']['delivery-status'].message}
// Convert the email JSON to FormData
const form_data = new FormData()
for (var key in mailOptions) {
    form_data.append(key, mailOptions[key]);
// Send the email
const sendEmail = await fetch(`${env.DOMAIN}/messages`, {
    method: 'POST',
    body: form_data,
    headers: {
        'authorization': `Basic ${new Buffer('api' + ':' + env.MAILGUN_API_KEY).toString('base64')}`,
        'accept': 'application/json'

Setting this all up gets me delivery failure messages like this:

Of course, if you get an error sending that email, you could be stuck in a loop and still get silent failures, so I’ve set my recipient to a Gmail address which has pretty good availability.

In summary, having this worker set up allows me to catch any emails that don’t get delivered, and then be able to dive into the Mailgun logs to debug the issue. On the flex plan, logs are only stored for 5 days, so having this webhook set up gives me near instant error messages and allows me to action any issues quickly.

To build on this, I’d want to set up something to notify me of forwarding failures from Cloudflare’s free email forwarding.

TV Shows App

I like to keep track of the TV Shows I watch. I used to do this in a Word Document and manually go to IMDb and check whether the show was running or had been cancelled and then add the TV Show to my calendar. I decided to build an app that would do this for me.

I decided to try and learn a new framework whilst creating this fun little side-project. I’ve heard good things about Svelte so decided to give it a shot. It’s a framework very much like Vue (which I love by the way). It splits it’s template files into CSS, HTML, and JavaScript which made it easy to get the hang of. It doesn’t come with something like Vue data, and there’s a weird thing where you need to tell the framework a variable has changed by doing variable = variable. Svelte devtools aren’t anywhere near as intuitive either. These small little things are the price you pay for infinitely better load times. All the processing is done in a compile step, whereas, Vue does all it’s processing in the browser. It’s a framework I’d go to for a simple static site that might have some components that are easier to create in a framework than with vanilla JavaScript. For most of my projects though, I’ll be sticking to Vue.

My TV Show app is behind somewhat of a firewall, Cloudflare Access. I didn’t want the hassle of rolling an authentication system with my simple app so I decided to use Cloudflare Access instead. Otherwise, anyone would be able to add or remove TV Shows from my list. If you got to you’ll see that you have to log in with Cloudflare first.

The app queries the episodate API when you perform a search and stores the added TV Show in a Fauna Database. It does this by using a Lambda function hosted on Netlify. There are also Lambdas for removing and viewing saved TV Shows.

The app then queries the Fauna Database for all currently watching TV Shows and fetches information on them from the episodate API. The TV show is green for currently airing. Red for cancelled/finished. And has no colour for shows that haven’t announced new episodes yet.

The app exports all of the episodes set in the future to an iCal file which you can download and import into any calendar software. This is still a bit of a manual task and I wanted to automate it further so I created another Lambda function that fetches the TV Show information, and serves the calendar. This was quite a tricky process as I had to learn a lot more about Lambdas than just copying the FaunaDB examples. I got it working but it takes about 16 seconds to query all of the TV Shows I watch, longer than the 10-second execution limit on Netlify. I shopped around for another solution and came across Serverless, which makes deploying on AWS simpler. It only needs about 100mb of memory so I adjusted that limit accordingly.

If I were to make this a production app I’d probably cache the API in Local Storage or in the Fauna Database and find a way of not having to query every TV Show when something is removed or added.

If you want to get set up you can fork my repository and add a .env file containing your FaunaDB secret. Or, if you want a Lambda function acting as a webCal you can fork that repo and query any API you like. It uses ics.js to create the webCal.

Weather app

My friend made a weather app so that they could learn APIs. I decided to fork it and take it a step further by experimenting with CSS Houdini, Variable Fonts, CSS Variables, and new browser APIs such as the Speech Synthesis API.


Future Ideas

  • Turn notifications on and off and have icon reflect that.
  • Send notifications every 30 minutes even if app is not opened.
  • Use more bleeding edge APIs (Suggestions welcome).

No Thumbnails Gallery

When creating my portfolio and memories page I needed a quick and easy way of creating galleries of images without having to code each individual image (there are over 3,000 images!). Also, I needed it without a thumbnail for each image. As far as I can tell there isn’t an easy option to do that. So I created my own bit of code using AJAX, jQuery, and PHP. I have called this the No Thumbnails Gallery. After going to Dan Benham’s talk and hearing about how to turn skills into software that’s resellable I decided to make my bit of code standalone. I have since added it to GitHub for other people to see, and use free-of-charge.