Mailgun REST API integration from serverless node.js

In this Mailgun integration example we'll show how easy it is to create and deploy a complete serverless backend that integrates with the Mailgun SaaS API for sending email messages to your users.

This article is also available at codehooks.io.

Before you begin, you need to create a new Codehooks project, if you don't have one already.

Create a new serverless backend project

# create a new Codehooks project
coho create mailgunexample

# navigate into the directory for the new project
cd mailgunexample

# install dependent npm packages
npm i codehooks-js form-data node-fetch --save

4 simple steps to integrate with the Mailgun REST API

1. Get your Mailgun API credentials
2. Create secrets in your serverless backend
3. Create the REST API for sending email
4. Deploy your serverless backend

1. Get your Mailgun API credentials

Navigate to your account security setting directly here. Help information is available here.

You'll need two secret keys from your Mailgun account: MAILGUN_APIKEY and MAILGUN_DOMAIN

After locating and inspecting your API-key and domain, protect their content by adding them as encrypted secret environment variables to your serverless backend.

2. Create secrets in your serverless backend

It's easy to add secrets as environment variables using the CLI command set-env.
The example below shows how to create the two secrets we need to access the Mailgun REST API:

coho set-env "MAILGUN_APIKEY" "XXXXXXXXXXX" --encrypted
coho set-env "MAILGUN_DOMAIN" "example.com" --encrypted 

Once the secrets have been added to the serverless runtime we can access them as regular system variables, e.g process.env.MAILGUN_APIKEY.

3. Create the REST API for sending email

The code example below shows a complete serverless backend application.
The application exposes a REST API endpoint with a POST function that calls the Mailgun REST API to send an email to the body.email address. We also use the built-in serverless NoSQL database to store a log of all sent emails.

/*
* Mailgun integration example.
*/
import {app, Datastore} from 'codehooks-js';
import FormData from 'form-data';
import fetch from 'node-fetch';

// Mailgun REST API endpoint address
const MAILGUN_URL = 'api.eu.mailgun.net'; // or api.mailgun.net for US customers

// REST API for sending email to list of recipients
app.post('/sendmail', async function (req, res) {
  // pick from post
  const {email, name} = req.body;
  // create an email as form data
  const form = new FormData();
  form.append('from', '[e-mail]');
  form.append('to', email);
  form.append('subject', 'Testing Mailgun with Codehooks');
  form.append('text', `Hello ${name}, hope you are ok. Lets meet soon.`);
  // Mailgun api endpoint
  const url = `https://${MAILGUN_URL}/v3/${process.env.MAILGUN_DOMAIN}/messages`;
  // Mailgun credentials must be base64 encoded for Basic authentication
  const credentials = Buffer.from(`api:${process.env.MAILGUN_APIKEY}`).toString('base64');
  // POST REST API with the email form data
  const resp = await fetch(url, {
    method: 'POST',
    headers: {
      "Authorization": `Basic ${credentials}`
    },
    body: form
  });
  // handle response errors or OK data
  if (resp.status <= 201) {
    // Success, return Mailgun response to the REST API client
    const output = await resp.json();
    console.log("Success", output);
    // insert log to the NoSQL database
    const db = await Datastore.open();    
    const doc = await db.insertOne('maillog', {email, name, output});  
    return res.status(201).json(output);
  } else {
    console.error(rest.status, resp.statusText);
    // pass the Mailgun error to the REST API client
    return res.status(resp.status).json({error: resp.statusText});
  }    
})

// bind to serverless runtime
export default app.init();

4. Deploy your serverless backend

I just love to deploy serverless backends to the Codehooks.io cloud service, it's so easy and instant.

From the project directory run the CLI command for deployment:

coho deploy

# example output
Project: mailgunexample-8jto  Space: dev
Deployed Codehook successfully! 🙌 

The serverless backend API is now live and available for traffic in the cloud. It you run the CLI command coho info --examples you will see your backend endpoint address and some curl examples to get you started with testing.

Testing your Mailgun integration

Postman, Thunder or curl are great tools for API development and testing. In this example we'll keep it simple and use curl to test our new serverless API.

curl --location --request POST 'https://mailgunexample-8jto.api.codehooks.io/dev/sendmail' \
--header 'x-apikey: bb00d714-c4f2-4df7-9ecb-ad2ce4b29362' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Jane",
    "email": "[e-mail]"
}'

# Mailgun response on success
{"id":"<[e-mail]>","message":"Queued. Thank you."}

:::tip
Use the CLI command coho logs to see errors and generally what's going on inside of your runtime application.
:::

Now that our API has processed some traffic, we can query the NoSQL database to see what data has been written into the sendmail log collection.

coho query maillog --pretty

# Database output
{
  email: '[e-mail]',
  name: 'Jane',
  output: {
    id: '<[e-mail]>',
    message: 'Queued. Thank you.'
  },
  _id: '185b1139873-p6yxdvkww5jz31'
}
...

Voilá, we have a complete serverless backend for sending emails via the Mailgun REST API, including a full database log of all requests and results.

A more advanced example covering bulk sending, email templates, data import and worker queues can be found in this blog post.

The full source code from this Mailgun integration example is available at GitHub.

Happy coding!