Mailgun

Profile Requirements

To deliver a message to a recipient over Mailgun, Courier must be provided the recipient's email address. This value should be included in the recipient profile as email.

JSON

{
  "message": {
    // Recipient Profile
    "to": {
      "email": "example@example.com"
    }

    // ... rest of message definition
  }
}

Override

You can use a provider override to replace what we send to Mailgun's Messages API. For example, you can use Mailgun's Tagging with your request:

JSON

{
  "message": {
    "template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "to": {
      "email": "example@example.com"
    },
    "providers": {
      "mailgun": {
        "override": {
          "body": {
            "o:tag": "notifications"
          },
          "config": {
            "apiKey": "<your API Key>",
            "domain": "<domain>",
            "host": "<host>"
          }
        }
      }
    }
  }
}

Everything inside of message.providers.mailgun.override will replace what we send to Mailgun's Messages API.

For example, one could override the fromAddress field in the request Courier sends to Mailgun by including the override param and data inside the config object.

You can see all the available options by visiting Mailgun API docs.

EU Host

If you want to send emails using Mailgun's EU infrastructure, set the host to api.eu.mailgun.net:

"config": {
  "apiKey": "<your API Key>",
  "domain": "<domain>",
  "host": "api.eu.mailgun.net"
}

Sending Attachments

To include an attachment in the email, you can use the following override:

{
  "message": {
    "template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "to": {
      "email": "example@example.com"
    },
    "data": {
      "hello": "world"
    },
    "providers": {
      "mailgun": {
        "override": {
          "attachments": [
            {
              "filename": "billing.pdf",
              "contentType": "application/pdf",
              "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
            }
          ]
        }
      }
    }
  }
}

IP Address Range

Mailgun offers an additional security feature that can whitelist certain IP addresses from accessing their API. Courier is hosted on AWS and does not provide an IP range in the form of an allow list.

AWS provides a workaround by allowing users to subscribe and update the changes themselves. Whenever there is a change to the AWS IP address ranges, AWS will send notifications to subscribers of the AmazonIpSpaceChanged topic.

Setup mailhooks for delivery status updates

By default, after we send a message, Courier will poll Mailgun periodically to find out if the message was delivered successfully or not. To get faster status updates, you can setup a webhook so Mailgun can report delivery status directly to Courier.

To start, login to Courier and visit the Mailgun provider configuration screen (from the Channels menu on the left side). There, you will find a Webhook URL.

Copy this URL, then login to Mailgun. On the left side, choose Sending, then Webhooks.

On the webhooks screen, first make sure the Domain selected on the top-right matches the Mailgun Domain on the Courier Mailgun configuration screen. Then, click the green "Add webhook" button. For event type, choose "Delivered Messages". Now paste the webhook URL into the URL field and press "Create webhook."

Repeat the process to create a webhook for event type "Permanent Failure." Use the same URL for both webhooks.

Now that the webhook is configured, you will no longer need Courier to poll for status updates. We recommend waiting about an hour before disabling polling in order to make sure there is no gap in status reporting of any messages already in-flight. When you are ready, return to the Courier Mailgun configuration screen. Flip the toggle switch labeled "Enable polling for status updates" into the off position. Then, press the Save button at the bottom of the screen.