Mailgun

@keeb/mailgunv2026.08.26.1· 16d agoMODELS

01README

Mailgun email delivery models

02Release Notes

2026.08.26.1

Fixed: removed the API key preflight against GET /v5/users/me. It required account-level scope that none of these models otherwise need, so a domain-scoped key that could read /v4/domains perfectly well was rejected with 403 before its request was ever sent. Endpoints now report their own auth failures, with a hint distinguishing a wrong-region key (401) from an insufficiently scoped one (403).

2026.08.25.3

Changed: truncation is no longer silent. Every walk that stops short logs a warning and records it — lookup writes a _walk artifact, list_* methods carry truncated/truncationReason/maxItems in their result — so a partial list can't be presented as a complete one.
Added: max_items on the list_* methods, which previously walked uncapped. Every paginated method now has the same ceiling and the same default of 1000.
Fixed: a 404 on the first page of a walk now raises an error naming the domain global argument instead of returning an empty list. A mistyped domain was indistinguishable from a domain with no records.
Docs: README covers how to size max_items, when to filter instead of raising it, and how to detect a truncated answer.

2026.08.25.2

Added: lookup on event, exposing the upstream query parameters (recipient, event, begin, end, ascending, subject, message_id, tags, severity). Searching the event stream for one address no longer means pulling the stream and filtering client-side.
Added: max_items on every lookup method, defaulting to 1000 (300 on event). Paginated walks were previously bounded only by the 10,000-record page cap.
Fixed: README examples used a --arg flag that does not exist; method arguments are passed with --input, and object values need :json=.

03Models44

@keeb/mailgun/accountv2026.08.25.1account.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn update()

Update account attributes

fn create_http_signing_key()

Create or regenerate webhook signing key on an account

fn create_resend_activation_email()

Resend account activation email to the account owner

fn delete_limit_custom_monthly()

Delete a custom sending limit

fn get_http_signing_key()

Get webhook signing key saved on the account

fn get_limit_custom_monthly()

Get current custom sending limit

fn limit_custom_enable()

Re-enable account disabled for hitting send limit

fn update_features(webhooks_redact_pii?: string, ai_insights?: string)

Update account feature

Argument	Type	Required	Description
webhooks_redact_pii?	string	no	JSON object encoded as a string
ai_insights?	string	no	JSON object encoded as a string

fn update_limit_custom_monthly()

Set a custom sending limit

Resources

state(infinite)— Account resource state

account_action(ephemeral)— Account action result

@keeb/mailgun/account-templatev2026.08.25.3account_template.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
description?	string	no	Description of the template being stored
name	string	yes	Name of the template being stored. Supports utf-8 characters and name will be down cased.
createdBy?	string	no	Optional metadata field api user can indicate who created the template.
template?	string	no	Content of the template.
tag?	string	no	Initial tag of the created version. If the template parameter is provided and the tag is missing, the default value `initial` is used.
comment?	string	no	Version comment. This is valid only if a new version is being created. (template parameter is provided.)
headers?	string	no	Key value JSON object of headers to be stored with the template. Where key is the header name and value is the header value. The header names `From`, `Subject`, and `Reply-To` are the only ones currently supported.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a account template

fn get(id: string)

Get a account template

Argument	Type	Required	Description
id	string	yes	The name of the account template

fn lookup(max_items?: number)

List every account template and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update account template attributes

fn delete(id: string)

Delete the account template

Argument	Type	Required	Description
id	string	yes	The name of the account template

fn sync()

Sync account template state from Mailgun

fn copy(template_name: string, requests: array, source_versions?: array)

Copy a template

Argument	Type	Required	Description
template_name	string	yes	Path parameter: template_name
requests	array	yes	List of copy requests
source_versions?	array	no	Versions to copy or all versions if empty.

fn rename(template_name: string, new_template_name: string)

Rename a template

Argument	Type	Required	Description
template_name	string	yes	Path parameter: template_name
new_template_name	string	yes	Path parameter: new_template_name

Resources

state(infinite)— Account template resource state

account_template_action(ephemeral)— Account template action result

@keeb/mailgun/account-template-versionv2026.08.25.3account_template_version.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
template_name	string	yes	Path scope for the account template version: template_name
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
template	string	yes	Content of the template.
comment?	string	no	Comment related to the version that is being created.
active?	string	no	If this flag is set to yes, this version becomes active
headers?	string	no	Key value JSON object of headers to be stored with the template.
tag	string	yes	Tag of the version that is being created. Must be unique to the template.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a account template version

fn get(id: string)

Get a account template version

Argument	Type	Required	Description
id	string	yes	The name of the account template version

fn lookup(max_items?: number)

List every account template version and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update account template version attributes

fn delete(id: string)

Delete the account template version

Argument	Type	Required	Description
id	string	yes	The name of the account template version

fn sync()

Sync account template version state from Mailgun

fn copy(version_name: string, new_version_name: string)

Copy an account-level template version

Argument	Type	Required	Description
version_name	string	yes	Path parameter: version_name
new_version_name	string	yes	Path parameter: new_version_name

Resources

state(infinite)— Account template version resource state

account_template_version_action(ephemeral)— Account template version action result

@keeb/mailgun/account-webhookv2026.08.25.3account_webhook.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
description?	string	no	Description for the webhook
event_types	enum	yes	Event types to subscribe to. Use multiple times to specify multiple event types. Maximum of 3 unique URLs per event type.
url	string	yes	URL for webhook to be sent to
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a account webhook

fn get(id: string)

Get a account webhook

Argument	Type	Required	Description
id	string	yes	The id of the account webhook

fn lookup(max_items?: number)

List every account webhook and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update account webhook attributes

fn delete(id: string)

Delete the account webhook

Argument	Type	Required	Description
id	string	yes	The id of the account webhook

fn sync()

Sync account webhook state from Mailgun

Resources

state(infinite)— Account webhook resource state

@keeb/mailgun/alertv2026.08.25.3alert.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn delete_settings_slack()

Delete Slack settings

fn delete_slack_oauth()

Revoke Slack access token

fn email_test(event_type: string, emails: array)

Test message

Argument	Type	Required	Description
event_type	string	yes
emails	array	yes

fn get_settings()

List Alerts

fn list_events(max_items?: number)

List events

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn slack_test(event_type: string, channel_ids?: array)

Test message

Argument	Type	Required	Description
event_type	string	yes
channel_ids?	array	no	If omitted would be taken from the event settings

fn update_settings_slack(token: string, team_id?: string, team_name?: string, scope?: string)

Update Slack settings

Argument	Type	Required
token	string	yes
team_id?	string	no
team_name?	string	no
scope?	string	no

fn update_settings_webhooks_signing_key()

Reset Webhook Signing Key

fn webhooks_test(event_type: string, url: string)

Test webhook

Argument	Type	Required	Description
event_type	string	yes
url	string	yes

Resources

state(infinite)— Alert resource state

alert_action(ephemeral)— Alert action result

@keeb/mailgun/alert-eventv2026.08.25.1alert_event.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
event_type	string	yes	The type of event for which you would like to receive alerts.
channel	string	yes	The delivery method for the alert.
settings	object	yes	The details pertaining to the specified channel. Please note that the contents of this object differ per channel type.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a alert event

fn update()

Update alert event attributes

fn delete(id: string)

Delete the alert event

Argument	Type	Required	Description
id	string	yes	The id of the alert event

Resources

state(infinite)— Alert event resource state

@keeb/mailgun/allowlistv2026.08.25.3allowlist.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
address	string	yes	Valid email address if you would like to allowlist email address (prior over 'domain' parameter)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a allowlist

fn get(id: string)

Get a allowlist

Argument	Type	Required	Description
id	string	yes	The value of the allowlist

fn lookup(max_items?: number)

List every allowlist and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn delete(id: string)

Delete the allowlist

Argument	Type	Required	Description
id	string	yes	The value of the allowlist

fn sync()

Sync allowlist state from Mailgun

fn import(file: string)

Import allowlist

Argument	Type	Required	Description
file	string	yes	CSV file

Resources

state(infinite)— Allowlist resource state

allowlist_action(ephemeral)— Allowlist action result

@keeb/mailgun/analytics-logv2026.08.25.1analytics_log.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
start?	string	no	The start date (default: 1 day before current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
end?	string	no	The end date (default: current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
duration	string	yes	A duration in the format of '1d' '2h'. If duration is provided then it is calculated from the end date and overwrites the start date.
events?	array	no	The set of events to include.
metric_events?	array	no	Optional set of analytics metric events. Will be converted into corresponding events.
filter?	object	no	Filters to apply to the query.
include_subaccounts?	boolean	no	Include logs from all subaccounts.
include_totals?	boolean	no	Include total number of log entries.
pagination?	object	no
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a analytics log

Resources

state(infinite)— Analytics log resource state

@keeb/mailgun/analytics-metricv2026.08.25.1analytics_metric.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
start?	string	no	A start date (default: 7 days before current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
end?	string	no	An end date (default: current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
resolution?	string	no	A resolution in the format of 'day' 'hour' 'month'. Default is day.
duration?	string	no	A duration in the format of '1d' '2h' '2m'. If duration is provided then it is calculated from the end date and overwrites the start date.
dimensions?	array	no	Attributes of the metric data such as 'subaccount'. See [dimensions](https://documentation.mailgun.com/docs/mailgun/user-manual/reporting/dimensions)
metrics?	array	no	Name of the metrics to receive the stats for such as 'processed_count'. See [metrics](https://documentation.mailgun.com/docs/mailgun/user-manual/reporting/metric-definitions)
filter?	object	no	Filters to apply to the query.
include_subaccounts?	boolean	no	Include stats from all subaccounts.
include_aggregates?	boolean	no	Include top-level aggregate metrics.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a analytics metric

Resources

state(infinite)— Analytics metric resource state

@keeb/mailgun/analytics-tagv2026.08.25.1analytics_tag.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
tag?	string	no	The tag or tag prefix.
description?	string	no	The updated tag description.
pagination?	object	no
include_subaccounts?	boolean	no	Boolean indicating whether or not to include data from all subaccounts. Default false.
include_metrics?	boolean	no	Boolean indicating whether or not to include metrics for tags. Default false. When true max limit is 20.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a analytics tag

fn update()

Update analytics tag attributes

fn delete()

Delete the analytics tag

fn get_limits()

Get account tag limit information

Resources

state(infinite)— Analytics tag resource state

analytics_tag_action(ephemeral)— Analytics tag action result

@keeb/mailgun/analytics-usage-metricv2026.08.25.1analytics_usage_metric.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
start?	string	no	A start date (default: 7 days before current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
end?	string	no	An end date (default: current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
resolution?	string	no	A resolution in the format of 'day' 'hour' 'month'. Default is day.
duration?	string	no	A duration in the format of '1d' '2h' '2m'. If duration is provided then it is calculated from the end date and overwrites the start date.
dimensions?	array	no	Attributes of the metric data such as 'subaccount'. See [dimensions](https://documentation.mailgun.com/docs/mailgun/user-manual/reporting/dimensions)
metrics?	array	no	Name of the metrics to receive the stats for such as 'processed_count'.
filter?	object	no	Filters to apply to the query.
include_subaccounts?	boolean	no	Include stats from all subaccounts.
include_aggregates?	boolean	no	Include top-level aggregate metrics.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a analytics usage metric

Resources

state(infinite)— Analytics usage metric resource state

@keeb/mailgun/api-keyv2026.08.25.3api_key.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
domain_name?	string	no	Web domain to associate with the key, for keys of 'domain' kind
kind?	enum	no	Type of API key ('domain', 'user', or 'web'). Defaults to 'user' if not provided. Note: web keys are not subject to IP allowlisting and have a default/maximum validity period of 1 day.
description?	string	no	Key description
expiration?	number	no	Key lifetime in seconds, must be greater than 0 if set
role	enum	yes	Key role ('admin', 'basic' [use in place of analyst], 'sending' [use with keys of domain kind], or 'developer')
user_id?	string	no	API Key user's string user ID; should be provided for all keys of 'web' kind
user_name?	string	no	API Key user's name
email?	string	no	API Key user's email address; should be provided for all keys of 'web' kind
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a api key

fn lookup(max_items?: number)

List every api key and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn delete(id: string)

Delete the api key

Argument	Type	Required	Description
id	string	yes	The id of the api key

fn create_public()

Regenerate Mailgun Public API key

Resources

state(infinite)— Api key resource state

api_key_action(ephemeral)— Api key action result

@keeb/mailgun/bouncev2026.08.25.3bounce.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a bounce

fn get(id: string)

Get a bounce

Argument	Type	Required	Description
id	string	yes	The address of the bounce

fn lookup(max_items?: number)

List every bounce and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn delete(id: string)

Delete the bounce

Argument	Type	Required	Description
id	string	yes	The address of the bounce

fn sync()

Sync bounce state from Mailgun

fn import(file: string)

Import list of bounces

Argument	Type	Required	Description
file	string	yes	CSV file

Resources

state(infinite)— Bounce resource state

bounce_action(ephemeral)— Bounce action result

@keeb/mailgun/bounce-classification-metricv2026.08.25.1bounce_classification_metric.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
start?	record	no	A start timestamp (default: 7 days before current time). Must be in RFC 2822 format: https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview#date-format
end?	record	no	An end timestamp (default: current time). Must be in RFC 2822 format: https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview#date-format
resolution?	record	no	Resolution of the metrics.
duration?	string	no	A duration in the format of '48h' '60m' '30s'. If duration is provided then it is calculated from the end date and overwrites the start date.
dimensions?	array	no	Dimensions.
metrics?	array	no	Metrics to return. See example.
filter?	object	no	Filters to apply to the query.
include_subaccounts?	boolean	no	Include stats from all subaccounts.
pagination?	object	no	Attributes used for pagination and sorting.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a bounce classification metric

Resources

state(infinite)— Bounce classification metric resource state

@keeb/mailgun/complaintv2026.08.25.3complaint.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a complaint

fn get(id: string)

Get a complaint

Argument	Type	Required	Description
id	string	yes	The address of the complaint

fn lookup(max_items?: number)

List every complaint and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn delete(id: string)

Delete the complaint

Argument	Type	Required	Description
id	string	yes	The address of the complaint

fn sync()

Sync complaint state from Mailgun

fn import(file: string)

Import complaint list

Argument	Type	Required	Description
file	string	yes	CSV file

Resources

state(infinite)— Complaint resource state

complaint_action(ephemeral)— Complaint action result

@keeb/mailgun/dkim-keyv2026.08.25.1dkim_key.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
signing_domain	string	yes	Signing domain to be used for the new domain key
selector	string	yes	Selector to be used for the new domain key
bits?	number	no	Key size, can be 1024 or 2048
pem?	string	no	Private key PEM file
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a dkim key

fn get()

Get a dkim key

fn delete()

Delete the dkim key

fn sync()

Sync dkim key state from Mailgun

Resources

state(infinite)— Dkim key resource state

@keeb/mailgun/dkim-rotationv2026.08.25.1dkim_rotation.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn rotate(name: string)

Rotate Automatic Sender Security DKIM key for a domain

Argument	Type	Required	Description
name	string	yes	Path parameter: name

fn update_rotation(name: string, rotation_enabled: boolean, rotation_interval?: string)

Update Automatic Sender Security DKIM key rotation for a domain

Argument	Type	Required	Description
name	string	yes	Path parameter: name
rotation_enabled	boolean	yes	If true, enables DKIM Auto-Rotation. If false, disables it
rotation_interval?	string	no	The interval at which to rotate keys. Example, '5d' for five days

Resources

state(infinite)— Dkim rotation resource state

dkim_rotation_action(ephemeral)— Dkim rotation action result

@keeb/mailgun/domainv2026.08.25.3domain.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
archive_to?	string	no	If set to a URL, then each successfully delivered message will be submitted in an HTTP POST request to the URL. The Content-Type of the POST requests is application/mime and the request body is exactly what the recipient SMTP server received.
mailfrom_host?	string	no	The hostname to update to. Must be in lower case
message_ttl?	number	no	Specifies the time-to-live (TTL) in seconds for retrieving both incoming and outgoing messages. The maximum TTL value is determined by your subscription plan.
require_tls?	boolean	no	If set to true, this requires messages for the domain only be sent over a TLS connection. If a TLS connection cannot be established, Mailgun will not deliver the message. If set to false, Mailgun will still try and upgrade the connection, but if Mailgun cannot, the message will be delivered over a p
skip_verification?	boolean	no	If set to true, the certificate and hostname will not be verified when trying to establish a TLS connection and Mailgun will accept any certificate during delivery of a message. If set to false, Mailgun will verify the certificate and hostname. If either one can not be verified, a TLS connection wil
smtp_password?	string	no	Password for SMTP authentication
spam_action?	string	no	Disabled, block or tag. Default to disabled. If disabled, no spam filtering will occur for inbound messages. If block, inbound spam messages will not be delivered. If tag, inbound messages will be tagged with a spam header. See Spam Filter.
use_automatic_sender_security?	boolean	no	Enable Automatic Sender Security. This requires setting DNS CNAME entries for DKIM keys instead of a TXT record. Defaults to false.
webhooks_redact_pii?	boolean	no	If set to true, Personally Identifiable Information (PII) will be redacted from the payload of any webhook posted for this domain
web_scheme?	string	no	Sets your open, click and unsubscribe URLs to use http or https. Value either `http` or `https`. Defaults to http. In order for https to work, you must have a valid cert created for your domain. See Domain Tracking for TLS cert generation.
web_prefix?	string	no	Sets your open, click and unsubscribe URLs domain name prefix. Links rewritten or added by Mailgun in your emails will look like <web_scheme>://<web_prefix>.<domain_name>/... Default to email
wildcard?	boolean	no	Allows domain to accept inbound messages received on subdomains that have MX records pointed to Mailgun. Default is false.
dkim_host_name?	string	no	Set the DKIM host name for the domain that is being created. Note, the value must be a valid domain name, and can be the domain name being created or the root domain. This parameter cannot be used in conjunction with force_dkim_authority or force_root_dkim_host.
dkim_key_size?	string	no	The size of the new domain's DKIM key. Shall be either 1024 or 2048.
dkim_selector?	string	no	Explicitly set the value of the DKIM selector for the domain being created. If the domain key does not already exist, one will be created. The selector must be a valid atom per RFC2822. e.g valid value `foobar`, invalid value `foo.bar` https://datatracker.ietf.org/doc/html/rfc2822#section-3.2.4
encrypt_incoming_message?	boolean	no	Enable encrypting incoming messages for the given domain. This cannot be altered via API after being set for security purposes. Reach out to Support to disable if necessary. Default to false
force_dkim_authority?	boolean	no	If set to true, the domain will be the DKIM authority for itself even if the root domain is registered on the same mailgun account. If set to false, the domain will have the same DKIM authority as the root domain registered on the same mailgun account. Default to false.
force_root_dkim_host?	boolean	no	If set to true, the root domain will be the DKIM Host for the domain being created even if the root domain itself is not registered with Mailgun. The domain being created will still need to pass domain verification with valid spf records for the domain and valid DKIM record for the root domain. This
name	string	yes	The name of the new domain
pool_id?	string	no	Requested IP Pool to be assigned to the domain at creation.
ips?	string	no	An optional, comma-separated list of IP addresses to be assigned to this domain. If not specified, all dedicated IP addresses on the account will be assigned. If the request cannot be fulfilled (e.g. a requested IP is not assigned to the account, etc), a 400 will be returned.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a domain

fn get(id: string)

Get a domain

Argument	Type	Required	Description
id	string	yes	The name of the domain

fn lookup(max_items?: number)

List every domain and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update domain attributes

fn delete(id: string)

Delete the domain

Argument	Type	Required	Description
id	string	yes	The name of the domain

fn sync()

Sync domain state from Mailgun

fn all_dynamic_pools_enroll()

Enroll all account domains

fn create_dynamic_pools(name: string)

Enroll domain

Argument	Type	Required	Description
name	string	yes	Path parameter: name

fn create_webhooks(domain: string, id: enum, url: string)

Create a domain webhook

Argument	Type	Required	Description
domain	string	yes	Path parameter: domain
id	enum	yes	Webhook type to create.
url	string	yes	url(s) for webhooks to be sent to. Use multiple times to associate more than one url. Maximum of 3 urls for a given webhook type.

fn delete_dynamic_pools(name: string)

Remove domain from dynamic IP pools

Argument	Type	Required	Description
name	string	yes	Path parameter: name

fn delete_ips(name: string, ip: string)

Remove an IP from the domain pool, unlink a DIPP or remove the domain pool

Argument	Type	Required	Description
name	string	yes	Path parameter: name
ip	string	yes	Path parameter: ip

fn delete_pool(name: string, ip: string)

Remove an IP from the domain pool, unlink a DIPP or remove the domain pool

Argument	Type	Required	Description
name	string	yes	Path parameter: name
ip	string	yes	Path parameter: ip

fn delete_webhooks(domain: string)

Delete domain webhooks (v4)

Argument	Type	Required	Description
domain	string	yes	Path parameter: domain

fn get_dynamic_pools_assignable()

List assignable domains

fn get_sending_queues(name: string)

Get messages queue status

Argument	Type	Required	Description
name	string	yes	Path parameter: name

fn get_tracking(name: string)

Get tracking settings

Argument	Type	Required	Description
name	string	yes	Path parameter: name

fn get_webhooks(domain: string)

Get domain webhooks

Argument	Type	Required	Description
domain	string	yes	Path parameter: domain

fn keys_activate(domain: string, selector: string)

Activate a domain key

Argument	Type	Required	Description
domain	string	yes	Path parameter: domain
selector	string	yes	Path parameter: selector

fn keys_deactivate(domain: string, selector: string)

Deactivate a domain key

Argument	Type	Required	Description
domain	string	yes	Path parameter: domain
selector	string	yes	Path parameter: selector

fn list_keys(domain: string, max_items?: number)

List domain keys

Argument	Type	Required	Description
domain	string	yes	Path parameter: domain
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update_dkim_authority(name: string, self?: boolean)

Update DKIM authority

Argument	Type	Required	Description
name	string	yes	Path parameter: name
self?	boolean	no	Change the DKIM authority for a domain. If set to true, the domain will be the DKIM authority for itself even if the root domain is registered on the same mailgun account If set to false, the domain will have the same DKIM authority as the root domain registered on the same mailgun account.

fn update_dkim_selector(name: string, dkim_selector?: string)

Update a DKIM selector

Argument	Type	Required	Description
name	string	yes	Path parameter: name
dkim_selector?	string	no	Update the DKIM selector for a domain. If omitted no change is committed.

fn update_tracking_click(name: string, active?: string)

Update click tracking settings

Argument	Type	Required	Description
name	string	yes	Path parameter: name
active?	string	no	Set param to `htmlonly`, `true`, or `false`. Omit this param to make no change to the active status. Click tracking is consider as active if it's in the 'htmlonly' or 'true' state

fn update_tracking_open(name: string, active?: boolean, place_at_the_top?: boolean)

Update open tracking settings

Argument	Type	Required	Description
name	string	yes	Path parameter: name
active?	boolean	no	Set this param to true or false to toggle open tracking active status. Omit this param to keep current settings.
place_at_the_top?	boolean	no	Setting this param to true will place the open tracking pixel at the top of the HTML body when inserted into the email mime. Omit this param to keep current setting.

fn update_tracking_unsubscribe(name: string, active?: boolean, html_footer?: string, text_footer?: string)

Update unsubscribe tracking settings

Argument	Type	Required	Description
name	string	yes	Path parameter: name
active?	boolean	no	This param will toggle the active status of unsubscribe tracking on the domain.
html_footer?	string	no	Updates the html footer for the unsubscribe link inserted into the email html part of the mime.
text_footer?	string	no	Updates the text footer for the unsubscribe link inserted into the email plain part of the mime.

fn update_webhooks(domain: string, url: string, event_types: enum)

Update domain webhooks (v4)

Argument	Type	Required	Description
domain	string	yes	Path parameter: domain
url	string	yes	The webhook URL to update
event_types	enum	yes	Event types to associate with this URL. Use multiple times to specify multiple event types. This replaces the existing associations.

fn verify(name: string)

Verify Domain

Argument	Type	Required	Description
name	string	yes	Path parameter: name

Resources

state(infinite)— Domain resource state

domain_action(ephemeral)— Domain action result

@keeb/mailgun/domain-credentialv2026.08.25.3domain_credential.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
password?	string	no	Supply desired password(s) for the new credentials if preferred over generated ones; accepts multiple values
login	string	yes	Email address of SMTP credential user; accepts multiple values
mailbox?	string	no	Email address of SMTP credential user, may be used in place of 'login'; accepts multiple values
system?	boolean	no	Identify if these are system account credentials, defaults to false
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a domain credential

fn lookup(max_items?: number)

List every domain credential and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update domain credential attributes

fn delete(id: string)

Delete the domain credential

Argument	Type	Required	Description
id	string	yes	The login of the domain credential

Resources

state(infinite)— Domain credential resource state

@keeb/mailgun/domain-ip-assignmentv2026.08.25.1domain_ip_assignment.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
extra_dedicated_ips	object	yes	the DIPP spillover settings for the account
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn get(id: string)

Get a domain ip assignment

Argument	Type	Required	Description
id	string	yes	The name of the domain ip assignment

fn update()

Update domain ip assignment attributes

fn sync()

Sync domain ip assignment state from Mailgun

Resources

state(infinite)— Domain ip assignment resource state

@keeb/mailgun/domain-templatev2026.08.25.3domain_template.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
description?	string	no	Description of the template being stored
name	string	yes	Name of the template being stored. Supports utf-8 characters and name will be down cased.
createdBy?	string	no	Optional metadata field api user can indicate who created the template.
template?	string	no	Content of the template.
tag?	string	no	Initial tag of the created version. If the template parameter is provided and the tag is missing, the default value `initial` is used.
comment?	string	no	Version comment. This is valid only if a new version is being created. (template parameter is provided.)
headers?	string	no	Key value JSON object of headers to be stored with the template. Where key is the header name and value is the header value. The header names `From`, `Subject`, and `Reply-To` are the only ones currently supported. These headers will be inserted into the MIME at the time we attempt delivery. Headers
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a domain template

fn get(id: string)

Get a domain template

Argument	Type	Required	Description
id	string	yes	The name of the domain template

fn lookup(max_items?: number)

List every domain template and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update domain template attributes

fn delete(id: string)

Delete the domain template

Argument	Type	Required	Description
id	string	yes	The name of the domain template

fn sync()

Sync domain template state from Mailgun

fn copy(template_name: string, requests: array, source_versions?: array)

Copy a template

Argument	Type	Required	Description
template_name	string	yes	Path parameter: template_name
requests	array	yes	List of copy requests
source_versions?	array	no	Versions to copy or all versions if empty.

fn rename(template_name: string, new_template_name: string)

Rename a template

Argument	Type	Required	Description
template_name	string	yes	Path parameter: template_name
new_template_name	string	yes	Path parameter: new_template_name

Resources

state(infinite)— Domain template resource state

domain_template_action(ephemeral)— Domain template action result

@keeb/mailgun/domain-template-versionv2026.08.25.3domain_template_version.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
template_name	string	yes	Path scope for the domain template version: template_name
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
template	string	yes	Content of the template.
comment?	string	no	Comment related to the version that is being created.
active?	string	no	If this flag is set to yes, this version becomes active
headers?	string	no	Key value JSON object of headers to be stored with the template. Where key is the header name and value is the header value. The header names `From`, `Subject`, and `Reply-To` are the only ones currently supported. These headers will be inserted into the MIME at the time we attempt delivery. Headers
tag	string	yes	Tag of the version that is being created. Must be unique to the template.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a domain template version

fn get(id: string)

Get a domain template version

Argument	Type	Required	Description
id	string	yes	The name of the domain template version

fn lookup(max_items?: number)

List every domain template version and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update domain template version attributes

fn delete(id: string)

Delete the domain template version

Argument	Type	Required	Description
id	string	yes	The name of the domain template version

fn sync()

Sync domain template version state from Mailgun

fn copy(version_name: string, new_version_name: string)

Copy a version

Argument	Type	Required	Description
version_name	string	yes	Path parameter: version_name
new_version_name	string	yes	Path parameter: new_version_name

Resources

state(infinite)— Domain template version resource state

domain_template_version_action(ephemeral)— Domain template version action result

@keeb/mailgun/domain-webhookv2026.08.25.1domain_webhook.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
url	string	yes	New url(s) to associate to webhook. Use multiple times to associate more than one url. Maximum of 3 urls for a given type.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn get(id: string)

Get a domain webhook

Argument	Type	Required	Description
id	string	yes	The name of the domain webhook

fn update()

Update domain webhook attributes

fn delete(id: string)

Delete the domain webhook

Argument	Type	Required	Description
id	string	yes	The name of the domain webhook

fn sync()

Sync domain webhook state from Mailgun

Resources

state(infinite)— Domain webhook resource state

@keeb/mailgun/dynamic-ip-poolv2026.08.25.3dynamic_ip_pool.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
add_ip	string	yes	IP(s) to add to the pool
remove_ip	string	yes	IP(s) to remove from the pool
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn lookup(max_items?: number)

List every dynamic ip pool and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update dynamic ip pool attributes

fn add_ip(pool_name: string, ip: string)

Add IP to Dynamic IP Pool

Argument	Type	Required	Description
pool_name	string	yes	Path parameter: pool_name
ip	string	yes	Path parameter: ip

fn create_all(good_reputation: string, poor_reputation: string, new_senders: string)

Initialize/set IPs for all pools

Argument	Type	Required	Description
good_reputation	string	yes	IP(s) to include in the good_reputation pool
poor_reputation	string	yes	IP(s) to include in the poor_reputation pool
new_senders	string	yes	IP(s) to include in the new_senders pool

fn delete_all()

Remove all dynamic IP pools

fn delete_domains_override(name: string)

Remove override

Argument	Type	Required	Description
name	string	yes	Path parameter: name

fn domains_override(name: string)

Override domain assignment

Argument	Type	Required	Description
name	string	yes	Path parameter: name

fn get_domains_history(name: string)

List domain history

Argument	Type	Required	Description
name	string	yes	Path parameter: name

fn get_domains_preview(name: string)

Preview domain assignment

Argument	Type	Required	Description
name	string	yes	Path parameter: name

fn list_domains(max_items?: number)

List all domains assigned to dynamic IP pools

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn list_history(max_items?: number)

List account history

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

Resources

state(infinite)— Dynamic ip pool resource state

dynamic_ip_pool_action(ephemeral)— Dynamic ip pool action result

@keeb/mailgun/envelopev2026.08.25.1envelope.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn delete()

Delete the envelope

Resources

state(infinite)— Envelope resource state

@keeb/mailgun/eventv2026.08.25.3event.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn lookup(recipient?: string, event?: string, begin?: string, end?: string, ascending?: enum, subject?: string, message_id?: string, tags?: string, severity?: enum, max_items?: number)

Search the event stream and record each event as a data artifact (newest first, capped at 300 by default)

Argument	Type	Required	Description
recipient?	string	no	Only events for this recipient address, e.g. fan@example.com.
event?	string	no	Event type filter. A single type (`delivered`, `failed`, `opened`, `complained`, `unsubscribed`, `rejected`, `accepted`, `stored`) or a filter expression such as `failed OR rejected`.
begin?	string	no	Lower time bound, RFC 2822 (`Fri, 3 May 2013 09:00:00 -0000`) or a Unix timestamp. Mailgun walks backwards from `end` unless `ascending=yes`.
end?	string	no	Upper time bound, RFC 2822 or a Unix timestamp.
ascending?	enum	no	Walk the window oldest-first (`yes`) instead of newest-first.
subject?	string	no	Only events whose message had this subject.
message_id?	string	no	Only events for this message id, for tracing a single send end to end.
tags?	string	no	Only events carrying this tag.
severity?	enum	no	For failure events, whether the failure was a soft or hard bounce.
max_items?	number	no	Stop after this many events (default 300). Raise deliberately: the event stream is effectively unbounded on a busy domain.

fn get()

Fetch a single unfiltered, unpaginated page of the event stream. Prefer 'lookup', which filters by recipient and pages properly.

fn sync()

Sync event state from Mailgun

Resources

state(infinite)— Event resource state

@keeb/mailgun/forwardv2026.08.25.3forward.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a forward

fn get(id: string)

Get a forward

Argument	Type	Required	Description
id	string	yes	The id of the forward

fn lookup(max_items?: number)

List every forward and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update forward attributes

fn delete(id: string)

Delete the forward

Argument	Type	Required	Description
id	string	yes	The id of the forward

fn sync()

Sync forward state from Mailgun

Resources

state(infinite)— Forward resource state

@keeb/mailgun/ipv2026.08.25.3ip.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn get(id: string)

Get a ip

Argument	Type	Required	Description
id	string	yes	The ip of the ip

fn lookup(max_items?: number)

List every ip and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn sync()

Sync ip state from Mailgun

fn create_domains(ip: string)

Assign an IP to all account domains

Argument	Type	Required	Description
ip	string	yes	Path parameter: ip

fn create_ip_band(addr: string, ip_band: string)

Place account IP into a dedicated IP band

Argument	Type	Required	Description
addr	string	yes	Path parameter: addr
ip_band	string	yes	Dedicated IP band to place the IP address into

fn create_request_new()

Add a new dedicated IP to the account

fn delete_domains(ip: string)

Remove an IP from all account domains

Argument	Type	Required	Description
ip	string	yes	Path parameter: ip

fn get_account_settings()

Get DIPP spillover settings for an account

fn get_request_new()

Return the number of IPs available to the account per its billing plan

fn list_details_all(max_items?: number)

List account IPs - detailed view

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn list_domains(ip: string, max_items?: number)

Get all domains of an account where a specific IP is assigned

Argument	Type	Required	Description
ip	string	yes	Path parameter: ip
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update_account_settings(extra_dedicated_ips: object)

Set or Modify the dedicated IP pool used for IP spillover

Argument	Type	Required	Description
extra_dedicated_ips	object	yes	the DIPP spillover settings for the account. This value will apply to all domains under the account

fn update_subaccounts()

Update subaccount IP assignments

Resources

state(infinite)— Ip resource state

ip_action(ephemeral)— Ip action result

@keeb/mailgun/ip-poolv2026.08.25.3ip_pool.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
add_ip?	string	no	The IP to add to the DIPP (may be specified multiple times)
description	string	yes	Description of the DIPP
link_domain?	string	no	The ID of the domain link to the DIPP (may be specified multiple times)
name	string	yes	Short name of the DIPP
remove_ip?	string	no	The IP to remove from the DIPP (may be specified multiple times)
unlink_domain?	string	no	The ID of the domain to unlink from the DIPP (may be specified multiple times)
ip?	string	no	IP address to add to the DIPP (may be specified multiple times)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a ip pool

fn get(id: string)

Get a ip pool

Argument	Type	Required	Description
id	string	yes	The pool_id of the ip pool

fn lookup(max_items?: number)

List every ip pool and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update ip pool attributes

fn delete(id: string)

Delete the ip pool

Argument	Type	Required	Description
id	string	yes	The pool_id of the ip pool

fn sync()

Sync ip pool state from Mailgun

fn delegate(pool_id: string, subaccount_id: string)

Delegate DIPP to Subaccount

Argument	Type	Required	Description
pool_id	string	yes	Path parameter: pool_id
subaccount_id	string	yes	The ID of the subaccount to delegate the pool to

fn delete_delegate(pool_id: string, subaccount_id: string)

Revoke DIPP from Subaccount

Argument	Type	Required	Description
pool_id	string	yes	Path parameter: pool_id
subaccount_id	string	yes	The ID of the subaccount to revoke the pool from

fn delete_ips(pool_id: string, ip: string)

Remove an IP from a DIPP

Argument	Type	Required	Description
pool_id	string	yes	Path parameter: pool_id
ip	string	yes	Path parameter: ip

fn get_domains(pool_id: string)

Get domains linked to DIPP

Argument	Type	Required	Description
pool_id	string	yes	Path parameter: pool_id

fn replace_ips(pool_id: string, ips: array)

Add multiple IPs to the DIPP

Argument	Type	Required	Description
pool_id	string	yes	Path parameter: pool_id
ips	array	yes	IPs to add to the DIPP

fn update_ips(pool_id: string, ip: string)

Add an IP to a DIPP

Argument	Type	Required	Description
pool_id	string	yes	Path parameter: pool_id
ip	string	yes	Path parameter: ip

Resources

state(infinite)— Ip pool resource state

ip_pool_action(ephemeral)— Ip pool action result

@keeb/mailgun/ip-warmupv2026.08.25.3ip_warmup.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a ip warmup

fn get(id: string)

Get a ip warmup

Argument	Type	Required	Description
id	string	yes	The ip of the ip warmup

fn lookup(max_items?: number)

List every ip warmup and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn delete(id: string)

Delete the ip warmup

Argument	Type	Required	Description
id	string	yes	The ip of the ip warmup

fn sync()

Sync ip warmup state from Mailgun

Resources

state(infinite)— Ip warmup resource state

@keeb/mailgun/ip-whitelistv2026.08.25.1ip_whitelist.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
address	string	yes	Address to be added to the allowlist
description?	string	no	Description of the address to be added to the allowlist, defaults to empty string
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a ip whitelist

fn get()

Get a ip whitelist

fn update()

Update ip whitelist attributes

fn delete()

Delete the ip whitelist

fn sync()

Sync ip whitelist state from Mailgun

Resources

state(infinite)— Ip whitelist resource state

@keeb/mailgun/mailing-listv2026.08.25.3mailing_list.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
address	string	yes	A valid email address for the mailing list, e.g. developers@mailgun.net, or Developers <devs@mg.net>
description?	string	no	A description
name?	string	no	Mailing list name, e.g. Developers
access_level?	string	no	List access level, one of: readonly, members, everyone. Defaults to readonly
reply_reference?	string	no	Set where replies should go. Can be list or sender. Defaults to list.
reply_preference?	string	no	Set where replies should go: list or sender. Defaults to list
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a mailing list

fn get(id: string)

Get a mailing list

Argument	Type	Required	Description
id	string	yes	The address of the mailing list

fn lookup(max_items?: number)

List every mailing list and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update mailing list attributes

fn delete(id: string)

Delete the mailing list

Argument	Type	Required	Description
id	string	yes	The address of the mailing list

fn sync()

Sync mailing list state from Mailgun

fn list_pages(max_items?: number)

Get mailing lists by page

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

Resources

state(infinite)— Mailing list resource state

mailing_list_action(ephemeral)— Mailing list action result

@keeb/mailgun/mailing-list-memberv2026.08.25.3mailing_list_member.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
list_address	string	yes	Path scope for the mailing list member: list_address
address?	string	no	Valid email address specification.
name?	string	no	An optional member name.
vars?	record	no	JSON-encoded dictionary string with arbitrary parameters.
subscribed?	boolean	no	Set the member as subscribed or not. Defaults to true.
upsert?	boolean	no	Set to True to update member if present, False to raise error in case of a duplicate member. Defaults to false.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a mailing list member

fn get(id: string)

Get a mailing list member

Argument	Type	Required	Description
id	string	yes	The address of the mailing list member

fn lookup(max_items?: number)

List every mailing list member and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update mailing list member attributes

fn delete(id: string)

Delete the mailing list member

Argument	Type	Required	Description
id	string	yes	The address of the mailing list member

fn sync()

Sync mailing list member state from Mailgun

fn import_csv(subscribed?: boolean, upsert?: boolean, members?: string)

Bulk upload members to a mailing list (CSV)

Argument	Type	Required	Description
subscribed?	boolean	no
upsert?	boolean	no
members?	string	no	Absolute path to the CSV file

fn import_json()

Bulk upload members to a mailing list (JSON)

fn list_pages(max_items?: number)

Get members by page

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

Resources

state(infinite)— Mailing list member resource state

mailing_list_member_action(ephemeral)— Mailing list member action result

@keeb/mailgun/routev2026.08.25.3route.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
id?	string	no	Unique identifier of the route
priority?	number	no	Smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0.
description?	string	no	An arbitrary string.
expression	string	yes	The filtering rule.
action?	array	no	This action is executed when the expression evaluates to True. You can pass multiple parameters.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a route

fn get(id: string)

Get a route

Argument	Type	Required	Description
id	string	yes	The id of the route

fn lookup(max_items?: number)

List every route and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update route attributes

fn delete(id: string)

Delete the route

Argument	Type	Required	Description
id	string	yes	The id of the route

fn sync()

Sync route state from Mailgun

fn get_match()

Match address to route

Resources

state(infinite)— Route resource state

route_action(ephemeral)— Route action result

@keeb/mailgun/sandbox-recipientv2026.08.25.3sandbox_recipient.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a sandbox recipient

fn lookup(max_items?: number)

List every sandbox recipient and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn delete(id: string)

Delete the sandbox recipient

Argument	Type	Required	Description
id	string	yes	The address of the sandbox recipient

Resources

state(infinite)— Sandbox recipient resource state

@keeb/mailgun/send-alertv2026.08.25.3send_alert.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	A user-friendly name for the alert.
metric	string	yes	The metric being monitored.
comparator	string	yes	The comparison operator.
limit	string	yes	The threshold limit for the alert.
dimension	string	yes	The dimension to apply to the metric.
alert_channels?	array	no	A list of alert channels to notify.
filters?	array	no	A list of filters to apply to the alert.
period?	string	no	The time period for the metric aggregation in the format of '1h' '1d'.
description?	string	no	A description of what the alert does.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a send alert

fn get(id: string)

Get a send alert

Argument	Type	Required	Description
id	string	yes	The name of the send alert

fn lookup(max_items?: number)

List every send alert and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update send alert attributes

fn delete(id: string)

Delete the send alert

Argument	Type	Required	Description
id	string	yes	The name of the send alert

fn sync()

Sync send alert state from Mailgun

Resources

state(infinite)— Send alert resource state

@keeb/mailgun/sending-limitv2026.08.25.3sending_limit.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	A user-friendly name for the limit.
metric	string	yes	The metric being monitored.
comparator	string	yes	The comparison operator.
limit	string	yes	The threshold limit.
dimension	string	yes	The dimension to apply to the metric.
filters?	array	no	A list of filters to apply to the limit.
period?	string	no	The time period for the metric aggregation in the format of '1h' '1d'.
description?	string	no	A description of what the limit does.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a sending limit

fn get(id: string)

Get a sending limit

Argument	Type	Required	Description
id	string	yes	The name of the sending limit

fn lookup(max_items?: number)

List every sending limit and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update()

Update sending limit attributes

fn delete(id: string)

Delete the sending limit

Argument	Type	Required	Description
id	string	yes	The name of the sending limit

fn sync()

Sync sending limit state from Mailgun

Resources

state(infinite)— Sending limit resource state

@keeb/mailgun/slack-channelv2026.08.25.3slack_channel.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn get(id: string)

Get a slack channel

Argument	Type	Required	Description
id	string	yes	The id of the slack channel

fn lookup(max_items?: number)

List every slack channel and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn sync()

Sync slack channel state from Mailgun

Resources

state(infinite)— Slack channel resource state

@keeb/mailgun/stored-messagev2026.08.25.1stored_message.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
to	string	yes	Email address of the recipient(s). Supports friendly name format. Example: `"Bob <bob@host.com>"`. Use commas to separate multiple recipients. Duplicate addresses are automatically ignored.
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a stored message

fn get(id: string)

Get a stored message

Argument	Type	Required	Description
id	string	yes	The storage_key of the stored message

fn sync()

Sync stored message state from Mailgun

Resources

state(infinite)— Stored message resource state

@keeb/mailgun/subaccountv2026.08.25.3subaccount.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a subaccount

fn get(id: string)

Get a subaccount

Argument	Type	Required	Description
id	string	yes	The id of the subaccount

fn lookup(max_items?: number)

List every subaccount and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn delete()

Delete the subaccount

fn sync()

Sync subaccount state from Mailgun

fn delete_limit_custom_monthly(subaccount_id: string)

Delete a custom sending limit

Argument	Type	Required	Description
subaccount_id	string	yes	Path parameter: subaccount_id

fn disable(subaccount_id: string)

Disable a subaccount

Argument	Type	Required	Description
subaccount_id	string	yes	Path parameter: subaccount_id

fn enable(subaccount_id: string)

Enable a subaccount

Argument	Type	Required	Description
subaccount_id	string	yes	Path parameter: subaccount_id

fn get_limit_custom_monthly(subaccount_id: string)

Get current custom sending limit

Argument	Type	Required	Description
subaccount_id	string	yes	Path parameter: subaccount_id

fn list_ip_pools_all(max_items?: number)

List DIPPs delegated to subaccounts

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn update_features(subaccount_id: string, email_preview?: string, inbox_placement?: string, sending?: string, validations?: string, validations_bulk?: string)

Update subaccount feature

Argument	Type	Required	Description
subaccount_id	string	yes	Path parameter: subaccount_id
email_preview?	string	no	JSON object encoded as a string
inbox_placement?	string	no	JSON object encoded as a string
sending?	string	no	JSON object encoded as a string
validations?	string	no	JSON object encoded as a string
validations_bulk?	string	no	JSON object encoded as a string

fn update_limit_custom_monthly(subaccount_id: string)

Set a custom sending limit

Argument	Type	Required	Description
subaccount_id	string	yes	Path parameter: subaccount_id

Resources

state(infinite)— Subaccount resource state

subaccount_action(ephemeral)— Subaccount action result

@keeb/mailgun/thresholdv2026.08.25.3threshold.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn list_hits(max_items?: number)

List account hits

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

Resources

state(infinite)— Threshold resource state

threshold_action(ephemeral)— Threshold action result

@keeb/mailgun/tracking-certificatev2026.08.25.1tracking_certificate.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a tracking certificate

fn update()

Update tracking certificate attributes

fn get_status(domain: string)

Tracking Certificate: Get certificate and status

Argument	Type	Required	Description
domain	string	yes	Path parameter: domain

Resources

state(infinite)— Tracking certificate resource state

tracking_certificate_action(ephemeral)— Tracking certificate action result

@keeb/mailgun/unsubscribev2026.08.25.3unsubscribe.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
domain	string	yes	The Mailgun domain this resource belongs to
name	string	yes	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn create()

Create a unsubscribe

fn get(id: string)

Get a unsubscribe

Argument	Type	Required	Description
id	string	yes	The address of the unsubscribe

fn lookup(max_items?: number)

List every unsubscribe and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn delete(id: string)

Delete the unsubscribe

Argument	Type	Required	Description
id	string	yes	The address of the unsubscribe

fn sync()

Sync unsubscribe state from Mailgun

fn import(file: string)

Import unsubscribe list

Argument	Type	Required	Description
file	string	yes	CSV file

Resources

state(infinite)— Unsubscribe resource state

unsubscribe_action(ephemeral)— Unsubscribe action result

@keeb/mailgun/userv2026.08.25.3user.ts

Global Arguments

Argument	Type	Required	Description
region	enum	yes	Mailgun region the account belongs to. A key from the other region is rejected with 401.
name?	string	no	Instance name for this resource (used as the unique identifier in the factory pattern)
api_key?	string	no	Mailgun API key; overrides the MAILGUN_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.

fn get(id: string)

Get a user

Argument	Type	Required	Description
id	string	yes	The id of the user

fn lookup(max_items?: number)

List every user and record each as a data artifact (capped at 1000 by default)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 1000). Raise deliberately: every 100 results costs another request against Mailgun's rate limit.

fn sync()

Sync user state from Mailgun

fn get_me()

Get one's own user details

Resources

state(infinite)— User resource state

user_action(ephemeral)— User action result

04Previous Versions3

2026.08.25.3Aug 26, 2026

2026.08.25.3

Changed: truncation is no longer silent. Every walk that stops short logs a warning and records it — lookup writes a _walk artifact, list_* methods carry truncated/truncationReason/maxItems in their result — so a partial list can't be presented as a complete one.
Added: max_items on the list_* methods, which previously walked uncapped. Every paginated method now has the same ceiling and the same default of 1000.
Fixed: a 404 on the first page of a walk now raises an error naming the domain global argument instead of returning an empty list. A mistyped domain was indistinguishable from a domain with no records.
Docs: README covers how to size max_items, when to filter instead of raising it, and how to detect a truncated answer.

2026.08.25.2

Added: lookup on event, exposing the upstream query parameters (recipient, event, begin, end, ascending, subject, message_id, tags, severity). Searching the event stream for one address no longer means pulling the stream and filtering client-side.
Added: max_items on every lookup method, defaulting to 1000 (300 on event). Paginated walks were previously bounded only by the 10,000-record page cap.
Fixed: README examples used a --arg flag that does not exist; method arguments are passed with --input, and object values need :json=.

2026.08.25.2Aug 26, 2026

Added: lookup on event, exposing the upstream query parameters (recipient, event, begin, end, ascending, subject, message_id, tags, severity). Searching the event stream for one address no longer means pulling the stream and filtering client-side.
Added: max_items on every lookup method, defaulting to 1000 (300 on event). Paginated walks were previously bounded only by the 10,000-record page cap.
Fixed: README examples used a --arg flag that does not exist; method arguments are passed with --input, and object values need :json=.

Modified 1 models

2026.08.25.1Aug 25, 2026

Added: account_template_version, account_template, account_webhook, account, alert_event, alert, allowlist, analytics_log, analytics_metric, analytics_tag, analytics_usage_metric, api_key, bounce_classification_metric, bounce, complaint, dkim_key, dkim_rotation, domain_credential, domain_ip_assignment, domain_template_version, domain_template, domain_webhook, domain, dynamic_ip_pool, envelope, event, forward, ip_pool, ip_warmup, ip_whitelist, ip, mailing_list_member, mailing_list, message, route, sandbox_recipient, send_alert, sending_limit, slack_channel, stored_message, subaccount, threshold, tracking_certificate, unsubscribe, user

05Stats

85 / 100

Downloads

Archive size

160.7 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository0/2missing

06Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

07Labels

#mailgun #email #saas #messaging