<!-- Generated by `just docs` from catalog/toolkits/mailgun.yaml, catalog/expansions/mailgun.yaml, catalog/evals/scorecard.json. Edit the source, not this file. -->

# Mailgun

Transactional email. Send messages, manage sending domains and templates, read delivery events, and handle bounces.

| Property | Value |
| --- | --- |
| Slug | `mailgun` |
| Definition version | `0.1.0` |
| Base URL | `https://api.mailgun.net` |
| Auth schemes | `api_key` |
| Action tools | 37 |
| By class | 16 read, 14 write, 7 destructive |
| Triggers | 0 |
| Provider rate limit | not declared, so outbound calls are unpaced |

## Measured routing accuracy

74 golden cases replayed through the router over the whole index: measured over corpus `ea4f12ad2948` (65 toolkits, 2283 tools indexed and 13 declared uncallable), 37 cases written by hand and 37 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

| Measure | Cases | Share |
| --- | --- | --- |
| top-1 | 37/74 | 50.0% |
| top-8 | 59/74 | 79.7% |

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. `just eval-live` measures the same cases through the live reranker.

## Authentication

Connect an entity with `ConnectionsService.InitiateConnection`, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

### `api_key`

| Property | Value |
| --- | --- |
| Placement | `header` |
| Name | `Authorization` |
| Rendered as | `Basic {key}` |

Submit the key with `ConnectionsService` rather than putting it in a request; it is sealed at rest and never returned.

## Tools

37 action tools. The catalog-wide slug is `mailgun.<tool>`, which is what `search_tools` returns and `call_tool` takes.

### `mailgun.list_domains`

List the sending domains configured on this Mailgun account, paginated. Use when the user asks what domains, sending domains, or verified domains exist in Mailgun, rather than looking up one specific domain.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/domains`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `limit` | integer | no | Page size, default 100. |
| `skip` | integer | no | Number of domains to skip, for pagination. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].created_at` | string |  |
| `items[].name` | string |  |
| `items[].state` | string | Verification state, e.g. "active", "unverified", "disabled". |
| `items[].type` | string | "sending" or "receiving". |
| `total_count` | integer |  |

Also retrieved by: "what domains are hooked up to send mail", "show every sending domain on the account", "browse the domains we've registered", "see which hostnames are set up to email from".

### `mailgun.get_domain`

Get one Mailgun sending domain's full details by name: its verification state, DKIM/SPF setup, and the DNS records it still needs. Use when the user names a specific domain rather than browsing all of them, or asks why a domain won't verify.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/domains/{{params.domain}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain name, e.g. "mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `domain` | object |  |
| `domain.created_at` | string |  |
| `domain.name` | string |  |
| `domain.spam_action` | string |  |
| `domain.state` | string |  |
| `receiving_dns_records` | array of object |  |
| `receiving_dns_records[].record_type` | string |  |
| `receiving_dns_records[].valid` | string |  |
| `receiving_dns_records[].value` | string |  |
| `sending_dns_records` | array of object |  |
| `sending_dns_records[].record_type` | string |  |
| `sending_dns_records[].valid` | string |  |
| `sending_dns_records[].value` | string |  |

Also retrieved by: "check the dns setup for our sending domain", "pull up details on one hostname we send from", "why won't this domain verify".

### `mailgun.create_domain`

Register a new sending domain in Mailgun. Use when the user wants to add, connect, or set up a new domain to send email from, not verify or configure a domain that already exists. Returns the DNS records the domain must add before it can send.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /v3/domains`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain name to add, e.g. "mg.example.com". |
| `force_dkim_authority` | boolean | no | Whether this domain signs its own DKIM instead of inheriting signing from its root domain. |
| `spam_action` | string | no | How to handle mail flagged as spam: "disabled" (default), "block" (reject it), or "tag" (add a header). |
| `wildcard` | boolean | no | Whether to accept mail for every subdomain of this domain. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `domain` | object |  |
| `domain.name` | string |  |
| `domain.state` | string |  |
| `message` | string |  |
| `receiving_dns_records` | array of object |  |
| `receiving_dns_records[].record_type` | string |  |
| `receiving_dns_records[].value` | string |  |
| `sending_dns_records` | array of object |  |
| `sending_dns_records[].record_type` | string |  |
| `sending_dns_records[].value` | string |  |

Also retrieved by: "hook up a new hostname to send email from", "register a fresh domain for outbound mail", "set up a new place to send from", "connect another domain to the account".

### `mailgun.delete_domain`

Permanently delete a Mailgun sending domain, stopping it from sending or receiving any mail. Use when the user wants to remove, decommission, or delete a domain entirely, not disable one temporarily. Irreversible; the domain's own DNS records must be removed separately at the registrar.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `domains.write`. Calls `DELETE /v3/domains/{{params.domain}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain name to delete, e.g. "mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `message` | string |  |

Also retrieved by: "decommission a sending domain for good", "remove a hostname from the account entirely", "shut down a domain we no longer use".

### `mailgun.verify_domain`

Re-check a Mailgun domain's DNS records and refresh its verification state. Use when the user just added the required DNS records and wants Mailgun to confirm the domain, or asks why a domain is still showing unverified.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `PUT /v3/domains/{{params.domain}}/verify`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain name to re-verify, e.g. "mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `domain` | object |  |
| `domain.name` | string |  |
| `domain.state` | string |  |
| `message` | string |  |

Also retrieved by: "recheck the dns records for this hostname", "confirm the domain now that records are in place", "re-run the verification check".

### `mailgun.update_domain_connection_settings`

Change a Mailgun domain's delivery connection settings: whether to require TLS on outbound delivery and whether to skip certificate verification on the receiving server. Use when the user wants to enforce or relax TLS for a domain's outgoing mail, not its DNS or spam handling.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `PUT /v3/domains/{{params.domain}}/connection`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain name, e.g. "mg.example.com". |
| `require_tls` | boolean | no | Whether outbound delivery must use TLS or fail. |
| `skip_verification` | boolean | no | Whether to skip TLS certificate verification on the receiving server. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `connection` | object |  |
| `connection.require_tls` | boolean |  |
| `connection.skip_verification` | boolean |  |

Also retrieved by: "force tls on outbound delivery for this domain", "toggle strict certificate checking for sends", "change how strict the delivery connection is".

### `mailgun.send_message`

Send a transactional email through Mailgun from a verified sending domain, either as raw text/HTML or rendered from a saved template. Use when the user wants to send, deliver, or email a message right now. This is the core send action, distinct from managing domains, templates, or suppressions.

Class `write` (writes, no confirmation needed). Scopes `messages.write`. Calls `POST /v3/{{params.domain}}/messages`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `bcc` | array of string | no | BCC email addresses. |
| `cc` | array of string | no | CC email addresses. |
| `domain` | string | **yes** | Sending domain, e.g. "mg.example.com". |
| `from` | string | **yes** | Sender address, e.g. "Support <support@mg.example.com>". |
| `html` | string | no | HTML body. |
| `subject` | string | no | Email subject line. |
| `tags` | array of string | no | Up to three tags to attach, for later filtering in events and stats. |
| `template` | string | no | Name of a saved Mailgun template to render instead of text/html. |
| `template_variables` | object | no | Merge variables passed into the template for this send. |
| `template_version` | string | no | Specific version tag of the template to render. Omit to use its active version. |
| `text` | string | no | Plain-text body. |
| `to` | array of string | **yes** | Recipient email addresses. |
| `tracking` | boolean | no | Whether to enable open and click tracking for this message. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string |  |
| `message` | string |  |

Also retrieved by: "fire off a transactional email right now", "deliver a message to this recipient", "email someone from our domain", "push out a notification email", "render a template and mail it to someone".

### `mailgun.list_events`

List Mailgun delivery events for a domain: accepted, delivered, failed, opened, clicked, unsubscribed, or complained, filterable by event type, recipient, and time range. Use when the user asks what happened to a message, wants delivery logs, or wants recent activity for a domain.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/{{params.domain}}/events`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `begin` | string | no | Start of the time range, RFC 2822 or RFC 3339. |
| `domain` | string | **yes** | Domain to read events for, e.g. "mg.example.com". |
| `end` | string | no | End of the time range, RFC 2822 or RFC 3339. |
| `event` | string | no | Filter to one event type: "accepted", "delivered", "failed", "opened", "clicked", "unsubscribed", or "complained". Omit to include every type. |
| `limit` | integer | no | Page size, default 100. |
| `recipient` | string (email) | no | Filter to events for one recipient address. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].delivery-status` | object |  |
| `items[].delivery-status.code` | integer |  |
| `items[].delivery-status.message` | string |  |
| `items[].event` | string |  |
| `items[].message` | object |  |
| `items[].message.headers` | object |  |
| `items[].reason` | string |  |
| `items[].recipient` | string |  |
| `items[].timestamp` | number |  |

Also retrieved by: "what happened to this message", "pull the delivery logs for this domain", "show recent activity like opens and clicks", "check why a send failed".

### `mailgun.validate_email`

Check whether a single email address is valid and deliverable before sending to it. Use when the user wants to verify, check, or clean an address, or asks whether it is real, disposable, or a role account like "info@" or "support@". This checks one address, distinct from domain verification.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v4/address/validate`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string (email) | **yes** | Email address to validate. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `address` | string |  |
| `did_you_mean` | string |  |
| `is_disposable_address` | boolean |  |
| `is_role_address` | boolean |  |
| `reason` | array of string |  |
| `result` | string | "deliverable", "undeliverable", "do_not_send", "catch_all", or "unknown". |
| `risk` | string |  |

Also retrieved by: "is this address even real", "check if this inbox actually exists before sending", "clean this email before adding it anywhere", "is this a throwaway or role account".

### `mailgun.list_bounces`

List the email addresses Mailgun has suppressed for bouncing on a domain, paginated. Use when the user asks which addresses are bouncing or blocked as bounces, rather than looking up one specific address.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/{{params.domain}}/bounces`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain to list bounces for, e.g. "mg.example.com". |
| `limit` | integer | no | Page size, default 100. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].address` | string |  |
| `items[].code` | string |  |
| `items[].created_at` | string |  |
| `items[].error` | string |  |
| `total_count` | integer |  |

Also retrieved by: "which addresses are bouncing right now", "show me who's blocked as undeliverable", "browse the bounced addresses on this domain".

### `mailgun.get_bounce`

Check whether one email address is on a Mailgun domain's bounce suppression list, and why. Use when the user names a specific address rather than browsing the full bounce list.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/{{params.domain}}/bounces/{{params.address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string (email) | **yes** | Email address to look up. |
| `domain` | string | **yes** | Domain the address bounced on, e.g. "mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `address` | string |  |
| `code` | string |  |
| `created_at` | string |  |
| `error` | string |  |

Also retrieved by: "why did this address bounce", "check if this recipient is stuck on the bounce list", "pull the failure reason for one recipient".

### `mailgun.create_bounce`

Manually add an email address to a Mailgun domain's bounce suppression list, blocking future sends to it. Use when the user wants to proactively suppress or block an address, not remove one that already bounced on its own.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /v3/{{params.domain}}/bounces`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string (email) | **yes** | Email address to suppress. |
| `code` | string | no | SMTP bounce code to record, e.g. "550". Defaults to "550". |
| `domain` | string | **yes** | Domain to suppress the address on, e.g. "mg.example.com". |
| `error` | string | no | Free-text reason for the suppression. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `address` | string |  |
| `created_at` | string |  |
| `message` | string |  |

Also retrieved by: "block this address from ever getting mail", "proactively suppress a bad recipient", "add this inbox to the do-not-send list".

### `mailgun.delete_bounce`

Remove one email address from a Mailgun domain's bounce suppression list, allowing mail to it again. Use when the user wants to un-suppress, unblock, or retry an address that was incorrectly or is no longer bouncing.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `DELETE /v3/{{params.domain}}/bounces/{{params.address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string (email) | **yes** | Email address to un-suppress. |
| `domain` | string | **yes** | Domain the address is suppressed on, e.g. "mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `message` | string |  |

Also retrieved by: "let mail through to this address again", "clear the bounce flag on this recipient", "retry sending to a previously bounced inbox".

### `mailgun.list_unsubscribes`

List the email addresses that have unsubscribed from a Mailgun domain, paginated. Use when the user asks who has opted out or unsubscribed, rather than looking up one specific address.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/{{params.domain}}/unsubscribes`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain to list unsubscribes for, e.g. "mg.example.com". |
| `limit` | integer | no | Page size, default 100. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].address` | string |  |
| `items[].created_at` | string |  |
| `items[].tags` | array of string |  |
| `total_count` | integer |  |

Also retrieved by: "who has opted out of our mail", "show everyone who unsubscribed", "browse the opt-out list for this domain".

### `mailgun.get_unsubscribe`

Check whether one email address has unsubscribed from a Mailgun domain, and from which tag. Use when the user names a specific address rather than browsing the full unsubscribe list.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/{{params.domain}}/unsubscribes/{{params.address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string (email) | **yes** | Email address to look up. |
| `domain` | string | **yes** | Domain to check, e.g. "mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `address` | string |  |
| `created_at` | string |  |
| `tags` | array of string |  |

Also retrieved by: "did this person opt out", "check if this recipient unsubscribed already", "which tag did this address opt out of".

### `mailgun.create_unsubscribe`

Manually mark an email address as unsubscribed from a Mailgun domain, so it stops receiving mail tagged that way. Use when the user wants to opt someone out proactively, for example honoring an opt-out request made outside Mailgun's own unsubscribe link.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /v3/{{params.domain}}/unsubscribes`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string (email) | **yes** | Email address to unsubscribe. |
| `domain` | string | **yes** | Domain to unsubscribe the address from, e.g. "mg.example.com". |
| `tag` | string | no | Restrict the unsubscribe to one message tag. Use "*" (the default) to unsubscribe from everything sent from this domain. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `address` | string |  |
| `created_at` | string |  |
| `message` | string |  |
| `tag` | string |  |

Also retrieved by: "honor an opt-out someone requested by phone", "mark this person as opted out manually", "stop sending to someone who asked outside the usual link".

### `mailgun.delete_unsubscribe`

Remove an email address from a Mailgun domain's unsubscribe list, so it can receive mail again. Use when the user wants to resubscribe or reinstate an address that had previously opted out.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `DELETE /v3/{{params.domain}}/unsubscribes/{{params.address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string (email) | **yes** | Email address to resubscribe. |
| `domain` | string | **yes** | Domain the address unsubscribed from, e.g. "mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `message` | string |  |

Also retrieved by: "let this person receive our mail again", "reinstate someone who had opted out", "undo an unsubscribe for this recipient".

### `mailgun.list_complaints`

List the email addresses that have marked mail from a Mailgun domain as spam, paginated. Use when the user asks who complained or reported spam, rather than looking up one specific address.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/{{params.domain}}/complaints`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain to list complaints for, e.g. "mg.example.com". |
| `limit` | integer | no | Page size, default 100. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].address` | string |  |
| `items[].created_at` | string |  |
| `total_count` | integer |  |

Also retrieved by: "who reported our mail as spam", "show everyone who flagged us as junk", "browse spam reports for this domain".

### `mailgun.get_complaint`

Check whether one email address has filed a spam complaint against a Mailgun domain. Use when the user names a specific address rather than browsing the full complaint list.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/{{params.domain}}/complaints/{{params.address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string (email) | **yes** | Email address to look up. |
| `domain` | string | **yes** | Domain to check, e.g. "mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `address` | string |  |
| `created_at` | string |  |

Also retrieved by: "did this recipient mark us as spam", "check for a spam flag on this address", "has this person filed a junk report".

### `mailgun.create_complaint`

Manually add an email address to a Mailgun domain's spam complaint list, suppressing future sends to it. Use when the user wants to record a complaint that was reported outside Mailgun's own feedback loop.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /v3/{{params.domain}}/complaints`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string (email) | **yes** | Email address that complained. |
| `domain` | string | **yes** | Domain to suppress the address on, e.g. "mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `address` | string |  |
| `created_at` | string |  |
| `message` | string |  |

Also retrieved by: "log a spam report that came in some other way", "record that someone flagged this as junk", "note down a junk report we heard about by phone".

### `mailgun.delete_complaint`

Remove an email address from a Mailgun domain's spam complaint list, allowing mail to it again. Use when the user believes a complaint was filed in error and wants to reinstate the address.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). No scopes beyond the connection's defaults. Calls `DELETE /v3/{{params.domain}}/complaints/{{params.address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `address` | string (email) | **yes** | Email address to reinstate. |
| `domain` | string | **yes** | Domain the address complained on, e.g. "mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `message` | string |  |

Also retrieved by: "this complaint was filed by mistake, clear it", "reinstate an address wrongly marked as spam", "this junk report doesn't belong here, take it off".

### `mailgun.list_mailing_lists`

List the mailing lists on this Mailgun account, paginated. Use when the user asks what mailing lists or distribution lists exist, rather than looking up one specific list.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/lists`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `limit` | integer | no | Page size, default 100. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].access_level` | string |  |
| `items[].address` | string |  |
| `items[].description` | string |  |
| `items[].members_count` | integer |  |
| `items[].name` | string |  |
| `total_count` | integer |  |

Also retrieved by: "what distribution lists do we have", "show every subscriber list on the account", "browse our mailgun groups".

### `mailgun.get_mailing_list`

Get one Mailgun mailing list's details by address: its name, description, member count, and who can post to it. Use when the user names a specific list rather than browsing all of them.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/lists/{{params.list_address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `list_address` | string | **yes** | Mailing list's own email address, e.g. "announce@mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `list` | object |  |
| `list.access_level` | string |  |
| `list.address` | string |  |
| `list.created_at` | string |  |
| `list.description` | string |  |
| `list.members_count` | integer |  |
| `list.name` | string |  |

Also retrieved by: "pull up info on our announcement list", "check who can post to this distribution list", "how many subscribers does this group have".

### `mailgun.create_mailing_list`

Create a new Mailgun mailing list. Use when the user wants to start a new distribution list or subscriber list on Mailgun, not add a person to a list that already exists. Requires the list's own posting address.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /v3/lists`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `access_level` | string | no | Who can post to the list: "readonly" (only the list owner), "members" (any member), or "everyone". Defaults to "readonly". |
| `description` | string | no | What the list is for. |
| `list_address` | string | **yes** | New mailing list's own email address, e.g. "announce@mg.example.com". |
| `name` | string | no | Display name for the list. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `list` | object |  |
| `list.access_level` | string |  |
| `list.address` | string |  |
| `list.name` | string |  |
| `message` | string |  |

Also retrieved by: "start a new distribution list", "set up a group people can subscribe to", "build a fresh announcement list".

### `mailgun.update_mailing_list`

Update an existing Mailgun mailing list's name, description, or who can post to it. Use when the user wants to edit a list's settings, not add or remove a member.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `PUT /v3/lists/{{params.list_address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `access_level` | string | no | New posting permission: "readonly", "members", or "everyone". |
| `description` | string | no | New description of what the list is for. |
| `list_address` | string | **yes** | Mailing list's own email address, e.g. "announce@mg.example.com". |
| `name` | string | no | New display name for the list. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `list` | object |  |
| `list.access_level` | string |  |
| `list.address` | string |  |
| `list.name` | string |  |

Also retrieved by: "change who's allowed to post to this list", "edit the description on this distribution list", "rename this announcement group".

### `mailgun.delete_mailing_list`

Permanently delete a Mailgun mailing list and every member on it. Use when the user wants to remove, delete, or shut down an entire mailing list, not unsubscribe one person. Irreversible.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `lists.write`. Calls `DELETE /v3/lists/{{params.list_address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `list_address` | string | **yes** | Mailing list's own email address to delete, e.g. "announce@mg.example.com". |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `address` | string |  |
| `message` | string |  |

Also retrieved by: "shut down this whole distribution list", "get rid of a group and everyone in it", "tear down a list we don't need anymore".

### `mailgun.add_list_member`

Add one new subscriber to a Mailgun mailing list, or update one that already exists there. Use when the user wants to subscribe, sign up, or add a single person's email to a list. For adding many people at once use add_list_members_bulk instead.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /v3/lists/{{params.list_address}}/members`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `list_address` | string | **yes** | Mailing list's own email address, e.g. "announce@mg.example.com". |
| `member_address` | string (email) | **yes** | New subscriber's email address. |
| `name` | string | no | Subscriber's display name. |
| `subscribed` | boolean | no | Whether the member is active on the list. Defaults to true. |
| `upsert` | boolean | no | Update the member instead of failing if the address already exists. |
| `vars` | object | no | Custom merge variables to store with this subscriber. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `member` | object |  |
| `member.address` | string |  |
| `member.name` | string |  |
| `member.subscribed` | boolean |  |
| `message` | string |  |

Also retrieved by: "sign someone up for this distribution list", "get one person subscribed to the group", "put this email on the announcement list".

### `mailgun.get_list_member`

Get one Mailgun mailing list subscriber's record by list and address: their name, custom variables, and subscription status. Use when the user names a specific person already on the list.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/lists/{{params.list_address}}/members/{{params.member_address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `list_address` | string | **yes** | Mailing list's own email address, e.g. "announce@mg.example.com". |
| `member_address` | string (email) | **yes** | Subscriber's email address. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `member` | object |  |
| `member.address` | string |  |
| `member.name` | string |  |
| `member.subscribed` | boolean |  |
| `member.vars` | object |  |

Also retrieved by: "pull up one subscriber's record", "check this person's status on the group", "what merge variables do we have on file for them".

### `mailgun.list_list_members`

List the subscribers on a Mailgun mailing list, paginated, optionally filtered to only active or only unsubscribed members. Use for browsing or exporting a list's membership rather than looking up one specific subscriber.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/lists/{{params.list_address}}/members/pages`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `limit` | integer | no | Page size, default 100. |
| `list_address` | string | **yes** | Mailing list's own email address, e.g. "announce@mg.example.com". |
| `subscribed` | string | no | Filter to "yes" (active) or "no" (unsubscribed). Omit for both. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].address` | string |  |
| `items[].name` | string |  |
| `items[].subscribed` | boolean |  |

Also retrieved by: "who's subscribed to this distribution list", "export the roster of this group", "see everyone on the announcement list".

### `mailgun.update_list_member`

Update a Mailgun mailing list subscriber's name, custom variables, or subscription status. Use when the user wants to edit, resubscribe, or unsubscribe an existing member, not add a new person.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `PUT /v3/lists/{{params.list_address}}/members/{{params.member_address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `list_address` | string | **yes** | Mailing list's own email address, e.g. "announce@mg.example.com". |
| `member_address` | string (email) | **yes** | Subscriber's email address. |
| `name` | string | no | New display name for the subscriber. |
| `subscribed` | boolean | no | New subscription status. |
| `vars` | object | no | New custom merge variables for the subscriber. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `member` | object |  |
| `member.address` | string |  |
| `member.name` | string |  |
| `member.subscribed` | boolean |  |

Also retrieved by: "fix this subscriber's info on the list", "resubscribe someone who had opted out of the group", "change the merge variables stored for this person".

### `mailgun.delete_list_member`

Permanently remove one subscriber from a Mailgun mailing list. Use when the user wants to unsubscribe, remove, or delete a single person from a list. Irreversible; re-adding them requires their email address again.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `lists.write`. Calls `DELETE /v3/lists/{{params.list_address}}/members/{{params.member_address}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `list_address` | string | **yes** | Mailing list's own email address, e.g. "announce@mg.example.com". |
| `member_address` | string (email) | **yes** | Subscriber's email address to remove. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `member` | object |  |
| `member.address` | string |  |
| `message` | string |  |

Also retrieved by: "take this person off the distribution list", "remove one subscriber from the group", "drop them off the announcement roster for good".

### `mailgun.add_list_members_bulk`

Add or update many subscribers on a Mailgun mailing list in one call. Use when the user wants to import, upload, or bulk-add a batch of people to a list, not add one person at a time with add_list_member.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /v3/lists/{{params.list_address}}/members.json`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `list_address` | string | **yes** | Mailing list's own email address, e.g. "announce@mg.example.com". |
| `members` | array of object | **yes** | Subscribers to add or update. |
| `members[].address` | string (email) | no |  |
| `members[].name` | string | no |  |
| `members[].subscribed` | boolean | no |  |
| `members[].vars` | object | no |  |
| `upsert` | boolean | no | Update existing members instead of failing when an address already exists. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `list` | object |  |
| `list.address` | string |  |
| `task` | object |  |
| `task.id` | string |  |
| `task.status` | string |  |

Also retrieved by: "import a batch of subscribers at once", "upload a csv of people into the group", "bulk add a bunch of new members".

### `mailgun.list_templates`

List the reusable transactional email templates saved for a Mailgun domain, paginated. Use when the user asks what templates exist, rather than looking up one specific template.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/{{params.domain}}/templates`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain the templates belong to, e.g. "mg.example.com". |
| `limit` | integer | no | Page size, default 100. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `items` | array of object |  |
| `items[].createdAt` | string |  |
| `items[].description` | string |  |
| `items[].name` | string |  |
| `total_count` | integer |  |

Also retrieved by: "what reusable email designs do we have saved", "show every transactional template", "browse our saved message layouts".

### `mailgun.get_template`

Get one Mailgun template's details by name, including its active version's content. Use when the user names a specific template rather than browsing all of them, or wants to review what it currently says.

Class `read` (reads only). No scopes beyond the connection's defaults. Calls `GET /v3/{{params.domain}}/templates/{{params.name}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain the template belongs to, e.g. "mg.example.com". |
| `name` | string | **yes** | Template name. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `template` | object |  |
| `template.description` | string |  |
| `template.name` | string |  |
| `template.version` | object |  |
| `template.version.active` | boolean |  |
| `template.version.engine` | string |  |
| `template.version.tag` | string |  |
| `template.version.template` | string |  |

Also retrieved by: "show me the content of this saved template", "pull up what this email design currently says", "which version of this layout is active right now".

### `mailgun.create_template`

Save a new reusable transactional email template in Mailgun from HTML or plain text. Use when the user wants to create a template for use in send_message, not set the body of one specific message.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /v3/{{params.domain}}/templates`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `description` | string | no | What the template is for. |
| `domain` | string | **yes** | Domain to save the template under, e.g. "mg.example.com". |
| `engine` | string | no | Templating engine to render placeholders with: "handlebars" or "mustache". |
| `name` | string | **yes** | Template name. |
| `tag` | string | no | Version tag for this initial version, e.g. "initial". Defaults to "initial". |
| `template` | string | **yes** | Template body content for its first version. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `message` | string |  |
| `template` | object |  |
| `template.description` | string |  |
| `template.name` | string |  |

Also retrieved by: "save this html as a reusable message design", "store a new transactional layout for later", "build a new reusable notification design from scratch".

### `mailgun.create_template_version`

Add a new version to an existing Mailgun template. Use when the user wants to update, revise, or edit a template's content rather than create a brand-new template. Set active to true to make this the version send_message uses by default.

Class `write` (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls `POST /v3/{{params.domain}}/templates/{{params.name}}/versions`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `active` | boolean | no | Whether to make this the active version send_message uses by default. |
| `comment` | string | no | Free-text note about what changed in this version. |
| `domain` | string | **yes** | Domain the template belongs to, e.g. "mg.example.com". |
| `engine` | string | no | Templating engine to render placeholders with: "handlebars" or "mustache". |
| `name` | string | **yes** | Template name. |
| `tag` | string | **yes** | Version tag for this revision, e.g. "v2". |
| `template` | string | **yes** | This version's body content. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `message` | string |  |
| `template` | object |  |
| `template.name` | string |  |

Also retrieved by: "publish a new revision of this template", "update the content on an existing design", "make this the new active version of the layout".

### `mailgun.delete_template`

Permanently delete a Mailgun template and all of its versions. Use when the user wants to remove a saved template entirely; messages already sent from it are unaffected. Irreversible.

Class `destructive` (held by the mutation gate until the call's own arguments carry `"confirm": true`). Scopes `templates.write`. Calls `DELETE /v3/{{params.domain}}/templates/{{params.name}}`.

Arguments:

| Argument | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | **yes** | Domain the template belongs to, e.g. "mg.example.com". |
| `name` | string | **yes** | Template name to delete. |

Result fields (the payload is trimmed to these before it reaches the model):

| Field | Type | Notes |
| --- | --- | --- |
| `message` | string |  |

Also retrieved by: "remove a saved design we don't use anymore", "get rid of an old message layout for good", "clear out a stale notification design entirely".