> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/mailgun.md).

# Mailgun

Mailgun is a transactional email service. Send plain or template-based email, inspect delivery logs and metrics, and manage suppression and mailing lists from your AI workflows.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector         | Authentication  |
| ----------------- | --------------- |
| Mailgun (API Key) | Private API Key |

#### Mailgun (API Key)

Connect to Mailgun to send email and manage deliverability.

**Set up in Mailgun**

1. Prepare the Mailgun account or service that the workflow will access. Grant access to the required resources and operations.
2. **Private API Key:** Your Mailgun primary account API key (Dashboard -> Account Settings -> API Keys -> Private API key). Restricted 'domain sending keys' only allow sending and will fail every other action.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Mailgun (API Key)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field   | Required                 | What to enter                                                                                                                                                                                                                                                      |
| --------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Private API Key | Yes                      | Your Mailgun primary account API key (Dashboard -> Account Settings -> API Keys -> Private API key). Restricted 'domain sending keys' only allow sending and will fail every other action. [Provider instructions](https://app.mailgun.com/settings/api_security). |
| Region          | Optional / as applicable | Mailgun account region: 'us' or 'eu'. Must match where your domains live.                                                                                                                                                                                          |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **Mailgun** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Send Email

Send an email from a verified Mailgun domain, plain or template-based.

**Inputs**

| Field                   | Type            | Required | Description                                                                                                     |
| ----------------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| Sending Domain          | select (string) | Yes      | Verified Mailgun domain to send from. Options load from the selected connection.                                |
| From                    | string          | Yes      | Sender address; supports 'Friendly Name \<email>' format.                                                       |
| To                      | string          | Yes      | Recipient address(es), comma-separated.                                                                         |
| Cc                      | string          | No       | Optional Cc address(es), comma-separated.                                                                       |
| Bcc                     | string          | No       | Optional Bcc address(es), comma-separated.                                                                      |
| Subject                 | string          | No       | Message subject. Optional only when a template pre-sets it.                                                     |
| Text Body               | textarea        | No       | Plain-text body of the message.                                                                                 |
| HTML Body               | textarea        | No       | HTML body of the message.                                                                                       |
| Template                | select (string) | No       | Optional stored template to render the body from. Options load from the selected connection.                    |
| Template Variables      | object          | No       | Variables for template rendering (JSON object).                                                                 |
| Tags                    | array           | No       | Up to 3 tags for analytics/tracking.                                                                            |
| Reply-To                | string          | No       | Optional Reply-To address.                                                                                      |
| Scheduled Delivery Time | datetime        | No       | Optional future delivery time (Mailgun allows up to 3 days ahead).                                              |
| Test Mode               | boolean         | No       | Process the message without actually delivering it.                                                             |
| Click/Open Tracking     | select (string) | No       | Override the domain's click and open tracking for this message. Available values: Enabled, Disabled, HTML only. |
| Recipient Variables     | object          | No       | Per-recipient variables for batch sending (JSON object keyed by email).                                         |

**Outputs**

| Field          | Type   | Description                                               |
| -------------- | ------ | --------------------------------------------------------- |
| Message ID     | string | The queued message's ID, without angle brackets.          |
| Raw ID         | string | The message ID exactly as Mailgun returned it.            |
| Status Message | string | Mailgun's acceptance message (e.g. 'Queued. Thank you.'). |
| Domain         | string | The domain the message was sent from.                     |

#### List Domains

List the sending domains on the Mailgun account.

**Inputs**

| Field        | Type    | Required | Description                                                 |
| ------------ | ------- | -------- | ----------------------------------------------------------- |
| Limit        | integer | No       | Maximum domains to return (default 100).                    |
| State Filter | string  | No       | Optional domain state filter (e.g. 'active', 'unverified'). |

**Outputs**

| Field       | Type        | Description                                         |
| ----------- | ----------- | --------------------------------------------------- |
| Domains     | dict\_array | The sending domains.                                |
| Total Count | integer     | Total number of domains on the account.             |
| Has More    | boolean     | True if more domains exist beyond the returned set. |

#### Get Message Logs

Query Mailgun delivery and engagement logs for a time range.

**Inputs**

| Field       | Type                      | Required | Description                                                                                                                                                 |
| ----------- | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Duration    | string                    | No       | Look-back window like '1d' or '2h'. Alternative to start/end.                                                                                               |
| Start       | datetime                  | No       | Start of the time range. Naive datetimes are treated as UTC.                                                                                                |
| End         | datetime                  | No       | End of the time range (default: now).                                                                                                                       |
| Event Types | multiple\_select (string) | No       | Optional event types to include (default: all). Available values: Accepted, Delivered, Failed, Opened, Clicked, Unsubscribed, Complained, Rejected, Stored. |
| Domain      | select (string)           | No       | Optional sending domain to filter by. Options load from the selected connection.                                                                            |
| Recipient   | string                    | No       | Optional recipient email to filter by.                                                                                                                      |
| Limit       | integer                   | No       | Maximum log entries to return (default 100).                                                                                                                |

**Outputs**

| Field    | Type        | Description                                                    |
| -------- | ----------- | -------------------------------------------------------------- |
| Logs     | dict\_array | The matching log entries, newest first.                        |
| Count    | integer     | Number of log entries returned (may be capped; see has\_more). |
| Has More | boolean     | True if more entries exist beyond the returned set.            |

#### Get Sending Metrics

Query aggregated Mailgun sending and engagement metrics.

**Inputs**

| Field              | Type                      | Required | Description                                                                                                                                                                                                                                  |
| ------------------ | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Duration           | string                    | No       | Look-back window like '7d' or '2h'. Alternative to start/end.                                                                                                                                                                                |
| Start              | datetime                  | No       | Start of the time range. Naive datetimes are treated as UTC.                                                                                                                                                                                 |
| End                | datetime                  | No       | End of the time range (default: now).                                                                                                                                                                                                        |
| Resolution         | select (string)           | No       | Time bucket size (default: day). Available values: Hour, Day, Month.                                                                                                                                                                         |
| Metrics            | multiple\_select (string) | No       | Metrics to include (default: core delivery/engagement counts). Available values: Accepted, Delivered, Failed, Opened, Clicked, Unsubscribed, Complained, Sent, Processed, Unique Opened, Unique Clicked, Temporary Failed, Permanent Failed. |
| Dimensions         | multiple\_select (string) | No       | Grouping dimensions (default: time). Available values: Time, Domain, Tag, Recipient Domain, Recipient Provider, Subaccount.                                                                                                                  |
| Domain             | select (string)           | No       | Optional sending domain to filter by. Options load from the selected connection.                                                                                                                                                             |
| Include Aggregates | boolean                   | No       | Include top-level aggregate totals (default: true).                                                                                                                                                                                          |

**Outputs**

| Field      | Type        | Description                                  |
| ---------- | ----------- | -------------------------------------------- |
| Items      | dict\_array | Metric rows, one per dimension bucket.       |
| Aggregates | dict        | Top-level aggregate totals across the range. |

#### List Suppressions

List the bounces, unsubscribes, or complaints of a domain.

**Inputs**

| Field            | Type            | Required | Description                                                                                   |
| ---------------- | --------------- | -------- | --------------------------------------------------------------------------------------------- |
| Domain           | select (string) | Yes      | The sending domain whose suppression list to read. Options load from the selected connection. |
| Suppression Type | select (string) | Yes      | Which suppression list to read. Available values: Bounces, Unsubscribes, Complaints.          |
| Limit            | integer         | No       | Maximum entries to return (default 100).                                                      |

**Outputs**

| Field    | Type        | Description                                                |
| -------- | ----------- | ---------------------------------------------------------- |
| Entries  | dict\_array | The suppression entries.                                   |
| Count    | integer     | Number of entries returned (may be capped; see has\_more). |
| Has More | boolean     | True if more entries exist beyond the returned set.        |

#### Check Suppressions

Check whether an address is bounced, unsubscribed, or complained.

**Inputs**

| Field         | Type            | Required | Description                                                                                     |
| ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Domain        | select (string) | Yes      | The sending domain whose suppression lists to check. Options load from the selected connection. |
| Email Address | string          | Yes      | The recipient address to look up.                                                               |

**Outputs**

| Field            | Type    | Description                                                       |
| ---------------- | ------- | ----------------------------------------------------------------- |
| Is Suppressed    | boolean | True if the address is on any suppression list.                   |
| Bounced          | boolean | True if the address is on the bounce list.                        |
| Bounce Code      | string  | SMTP error code of the bounce, when bounced.                      |
| Bounce Error     | string  | Error description of the bounce, when bounced.                    |
| Unsubscribed     | boolean | True if the address is on the unsubscribe list.                   |
| Unsubscribe Tags | string  | Tags the address unsubscribed from ('\*' = all), comma-separated. |
| Complained       | boolean | True if the address filed a spam complaint.                       |

#### Remove Suppression

Remove an address from a domain's bounce, unsubscribe, or complaint list.

**Inputs**

| Field            | Type            | Required | Description                                                                                             |
| ---------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| Domain           | select (string) | Yes      | The sending domain whose suppression list to edit. Options load from the selected connection.           |
| Suppression Type | select (string) | Yes      | Which suppression list to remove the address from. Available values: Bounces, Unsubscribes, Complaints. |
| Email Address    | string          | Yes      | The address to remove from the list.                                                                    |

**Outputs**

| Field            | Type   | Description                            |
| ---------------- | ------ | -------------------------------------- |
| Address          | string | The address that was removed.          |
| Suppression Type | string | The list the address was removed from. |

#### Add Unsubscribe

Add an address to a domain's unsubscribe list.

**Inputs**

| Field         | Type            | Required | Description                                                                                     |
| ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Domain        | select (string) | Yes      | The sending domain whose unsubscribe list to add to. Options load from the selected connection. |
| Email Address | string          | Yes      | The address to unsubscribe.                                                                     |
| Tag           | string          | No       | Optional tag to unsubscribe from. Omit for all correspondence.                                  |

**Outputs**

| Field   | Type   | Description                        |
| ------- | ------ | ---------------------------------- |
| Address | string | The address that was unsubscribed. |
| Domain  | string | The domain whose list was updated. |

#### Add List Member

Add or update a member of a Mailgun mailing list.

**Inputs**

| Field         | Type            | Required | Description                                                                       |
| ------------- | --------------- | -------- | --------------------------------------------------------------------------------- |
| Mailing List  | select (string) | Yes      | The mailing list to add the member to. Options load from the selected connection. |
| Email Address | string          | Yes      | The member's email address.                                                       |
| Name          | string          | No       | Optional member name.                                                             |
| Variables     | object          | No       | Optional member variables (JSON object).                                          |
| Subscribed    | boolean         | No       | Whether the member is subscribed (default: true).                                 |
| Upsert        | boolean         | No       | Update the member if it already exists (default: true).                           |

**Outputs**

| Field        | Type    | Description                               |
| ------------ | ------- | ----------------------------------------- |
| Address      | string  | The member's address as stored.           |
| Name         | string  | The member's name as stored.              |
| Subscribed   | boolean | Whether the member is subscribed.         |
| Mailing List | string  | The mailing list the member was added to. |

#### Store Template

Store a reusable email template on a Mailgun domain.

**Inputs**

| Field            | Type            | Required | Description                                                                             |
| ---------------- | --------------- | -------- | --------------------------------------------------------------------------------------- |
| Domain           | select (string) | Yes      | The sending domain to store the template on. Options load from the selected connection. |
| Template Name    | string          | Yes      | Name of the template. Mailgun stores it lowercased.                                     |
| Template Content | textarea        | Yes      | The template body (Handlebars variables supported).                                     |
| Description      | string          | No       | Optional description of the template.                                                   |
| Version Tag      | string          | No       | Optional tag for the initial version (default: 'initial').                              |

**Outputs**

| Field          | Type   | Description                            |
| -------------- | ------ | -------------------------------------- |
| Template Name  | string | The stored (lowercased) template name. |
| Description    | string | The stored description.                |
| Status Message | string | Mailgun's confirmation message.        |
| Domain         | string | The domain the template was stored on. |

#### Validate Email

Check whether an email address is deliverable (requires Mailgun Validate).

**Inputs**

| Field           | Type    | Required | Description                                           |
| --------------- | ------- | -------- | ----------------------------------------------------- |
| Email Address   | string  | Yes      | The email address to validate.                        |
| Provider Lookup | boolean | No       | Also check with the mailbox provider (default: true). |

**Outputs**

| Field           | Type    | Description                                                                 |
| --------------- | ------- | --------------------------------------------------------------------------- |
| Address         | string  | The address that was validated.                                             |
| Result          | string  | Verdict: deliverable, undeliverable, do\_not\_send, catch\_all, or unknown. |
| Risk            | string  | Risk level: low, medium, high, or unknown.                                  |
| Reason          | string  | Reasons behind the verdict, comma-separated.                                |
| Is Disposable   | boolean | True if the address is from a disposable-email provider.                    |
| Is Role Address | boolean | True for role addresses like info@ or support\@.                            |
| Did You Mean    | string  | Suggested correction for likely typos (empty when none).                    |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/mailgun.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
