Skip to main content
Mailgun logo

​
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).
Categories: Communication · Email · Auth: Mailgun API Key · Actions: 9

​
Authentication

​
Mailgun API Key

Authenticate using your Mailgun API key and region
1

Step 1

Log in to https://app.mailgun.com
2

Step 2

Go to Settings > API Security
3

Step 3

Copy your Private API key
4

Step 4

Set MAILGUN_REGION to ‘EU’ if your account is on the EU infrastructure, otherwise leave as ‘US’

​
Required Credentials

FieldDescriptionRequiredFormat
Mailgun API KeyPrivate API key from Mailgun dashboard (Settings > API Security)Yeskey-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Mailgun RegionAPI region: ‘US’ (default) or ‘EU’NoUS

​
Available Actions

​
Parameters

​
domain
string
required
Mailgun domain name to send from
​
from_name
string
required
Sender display name
​
from_email
string
required
Sender email address
​
to
array
required
Recipient email address(es) as a list of strings
​
subject
string
required
Email subject line
​
text
string
Plain text message body
​
html
string
HTML message body
​
reply_to
string
Reply-to email address
​
test_mode
boolean
Enable Mailgun test mode (message accepted but not delivered) (Default: true)
​
dkim
boolean
Enable or disable DKIM signatures on the message (Default: true)
​
tracking
boolean
Enable or disable tracking on the message (Default: true)

​
Response

{
  "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"
}

​
Parameters

​
email
string
required
Email address to verify

​
Response

{
  "$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"
}

​
Parameters

​
list_address
string
required
Mailing list address (e.g. list@yourdomain.com)
​
address
string
required
Email address of the member to add
​
name
string
Display name of the member
​
vars
object
Extra arbitrary member data as a JSON object
​
subscribed
string
Subscription status: ‘yes’ (default) or ‘no’ for unsubscribed (Default: yes)
​
upsert
string
If ‘yes’, update existing member; if ‘no’, error on duplicate. Values: yes, no (Default: no)

​
Response

{
  "$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"
}

​
Parameters

​
priority
integer
required
Route priority (lower numbers are evaluated first)
​
description
string
required
Human-readable description of the route
​
expression
string
required
Mailgun route filter expression, e.g. match_recipient(’.*@example.com’)
​
action
array
required
List of route action strings, e.g. [‘forward(“dest@example.com”)’, ‘stop()‘]

​
Response

{
  "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"
}

​
Parameters

​
list_address
string
required
Mailing list address (e.g. list@yourdomain.com)
​
address
string
required
Email address of the member to remove

​
Response

{
  "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"
}

​
Parameters

​
state
string
Filter by domain state: active, unverified, disabled (Default: active)

​
Response

{
  "$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"
}

​
Parameters

​
list_address
string
required
Mailing list address (e.g. list@yourdomain.com)
​
subscribed
string
Filter by subscription: ‘true’ for subscribed only, ‘false’ for unsubscribed only, or omit for all

​
Response

{
  "$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"
}

​
Parameters

​
list_address
string
required
Mailing list address (e.g. list@yourdomain.com)
​
address
string
required
Email address of the member to retrieve

​
Response

{
  "$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"
}

​
Parameters

​
domain
string
required
Mailgun domain name
​
email
string
required
Email address to suppress
​
category
string
required
Suppression list category: bounces, unsubscribes, or complaints
​
bounce_error_code
string
Bounce error code (only for ‘bounces’ category) (Default: 550)
​
bounce_error_message
string
Bounce error message (only for ‘bounces’ category)
​
unsubscribe_tag
string
Tag to unsubscribe from (only for ‘unsubscribes’ category). Use ’*’ for all. (Default: *)

​
Response

{
  "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"
}

​
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/.
  • 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.

AgentMail

Gmail

Microsoft Outlook