Mailgun Readonly

@keeb/mailgun-readonlyv2026.08.26.1· 16d agoMODELS

01README

Read-only Mailgun models — GET requests only, no write capability

02Release Notes

Initial release. A read-only sibling of @keeb/mailgun: same models, GET requests only.

The client issues GET and nothing else. A non-GET verb throws before the API key is resolved, so key scope grants no write capability. There is no allowlist and no exceptions.
There is no request-body encoder and no body parameter, so the client has no way to carry a payload.
Every create, update, and delete method is absent, as is every mutating verb endpoint (verify, enable/disable, import, rotate, send). 37 models, all read: get, lookup, sync, get_*, list_*.
Models that existed only to write are absent entirely: message, envelope, alert_event, dkim_rotation. So are the analytics models (analytics_log, analytics_metric, analytics_usage_metric, bounce_classification_metric), whose search endpoints require POST.
Walks are capped: max_items on every lookup and list_* method (default 1000, 300 on event), and truncation is reported rather than silent.

03Models37

@keeb/mailgun-readonly/accountv2026.08.26.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 get_http_signing_key()

Get webhook signing key saved on the account

fn get_limit_custom_monthly()

Get current custom sending limit

Resources

account_action(ephemeral)— Account action result

@keeb/mailgun-readonly/account-templatev2026.08.26.1account_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 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 sync()

Sync account template state from Mailgun

Resources

state(infinite)— Account template resource state

@keeb/mailgun-readonly/account-template-versionv2026.08.26.1account_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 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 sync()

Sync account template version state from Mailgun

Resources

state(infinite)— Account template version resource state

@keeb/mailgun-readonly/account-webhookv2026.08.26.1account_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 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 sync()

Sync account webhook state from Mailgun

Resources

state(infinite)— Account webhook resource state

@keeb/mailgun-readonly/alertv2026.08.26.1alert.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_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.

Resources

alert_action(ephemeral)— Alert action result

@keeb/mailgun-readonly/allowlistv2026.08.26.1allowlist.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 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 sync()

Sync allowlist state from Mailgun

Resources

state(infinite)— Allowlist resource state

@keeb/mailgun-readonly/analytics-tagv2026.08.26.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 get_limits()

Get account tag limit information

Resources

analytics_tag_action(ephemeral)— Analytics tag action result

@keeb/mailgun-readonly/api-keyv2026.08.26.1api_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 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.

Resources

state(infinite)— Api key resource state

@keeb/mailgun-readonly/bouncev2026.08.26.1bounce.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 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 sync()

Sync bounce state from Mailgun

Resources

state(infinite)— Bounce resource state

@keeb/mailgun-readonly/complaintv2026.08.26.1complaint.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 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 sync()

Sync complaint state from Mailgun

Resources

state(infinite)— Complaint resource state

@keeb/mailgun-readonly/dkim-keyv2026.08.26.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 get()

Get a dkim key

fn sync()

Sync dkim key state from Mailgun

Resources

state(infinite)— Dkim key resource state

@keeb/mailgun-readonly/domainv2026.08.26.1domain.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 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 sync()

Sync domain state from Mailgun

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 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.

Resources

state(infinite)— Domain resource state

domain_action(ephemeral)— Domain action result

@keeb/mailgun-readonly/domain-credentialv2026.08.26.1domain_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 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.

Resources

state(infinite)— Domain credential resource state

@keeb/mailgun-readonly/domain-ip-assignmentv2026.08.26.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 sync()

Sync domain ip assignment state from Mailgun

Resources

state(infinite)— Domain ip assignment resource state

@keeb/mailgun-readonly/domain-templatev2026.08.26.1domain_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 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 sync()

Sync domain template state from Mailgun

Resources

state(infinite)— Domain template resource state

@keeb/mailgun-readonly/domain-template-versionv2026.08.26.1domain_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 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 sync()

Sync domain template version state from Mailgun

Resources

state(infinite)— Domain template version resource state

@keeb/mailgun-readonly/domain-webhookv2026.08.26.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 sync()

Sync domain webhook state from Mailgun

Resources

state(infinite)— Domain webhook resource state

@keeb/mailgun-readonly/dynamic-ip-poolv2026.08.26.1dynamic_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 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-readonly/eventv2026.08.26.1event.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-readonly/forwardv2026.08.26.1forward.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 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 sync()

Sync forward state from Mailgun

Resources

state(infinite)— Forward resource state

@keeb/mailgun-readonly/ipv2026.08.26.1ip.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 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.

Resources

state(infinite)— Ip resource state

ip_action(ephemeral)— Ip action result

@keeb/mailgun-readonly/ip-poolv2026.08.26.1ip_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 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 sync()

Sync ip pool state from Mailgun

fn get_domains(pool_id: string)

Get domains linked to DIPP

Argument	Type	Required	Description
pool_id	string	yes	Path parameter: pool_id

Resources

state(infinite)— Ip pool resource state

ip_pool_action(ephemeral)— Ip pool action result

@keeb/mailgun-readonly/ip-warmupv2026.08.26.1ip_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 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 sync()

Sync ip warmup state from Mailgun

Resources

state(infinite)— Ip warmup resource state

@keeb/mailgun-readonly/ip-whitelistv2026.08.26.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 get()

Get a ip whitelist

fn sync()

Sync ip whitelist state from Mailgun

Resources

state(infinite)— Ip whitelist resource state

@keeb/mailgun-readonly/mailing-listv2026.08.26.1mailing_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 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 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-readonly/mailing-list-memberv2026.08.26.1mailing_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 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 sync()

Sync mailing list member state from Mailgun

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-readonly/routev2026.08.26.1route.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 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 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-readonly/sandbox-recipientv2026.08.26.1sandbox_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 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.

Resources

state(infinite)— Sandbox recipient resource state

@keeb/mailgun-readonly/send-alertv2026.08.26.1send_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 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 sync()

Sync send alert state from Mailgun

Resources

state(infinite)— Send alert resource state

@keeb/mailgun-readonly/sending-limitv2026.08.26.1sending_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 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 sync()

Sync sending limit state from Mailgun

Resources

state(infinite)— Sending limit resource state

@keeb/mailgun-readonly/slack-channelv2026.08.26.1slack_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-readonly/stored-messagev2026.08.26.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 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-readonly/subaccountv2026.08.26.1subaccount.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 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 sync()

Sync subaccount state from Mailgun

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.

Resources

state(infinite)— Subaccount resource state

subaccount_action(ephemeral)— Subaccount action result

@keeb/mailgun-readonly/thresholdv2026.08.26.1threshold.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

threshold_action(ephemeral)— Threshold action result

@keeb/mailgun-readonly/tracking-certificatev2026.08.26.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 get_status(domain: string)

Tracking Certificate: Get certificate and status

Argument	Type	Required	Description
domain	string	yes	Path parameter: domain

Resources

tracking_certificate_action(ephemeral)— Tracking certificate action result

@keeb/mailgun-readonly/unsubscribev2026.08.26.1unsubscribe.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 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 sync()

Sync unsubscribe state from Mailgun

Resources

state(infinite)— Unsubscribe resource state

@keeb/mailgun-readonly/userv2026.08.26.1user.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

04Stats

85 / 100

Downloads

Archive size

87.3 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

05Platforms

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

06Labels

#mailgun #email #saas #messaging #read-only