<!-- BusyBot node reference — https://busybot.net/tools/mailgun/ -->

> Node: Mailgun (`mailgun`) · Action (binary) · v1
> Category: Communication · Credentials: Mailgun API (`mailgunApi`)
> Updated: 2026-08-16

# Mailgun

> Send emails via Mailgun with attachments

## Overview

The Mailgun tool sends transactional emails using the Mailgun API. It constructs multipart/form-data POST requests to the Mailgun /messages endpoint. Supports plain text and HTML bodies, CC/BCC recipients, binary file attachments from upstream items, custom tags for analytics, and tracking options (opens, clicks). Authentication uses HTTP Basic Auth with username "api" and the Mailgun API key. Supports both US and EU API regions configured in the credential. Each input item sends one email.

**Category:** Communication  
**Tool Name:** `mailgun`  
**Version:** 1

**Appearance:** Icon: `si-mailgun` | Color: `#F06B66`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Mailgun API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/mailgun-api/) for setup instructions.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| From Email | `string` | Yes | — | Email address of the sender, optionally with display name (e.g., "Admin \<admin@example.com\>"). Supports expressions. |
| To Email | `string` | Yes | — | Email address of the recipient. Multiple addresses can be separated by commas. Supports expressions like {{ $json.email }}. |
| Subject | `string` | No | — | Subject line of the email. Supports expressions. |
| Text | `string` | No | — | Plain text message body of the email. Supports expressions. |
| HTML | `string` | No | — | HTML message body of the email. Supports expressions. |
| Attachments | `string` | No | — | Name of the binary properties that contain data to add as email attachments. Multiple names can be comma-separated (e.g., "data,attachment_0"). Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. |
| Options | `collection` | No | `{}` | Additional recipients, tracking and transport settings. |
| — CC Email | `string` | No | — | CC recipient email address(es). Multiple can be separated by commas. Supports expressions. |
| — BCC Email | `string` | No | — | BCC recipient email address(es). Multiple can be separated by commas. Supports expressions. |
| — Tags | `string` | No | — | Comma-separated tags for Mailgun analytics. Maximum 3 tags per message. Supports expressions. |
| — Track Opens | `boolean` | No | `false` | Whether to enable open tracking for this email. |
| — Track Clicks | `options` | No | `false` | Whether to enable click tracking. "HTML Only" tracks clicks in HTML body only. |
| | | | | Options: `true` (Yes), `false` (No), `htmlonly` (HTML Only) |
| — Require TLS | `boolean` | No | `false` | Whether to require TLS connection for message delivery. If TLS cannot be established, Mailgun will not deliver the message. |
| — Skip Verification | `boolean` | No | `false` | Whether to skip TLS certificate and hostname verification. Use with "Require TLS" for less strict TLS enforcement. |
| Max Concurrency | `number` | No | `5` | Maximum number of items to process concurrently. Keep low to respect Mailgun rate limits. |

## Output Data

One email per input item and one output item per input item — this node never fans out, even when To Email lists several addresses. Two fields from the Mailgun send result are added to the item JSON; everything the item already carried passes through unchanged, and any binary data on the input item is forwarded (including the properties that were attached).

```json
{
  "id": "<20240315103000.1.A1B2C3D4E5F6@mg.example.com>",
  "message": "Queued. Thank you."
}
```

- `id` — the Mailgun message ID for the queued message. Use it to correlate later delivery-event webhooks.
- `message` — Mailgun's acceptance text for the request.

Both fields are set to an empty string if Mailgun's response omits them. Reference them downstream by expression, e.g. `{{ $json.id }}`.

## Usage Examples

- Send an HTML email with a PDF attachment via Mailgun
- Send a plain text notification email through Mailgun
- Send email with CC and BCC recipients using Mailgun
- Send bulk transactional emails with tracking enabled
- Send email with multiple binary file attachments

## Example Configuration

Basic email with both a plain-text and an HTML body:

```json
{
  "type": "mailgun",
  "parameters": {
    "fromEmail": "noreply@company.com",
    "toEmail": "customer@example.com",
    "subject": "Welcome to Our Service",
    "text": "Thank you for signing up! We're excited to have you on board.",
    "html": "<h1>Welcome!</h1><p>Thank you for signing up! We're excited to have you on board.</p>"
  }
}
```

Email with advanced options — CC, BCC, tags and tracking:

```json
{
  "type": "mailgun",
  "parameters": {
    "fromEmail": "Marketing Team <marketing@company.com>",
    "toEmail": "subscriber@example.com",
    "subject": "Monthly Newsletter - March 2024",
    "html": "<h2>March Newsletter</h2><p>Check out our latest updates and <a href='https://company.com/news'>click here</a> for more info.</p>",
    "options": {
      "ccEmail": "manager@company.com",
      "bccEmail": "analytics@company.com",
      "tags": "newsletter,march2024,marketing",
      "trackingOpens": true,
      "trackingClicks": "true"
    }
  }
}
```

Email with security options — TLS required, clicks tracked in HTML only:

```json
{
  "type": "mailgun",
  "parameters": {
    "fromEmail": "Security <security@company.com>",
    "toEmail": "admin@client.com,backup@client.com",
    "subject": "Security Alert - Action Required",
    "text": "Important security notification requiring immediate attention.",
    "html": "<div style='color:red;'><h3>Security Alert</h3><p>Important security notification requiring immediate attention.</p></div>",
    "options": {
      "tags": "security,alert,urgent",
      "trackingOpens": true,
      "trackingClicks": "htmlonly",
      "requireTls": true,
      "skipVerification": false
    }
  }
}
```

Email with two binary attachments taken from upstream items:

```json
{
  "type": "mailgun",
  "parameters": {
    "fromEmail": "Reports <reports@company.com>",
    "toEmail": "client@example.com",
    "subject": "Monthly Report - March 2024",
    "text": "Please find attached your monthly report.",
    "html": "<p>Please find attached your monthly report.</p><p>Thank you for your business!</p>",
    "attachments": "report_data,invoice_pdf",
    "maxConcurrency": 3,
    "options": {
      "tags": "report,march2024",
      "trackingOpens": true
    }
  }
}
```

Newsletter campaign — one item per subscriber, with tracking:

```json
{
  "type": "mailgun",
  "parameters": {
    "fromEmail": "Newsletter <news@company.com>",
    "toEmail": "{{ $json.email }}",
    "subject": "{{ $json.subject }}",
    "html": "{{ $json.htmlContent }}",
    "options": {
      "tags": "newsletter,{{ $json.campaign_id }}",
      "trackingOpens": true,
      "trackingClicks": "true",
      "bccEmail": "analytics@company.com"
    }
  }
}
```

Transactional email for order confirmations, password resets and the like:

```json
{
  "type": "mailgun",
  "parameters": {
    "fromEmail": "System <system@company.com>",
    "toEmail": "{{ $json.userEmail }}",
    "subject": "{{ $json.emailType }} - {{ $json.orderId }}",
    "html": "{{ $json.templateContent }}",
    "options": {
      "tags": "transactional,{{ $json.emailType }}",
      "requireTls": true,
      "trackingOpens": false
    }
  }
}
```

Secure communication for sensitive content:

```json
{
  "type": "mailgun",
  "parameters": {
    "fromEmail": "Compliance <compliance@company.com>",
    "toEmail": "{{ $json.recipientEmail }}",
    "subject": "Confidential: {{ $json.subject }}",
    "text": "{{ $json.message }}",
    "options": {
      "tags": "confidential,compliance",
      "requireTls": true,
      "skipVerification": false,
      "trackingOpens": false,
      "trackingClicks": "false"
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Send transactional emails via Mailgun API with optional binary file attachments, tracking, and tags.

### Important Notes

- **Rate Limits**: Keep `maxConcurrency` low (recommended: 5 or less) to respect Mailgun API rate limits
- **Options Structure**: All advanced options must be nested under the `options` object, not at the top level
- **Multiple Recipients**: Separate multiple email addresses with commas in `toEmail`, `ccEmail`, or `bccEmail`
- **Tags Limit**: Maximum of 3 tags per message for Mailgun analytics
- **TLS Security**: Use `requireTls: true` for sensitive emails, optionally with `skipVerification: false` for strict certificate validation
- **Tracking Options**: `trackingClicks` accepts "true", "false", or "htmlonly" as string values