Mailgun

Mailgun

@opencoredev/email-sdk/mailgun

OfficialNot API testedRequest tested

Before live sends

Create a Mailgun API key for the sending domain and use the base URL for the domain region. EU domains need the EU API base URL; US domains use the default. Verify DNS and sender setup before treating a successful SDK call as production-ready delivery.

Configure

import { createEmailClient } from "@opencoredev/email-sdk";
import { mailgun } from "@opencoredev/email-sdk/mailgun";

const email = createEmailClient({
  adapters: [
    mailgun({
      apiKey: process.env.MAILGUN_API_KEY!,
      domain: process.env.MAILGUN_DOMAIN!,
    }),
  ],
});

Send

const result = await email.send({
  from: "Acme <hello@mg.example.com>",
  to: "user@example.com",
  replyTo: "support@example.com",
  subject: "Receipt",
  html: "<p>Thanks for your order.</p>",
  metadata: {
    orderId: "ord_123",
  },
  tags: [{ name: "type", value: "receipt" }],
  attachments: [
    {
      filename: "receipt.txt",
      content: "Thanks for your order.",
      contentType: "text/plain",
    },
  ],
});

console.log(result.provider, result.messageId);

Mailgun maps metadata as v:* variables and tag values as o:tag. Use baseUrl: "https://api.eu.mailgun.net" for EU-region domains.

Send with headers

await email.send({
  from: "Acme <hello@mg.example.com>",
  to: "user@example.com",
  subject: "Support update",
  text: "We received your request.",
  headers: {
    "X-Ticket-ID": "ticket_123",
  },
});

Options

Option	Type	Required	Notes
`apiKey`	`string`	Yes	Mailgun API key.
`domain`	`string`	Yes	Sending domain.
`baseUrl`	`string`	No	Defaults to `https://api.mailgun.net`. Use the EU API base URL if your domain is in the EU region.
`fetch`	`typeof fetch`	No	Useful for tests or custom runtimes.

Mailgun sends attachments as multipart form data. See field support for the full mapping.

Response

The adapter maps Mailgun id to the normalized id and messageId fields.

CLI smoke test

MAILGUN_API_KEY="key-..." \
MAILGUN_DOMAIN="mg.example.com" \
npx email-sdk send \
  --adapter mailgun \
  --from "Acme <hello@mg.example.com>" \
  --to user@example.com \
  --subject "Mailgun test" \
  --text "It works"