Send email with Mailgun through Courier

Prerequisites

A Mailgun account with a verified sending domain
Your Mailgun API key and domain name

Setup

Create a Mailgun API key

In Mailgun, open API security and copy a sending key. Your domain is on the Domains page.

Configure in Courier

Open the in Courier, enter your API key, domain, and From Address, then save.

EU-region accounts need the host set to api.eu.mailgun.net in a per-send config override. The integration settings have no host field.

Addressing a recipient and sending are the same on every email provider, so they are documented once: and .

Overrides

covers the two levels and which one wins. lists the fields every email provider takes. Use the override object to change the payload Courier sends to Mailgun’s Messages API. This example adds a Mailgun tag.

const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      mailgun: {
        override: {
          body: {
            "o:tag": "notifications",
          },
          config: {
            apiKey: "<your API Key>",
            domain: "<domain>",
            host: "<host>",
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "mailgun": {
                "override": {
                    "body": {
                        "o:tag": "notifications",
                    },
                    "config": {
                        "apiKey": "<your API Key>",
                        "domain": "<domain>",
                        "host": "<host>",
                    },
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "mailgun": {
          "override": {
            "body": {
              "o:tag": "notifications"
            },
            "config": {
              "apiKey": "<your API Key>",
              "domain": "<domain>",
              "host": "<host>"
            }
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      mailgun: {
        override: {
          body: {
            "o:tag": "notifications"
          },
          config: {
            apiKey: "<your API Key>",
            domain: "<domain>",
            host: "<host>"
          }
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"mailgun": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"o:tag": "notifications",
					},
					"config": map[string]any{
						"apiKey": "<your API Key>",
						"domain": "<domain>",
						"host": "<host>",
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("mailgun", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "o:tag", "notifications"
                    ),
                    "config", java.util.Map.of(
                        "apiKey", "<your API Key>",
                        "domain", "<domain>",
                        "host", "<host>"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'mailgun' => [
        'override' => [
          'body' => [
            'o:tag' => 'notifications',
          ],
          'config' => [
            'apiKey' => '<your API Key>',
            'domain' => '<domain>',
            'host' => '<host>',
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "mailgun",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "o:tag": "notifications"
                          },
                          "config": {
                            "apiKey": "<your API Key>",
                            "domain": "<domain>",
                            "host": "<host>"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"mailgun": {"override": {"body": {"o:tag": "notifications"}, "config": {"apiKey": "<your API Key>", "domain": "<domain>", "host": "<host>"}}}}'

With Courier MCP, send my template to sarah@acme-corp.com and add a Mailgun tag.

Courier replaces the full request body with the contents of override. Set fromAddress and other Mailgun config options under override.config. Refer to the Mailgun API docs for supported parameters.

To send through Mailgun’s EU region, set host to api.eu.mailgun.net:

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

Attachments

Add an attachments array to the override. File content must be base64-encoded.

const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    data: {
      hello: "world",
    },
    providers: {
      mailgun: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
            },
          ],
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "data": {
            "hello": "world",
        },
        "providers": {
            "mailgun": {
                "override": {
                    "attachments": [
                        {
                            "filename": "billing.pdf",
                            "contentType": "application/pdf",
                            "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
                        },
                    ],
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "data": {
        "hello": "world"
      },
      "providers": {
        "mailgun": {
          "override": {
            "attachments": [
              {
                "filename": "billing.pdf",
                "contentType": "application/pdf",
                "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
              }
            ]
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    data: {
      hello: "world"
    },
    providers: {
      mailgun: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
            }
          ]
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"hello": "world",
		},
		Providers: shared.MessageProvidersParam{
			"mailgun": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"attachments": []any{
						map[string]any{
							"filename": "billing.pdf",
							"contentType": "application/pdf",
							"data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
						},
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of(
            "hello", "world"
        )))
        .providers(MessageProviders.builder()
            .putAdditionalProperty("mailgun", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "attachments", java.util.List.of(
                        java.util.Map.of(
                            "filename", "billing.pdf",
                            "contentType", "application/pdf",
                            "data", "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'data' => [
      'hello' => 'world',
    ],
    'providers' => [
      'mailgun' => [
        'override' => [
          'attachments' => [
            [
              'filename' => 'billing.pdf',
              'contentType' => 'application/pdf',
              'data' => 'Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh',
            ],
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "hello", JsonSerializer.SerializeToElement("world") },
        },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "mailgun",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "attachments": [
                            {
                              "filename": "billing.pdf",
                              "contentType": "application/pdf",
                              "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                            }
                          ]
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"hello": "world"}' \
  --message.providers '{"mailgun": {"override": {"attachments": [{"filename": "billing.pdf", "contentType": "application/pdf", "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"}]}}}'

With Courier MCP, send my template to sarah@acme-corp.com with an attachment through Mailgun.

IP allowlisting

Mailgun supports IP allowlists for API access. Courier runs on AWS and doesn’t use fixed outbound IPs. Subscribe to the AmazonIpSpaceChanged SNS topic. AWS notifies you whenever its IP ranges change, so you can update your allowlist.

Delivery tracking

Courier does not poll Mailgun unless you turn on Enable polling for status updates in the integration settings. Without polling or a webhook, messages stay at SENT instead of advancing to DELIVERED. Webhooks are better, because Mailgun reports status to Courier in real time.

Copy the Courier webhook URL

In Courier, go to the . Copy the generated Webhook URL.

Configure webhooks in Mailgun

In Mailgun, go to Sending → Webhooks.
Add a webhook for Delivered Messages and paste the URL.
Repeat for Permanent Failure.

Match the domain

In Mailgun, make sure the selected domain matches the one in Courier.

Disable polling (optional)

Wait ~1 hour so in-flight updates land. Then switch off Enable polling for status updates in Courier and click Save.

Troubleshooting

550 error, missing MX record

Mailgun returns a 550 error when the sending domain has no MX record.

Fix:
Add an MX record to your domain’s DNS. Wait ~2 hours for propagation.

Account throttling or probation

Mailgun may throttle or suspend delivery for accounts with high bounce/spam rates or traffic spikes.

Fix:

Complete Mailgun’s Business Verification.
Remove addresses that bounce consistently. Avoid bulk sends to unverified users.

Provider details

mailgun

Courier recommends routing to the channel. Naming this key in routing.channels instead is supported, and sends through just this provider.

Send to a specific provider

When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

Get started

Available integrations

Send email with Mailgun through Courier

Prerequisites

Setup

Overrides

Attachments

IP allowlisting

Delivery tracking

Troubleshooting

Provider details

Send to a specific provider

​Prerequisites

​Setup

​Overrides

​Attachments

​IP allowlisting

​Delivery tracking

​Troubleshooting

​Provider details

Send to a specific provider

Prerequisites

Setup

Overrides

Attachments

IP allowlisting

Delivery tracking

Troubleshooting

Provider details