# Mailgun (/docs/v/0.6.0/adapters/mailgun)



<ProviderBadge adapter="mailgun" />

## Before live sends [#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 [#configure]

```ts
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 [#send]

```ts
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 [#send-with-headers]

```ts
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 [#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 <a href="/docs/v/0.6.0/adapters/field-support">field support</a> for the full mapping.

## Response [#response]

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

## CLI smoke test [#cli-smoke-test]

```bash
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"
```