> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Mailgun Integration for AI Agents & Workflows

> Transactional email API for sending, receiving, and tracking email

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/df8MOr-hXotYLTh5/logos/mailgun.svg?fit=max&auto=format&n=df8MOr-hXotYLTh5&q=85&s=7374e4f5536370b586cc361a7c77ae07" alt="Mailgun logo" width="72" height="72" data-path="logos/mailgun.svg" />

## Overview

Add **Mailgun** to any ModuleX agent or workflow. Transactional email API integration for sending, receiving, and tracking email via the Mailgun REST API (`api.mailgun.net`).

<Info>
  **Categories**: Communication · Email · **Auth**: Mailgun API Key · **Actions**: 9
</Info>

## Authentication

### Mailgun API Key

Authenticate using your Mailgun API key and region

<Steps>
  <Step title="Step 1">
    Log in to [https://app.mailgun.com](https://app.mailgun.com)
  </Step>

  <Step title="Step 2">
    Go to Settings > API Security
  </Step>

  <Step title="Step 3">
    Copy your Private API key
  </Step>

  <Step title="Step 4">
    Set MAILGUN\_REGION to 'EU' if your account is on the EU infrastructure, otherwise leave as 'US'
  </Step>
</Steps>

#### Required Credentials

| Field           | Description                                                      | Required | Format                                 |
| --------------- | ---------------------------------------------------------------- | -------- | -------------------------------------- |
| Mailgun API Key | Private API key from Mailgun dashboard (Settings > API Security) | Yes      | `key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
| Mailgun Region  | API region: 'US' (default) or 'EU'                               | No       | `US`                                   |

## Available Actions

<AccordionGroup>
  <Accordion title="send_email — Send an email via Mailgun">
    ### Parameters

    <ResponseField name="domain" type="string" required>
      Mailgun domain name to send from
    </ResponseField>

    <ResponseField name="from_name" type="string" required>
      Sender display name
    </ResponseField>

    <ResponseField name="from_email" type="string" required>
      Sender email address
    </ResponseField>

    <ResponseField name="to" type="array" required>
      Recipient email address(es) as a list of strings
    </ResponseField>

    <ResponseField name="subject" type="string" required>
      Email subject line
    </ResponseField>

    <ResponseField name="text" type="string">
      Plain text message body
    </ResponseField>

    <ResponseField name="html" type="string">
      HTML message body
    </ResponseField>

    <ResponseField name="reply_to" type="string">
      Reply-to email address
    </ResponseField>

    <ResponseField name="test_mode" type="boolean">
      Enable Mailgun test mode (message accepted but not delivered) (Default: `true`)
    </ResponseField>

    <ResponseField name="dkim" type="boolean">
      Enable or disable DKIM signatures on the message (Default: `true`)
    </ResponseField>

    <ResponseField name="tracking" type="boolean">
      Enable or disable tracking on the message (Default: `true`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Message"
        }
      },
      "required": [
        "success"
      ],
      "title": "SendEmailOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="verify_email — Verify an email address for deliverability using Mailgun's validation API">
    ### Parameters

    <ResponseField name="email" type="string" required>
      Email address to verify
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "EmailVerificationResult": {
          "additionalProperties": false,
          "properties": {
            "address": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Address"
            },
            "did_you_mean": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Did You Mean"
            },
            "is_disposable_address": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Is Disposable Address"
            },
            "is_role_address": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Is Role Address"
            },
            "reason": {
              "items": {
                "type": "string"
              },
              "title": "Reason",
              "type": "array"
            },
            "result": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Result"
            },
            "risk": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Risk"
            }
          },
          "title": "EmailVerificationResult",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "verification": {
          "anyOf": [
            {
              "$ref": "#/$defs/EmailVerificationResult"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "success"
      ],
      "title": "VerifyEmailOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_mailinglist_member — Add a member to an existing Mailgun mailing list">
    ### Parameters

    <ResponseField name="list_address" type="string" required>
      Mailing list address (e.g. [list@yourdomain.com](mailto:list@yourdomain.com))
    </ResponseField>

    <ResponseField name="address" type="string" required>
      Email address of the member to add
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the member
    </ResponseField>

    <ResponseField name="vars" type="object">
      Extra arbitrary member data as a JSON object
    </ResponseField>

    <ResponseField name="subscribed" type="string">
      Subscription status: 'yes' (default) or 'no' for unsubscribed (Default: `yes`)
    </ResponseField>

    <ResponseField name="upsert" type="string">
      If 'yes', update existing member; if 'no', error on duplicate. Values: yes, no (Default: `no`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "MailinglistMember": {
          "additionalProperties": false,
          "properties": {
            "address": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Address"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Name"
            },
            "subscribed": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Subscribed"
            },
            "vars": {
              "anyOf": [
                {
                  "additionalProperties": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Vars"
            }
          },
          "title": "MailinglistMember",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "member": {
          "anyOf": [
            {
              "$ref": "#/$defs/MailinglistMember"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateMailinglistMemberOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_route — Create a new Mailgun route for email matching and forwarding">
    ### Parameters

    <ResponseField name="priority" type="integer" required>
      Route priority (lower numbers are evaluated first)
    </ResponseField>

    <ResponseField name="description" type="string" required>
      Human-readable description of the route
    </ResponseField>

    <ResponseField name="expression" type="string" required>
      Mailgun route filter expression, e.g. match\_recipient('.\*@example.com')
    </ResponseField>

    <ResponseField name="action" type="array" required>
      List of route action strings, e.g. \['forward("[dest@example.com](mailto:dest@example.com)")', 'stop()']
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "route_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Route Id"
        },
        "route_message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Route Message"
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateRouteOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="delete_mailinglist_member — Delete a member from a Mailgun mailing list by email address">
    ### Parameters

    <ResponseField name="list_address" type="string" required>
      Mailing list address (e.g. [list@yourdomain.com](mailto:list@yourdomain.com))
    </ResponseField>

    <ResponseField name="address" type="string" required>
      Email address of the member to remove
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "member_address": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Member Address"
        },
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Message"
        }
      },
      "required": [
        "success"
      ],
      "title": "DeleteMailinglistMemberOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_domains — List all domains configured in the Mailgun account">
    ### Parameters

    <ResponseField name="state" type="string">
      Filter by domain state: active, unverified, disabled (Default: `active`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "DomainSummary": {
          "additionalProperties": false,
          "properties": {
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Name"
            },
            "state": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "State"
            },
            "type": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Type"
            },
            "created_at": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Created At"
            },
            "smtp_login": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Smtp Login"
            },
            "web_prefix": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Web Prefix"
            }
          },
          "title": "DomainSummary",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "domains": {
          "items": {
            "$ref": "#/$defs/DomainSummary"
          },
          "title": "Domains",
          "type": "array"
        },
        "total_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Total Count"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListDomainsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_mailinglist_members — List all members of a Mailgun mailing list">
    ### Parameters

    <ResponseField name="list_address" type="string" required>
      Mailing list address (e.g. [list@yourdomain.com](mailto:list@yourdomain.com))
    </ResponseField>

    <ResponseField name="subscribed" type="string">
      Filter by subscription: 'true' for subscribed only, 'false' for unsubscribed only, or omit for all
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "MailinglistMember": {
          "additionalProperties": false,
          "properties": {
            "address": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Address"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Name"
            },
            "subscribed": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Subscribed"
            },
            "vars": {
              "anyOf": [
                {
                  "additionalProperties": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Vars"
            }
          },
          "title": "MailinglistMember",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "members": {
          "items": {
            "$ref": "#/$defs/MailinglistMember"
          },
          "title": "Members",
          "type": "array"
        },
        "total_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Total Count"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListMailinglistMembersOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="retrieve_mailinglist_member — Get details of a specific mailing list member by email address">
    ### Parameters

    <ResponseField name="list_address" type="string" required>
      Mailing list address (e.g. [list@yourdomain.com](mailto:list@yourdomain.com))
    </ResponseField>

    <ResponseField name="address" type="string" required>
      Email address of the member to retrieve
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "MailinglistMember": {
          "additionalProperties": false,
          "properties": {
            "address": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Address"
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Name"
            },
            "subscribed": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Subscribed"
            },
            "vars": {
              "anyOf": [
                {
                  "additionalProperties": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "integer"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Vars"
            }
          },
          "title": "MailinglistMember",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "member": {
          "anyOf": [
            {
              "$ref": "#/$defs/MailinglistMember"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "success"
      ],
      "title": "RetrieveMailinglistMemberOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="suppress_email — Add an email address to a Mailgun suppression list (bounces, unsubscribes, or complaints)">
    ### Parameters

    <ResponseField name="domain" type="string" required>
      Mailgun domain name
    </ResponseField>

    <ResponseField name="email" type="string" required>
      Email address to suppress
    </ResponseField>

    <ResponseField name="category" type="string" required>
      Suppression list category: bounces, unsubscribes, or complaints
    </ResponseField>

    <ResponseField name="bounce_error_code" type="string">
      Bounce error code (only for 'bounces' category) (Default: `550`)
    </ResponseField>

    <ResponseField name="bounce_error_message" type="string">
      Bounce error message (only for 'bounces' category)
    </ResponseField>

    <ResponseField name="unsubscribe_tag" type="string">
      Tag to unsubscribe from (only for 'unsubscribes' category). Use '\*' for all. (Default: `*`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Message"
        }
      },
      "required": [
        "success"
      ],
      "title": "SuppressEmailOutput",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Limits & Quotas

* **Free tier**: 100 emails/day for the first 30 days (sandbox domain).
* **Paid plans**: rate limits vary by plan; see [https://www.mailgun.com/pricing/](https://www.mailgun.com/pricing/).
* **Email validation**: billed separately per validation request.
* **Error model**: non-2xx responses and timeouts are caught and returned as `success=False` + `error` rather than raising.

## Related integrations

<CardGroup cols={3}>
  <Card title="AgentMail" href="/integrations/tools/agentmail" />

  <Card title="Gmail" href="/integrations/tools/gmail" />

  <Card title="Microsoft Outlook" href="/integrations/tools/microsoft-outlook" />
</CardGroup>

## Links

* [Mailgun](https://www.mailgun.com)