Mailgun

Send, route, and track transactional email and validate addresses via the Mailgun API.

This is a standard-library Python InTouch tool (no external packages). It talks to Mailgun over HTTPS using HTTP Basic authentication and returns the raw API response as a JSON string in result alongside the HTTP status.

What it does

• send-message — send a transactional email through your Mailgun domain
• validate-address — check whether an email address is deliverable
• list-events — read delivery/open/click/failure events for a domain (tracking)
• list-routes — list inbound routing rules on the account
• create-route — create an inbound routing rule (forward, store, stop)

Base URL & regions

Set region: eu if your domain is hosted in the EU; otherwise leave it blank (US). The region must match where your sending domain lives.

Authentication (apiKey)

Mailgun uses HTTP Basic auth with the username api and your API key as the password (the classic --user 'api:YOUR_API_KEY' curl idiom). The tool encodes this for you — just supply apiKey.

To get a key:

1. Sign in to the Mailgun dashboard.
2. Open API Keys.
3. Use your account API key for full access (validation, events, routes), or create a Domain Sending Key for send-only access scoped to one domain.

credentialBased: false — the key is passed inline as the apiKey input.

Operations & endpoints

Inputs

• apiKey (required) — Mailgun API key
• operation (required) — one of the five operations above
• region — us (default) or eu
• domain — sending domain (send-message, list-events)
• from, to, subject, text, html — send-message fields
• address, providerLookup — validate-address fields
• event, limit — list-events filters
• limit, skip — list-routes pagination
• expression, action, description, priority — create-route fields

to may be comma-separated for multiple recipients. For create-route, supply multiple actions by separating them with || (e.g. forward('https://x/hook')||store()).

Examples

Send an email

{
  "apiKey": "key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "operation": "send-message",
  "domain": "mg.example.com",
  "from": "Excited User <[email protected]>",
  "to": "[email protected]",
  "subject": "Hello there!",
  "text": "Testing some Mailgun awesomeness!"
}

Validate an address

{
  "apiKey": "key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "operation": "validate-address",
  "address": "[email protected]"
}

List recent delivery events

{
  "apiKey": "key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "operation": "list-events",
  "domain": "mg.example.com",
  "event": "failed",
  "limit": "25"
}

Create an inbound route (forward to a webhook)

{
  "apiKey": "key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "operation": "create-route",
  "expression": "match_recipient('.*@mg.example.com')",
  "action": "forward('https://example.com/incoming')||stop()",
  "description": "Forward all inbound mail to our webhook",
  "priority": "1"
}

Output

Every call returns:

• result — the Mailgun API response body as a JSON string
• status — the HTTP status code as a string (e.g. 200)

On a transport error the tool prints {"error": "..."} and exits non-zero so the job step is marked FAILED. HTTP 4xx/5xx responses are not treated as transport errors — Mailgun's error JSON is returned in result with the real status so you can branch on it.