{ "openapi": "3.1.0", "info": { "title": "Mailgun API", "description": "Mailgun API defined by OpenAPI Specification (OAS) 3.1.0", "version": "3.0.0" }, "servers": [ { "url": "https://api.mailgun.net", "description": "US Mailgun" }, { "url": "https://api.eu.mailgun.net", "description": "EU Mailgun" } ], "tags": [ { "name": "Messages", "description": "Send email two ways via our REST API:\n1. Send emails using MIME format using a MIME building library\n2. Submit the individual parts (Text, html, attachments, etc.)\n\nReminder: You can also send email via SMTP with Mailgun. Please reference the user manual.", "x-displayName": "Messages" }, { "name": "Domain Tracking", "description": "Mailgun offers tracking for clicks, unsubscribes, and opens, with optional HTTPS protocol support on tracking URLs. To enable HTTPS, Mailgun uses Let’s Encrypt with HTTP-01 challenges through your existing tracking CNAME record to issue a TLS certificate. This setup also includes support for HTTP Strict Transport Security (HSTS) for enhanced security.", "x-displayName": "Domain Tracking" }, { "name": "Domain Keys", "description": "An authentication standard used to prevent email spoofing.", "x-displayName": "Domain Keys" }, { "name": "Domains", "description": "Domains API manages domains, domain keys and DNS verification.", "x-displayName": "Domains" }, { "name": "Account Webhooks", "description": "Webhooks API to manage account-specific webhooks. You can create, retrieve, update, and delete webhooks programmatically. Account-level webhooks are configured independently for US and EU regions. When triggered, webhook URLs are deduplicated by event type, across account and domain levels to prevent redundant webhook sends.", "x-displayName": "Account Webhooks" }, { "name": "Domain Webhooks", "description": "Webhooks API to manage domain-specific webhooks. You can create, retrieve, update, and delete webhooks programmatically. When triggered, webhook URLs are deduplicated by event type, across account and domain levels to prevent redundant webhook sends.", "x-displayName": "Domain Webhooks" }, { "name": "DKIM Security", "description": "Automatic Sender Security DKIM Key APIs. To enable this feature please see 'Update a domain' API docs.", "x-displayName": "DKIM Security" }, { "name": "IPs", "description": "The IP API endpoint allows you to access information regarding the IPs allocated to your Mailgun account that are used for outbound sending.", "x-displayName": "IPs" }, { "name": "IP Pools", "description": "IP Pools allow you to group your dedicated IPs into customized \"pools\" to help manage your sending reputation for different mail sending streams.", "x-displayName": "IP Pools" }, { "name": "Dynamic IP Pools", "description": "Dynamic IP Pools allow you to group your dedicated IPs into customized \"pools\" based on sender reputation. Domains enrolled in Dynamic IP Pools will be assigned to a pool based on the result of periodic health checks.", "x-displayName": "Dynamic IP Pools" }, { "name": "Delegated DIPPs", "x-displayName": "Delegated DIPPs" }, { "name": "openapi-tower_other", "x-displayName": "other" }, { "name": "IP Address Warmup", "x-displayName": "IP Address Warmup" }, { "name": "Events", "description": "Mailgun keeps track of every inbound and outbound message event and stores this data for at least 3 days.

WARNING: This API is deprecated in favor of our [Logs](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/logs) API. ", "x-displayName": "Events" }, { "name": "Tags", "description": "Mailgun lets you tag each outgoing message with a custom value. When you access stats on your messages, they will be aggregated by these tags.

WARNING: This API is deprecated in favor of our new [Tags](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/tags-new) API. ", "x-displayName": "Tags" }, { "name": "Stats", "description": "Mailgun collects many different events and generates event statistics which are available in your Control Panel. This data is also available via our stats API endpoint.

WARNING: This API is deprecated in favor of our [Metrics](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/metrics) API. ", "x-displayName": "Stats" }, { "name": "openapi-scout_other", "x-displayName": "other" }, { "name": "Metrics", "description": "The Mailgun Metrics API provides programmatic access to detailed analytics data about your email sending activity. This API allows you to query, filter, and analyze email performance metrics to gain insights into deliverability, engagement, and overall sending health.\n\n## Metrics vs. Stats API\n\nThe Metrics API is the modern replacement for the deprecated Stats API:\n\n| Feature | Stats API (Deprecated) | Metrics API (Current) |\n|---------|----------------------|---------------------|\n| Flexibility | Limited filtering | Advanced filtering with logical operators |\n| Dimensions | Fixed groupings | Flexible dimension combinations |\n| Metrics | Basic counts | Comprehensive metrics including rates |\n| Performance | Slower | Optimized for large datasets |\n| Future Support | None | Active development |\n\n**Migration:** If you're using the Stats API, plan to migrate to the Metrics API for continued support and new features.\n\n## What Are Metrics?\n\nMetrics are quantitative measurements of your email activity. The Mailgun platform collects event data in real-time and aggregates it into meaningful metrics that help you understand how your emails are performing.\n\n## Types of Metrics\n\nMailgun provides two categories of metrics:\n\n### Sending Metrics (via `/v1/analytics/metrics`)\n\nThese metrics track the lifecycle and performance of your outbound emails:\n\n- **Volume Metrics**: Messages accepted, delivered, failed, queued\n- **Engagement Metrics**: Opens, clicks, unsubscribes\n- **Deliverability Metrics**: Bounces (permanent and temporary), complaints (spam reports)\n- **Rate Metrics**: Delivered rate, open rate, click rate, bounce rate\n- **ESP-Specific Metrics**: Performance broken down by email service provider\n\nSee [metric definitions](https://documentation.mailgun.com/docs/mailgun/user-manual/reporting/metric-definitions) for a complete list of available metrics.\n\n### Usage Metrics (via `/v1/analytics/usage/metrics`)\n\nThese metrics track your consumption of Mailgun services and features:\n\n- **Email Validation**: Single validations, bulk validations, API calls\n- **Email Preview**: Preview generation counts and failures\n- **Blocklist Monitoring**: Domain and IP blocklist checks\n- **Accessibility Checks**: Accessibility validation counts\n- **Seed Testing**: Seed test campaigns sent\n\n## Core Concepts\n\n### Dimensions\n\nDimensions are the attributes by which you can slice and group your metrics data. Think of them as the \"categories\" or \"labels\" for your data.\n\n**Available Dimensions:**\n\nSee [dimensions](https://documentation.mailgun.com/docs/mailgun/user-manual/reporting/dimensions) for a complete list of available dimensions.\n\n**Example:** If you query with dimensions `[\"time\", \"domain\"]`, your results will be grouped by time period for each sending domain.\n\n### Resolution\n\nResolution determines the time granularity of your results:\n\n- **hour**: Data grouped by hour (useful for real-time monitoring)\n- **day**: Data grouped by day (most common for daily reports)\n- **month**: Data grouped by month (useful for trend analysis)\n\nThe resolution you choose affects how the `time` dimension groups your data.\n\n### Time Range Selection\n\nYou have flexible options for specifying the time range:\n\n**Option 1: Start and End Dates**\n```json\n{\n\"start\": \"Mon, 13 Nov 2023 00:00:00 -0600\",\n\"end\": \"Mon, 20 Nov 2023 23:59:59 -0600\"\n}\n```\n\n**Option 2: Duration**\n```json\n{\n\"duration\": \"7d\"\n}\n```\n\nThis calculates the start date and end date automatically (7 days before the today).\n\n**Date Format:** RFC 2822 format with timezone support\n\n### Filters\n\nFilters allow you to narrow down your data to specific criteria. The filter system uses a logical structure:\n\n```json\n{\n\"filter\": {\n \"AND\": [\n {\n \"attribute\": \"domain\",\n \"comparator\": \"=\",\n \"values\": [\n {\"value\": \"example.com\"}\n ]\n },\n {\n \"attribute\": \"tag\",\n \"comparator\": \"=\",\n \"values\": [\n {\"value\": \"newsletter\"}\n ]\n }\n ]\n}\n}\n```\n\n**Note:** Filters only support the \"AND\" operator. \"OR\" is not supported. In the example above, only data where the sending domain equals `example.com` and the tag equals `newsletter` will be returned.\n\n**Filter Components:**\n- **attribute**: The field to filter on (domain, tag, subaccount)\n- **comparator**: The comparison operator (=, !=, contains, not contains)\n- **values**: Array of values to match against\n\n### Aggregates\n\nWhen `include_aggregates` is set to `true`, the API returns top-level summary statistics across all your queried data. This gives you totals and averages without having to sum the individual items yourself.\n\n### Subaccounts\n\nIf you use Mailgun's subaccount feature, you can:\n- Query metrics for a specific subaccount using filters\n- Include all subaccounts' data with `include_subaccounts: true`\n- View aggregated data across all subaccounts\n\n## Data Retention\n\nMailgun retains metrics data for different durations based on resolution:\n- **Hourly**: 60 days\n- **Daily**: 1 year\n- **Monthly**: Indefinitely \n\n## Pagination\n\nFor queries that return large result sets, the API uses offset-based pagination with `skip` and `limit` request attributes.\n\n- `skip` specifies how many items to offset (skip) from the beginning of the result set.\n- `limit` specifies the maximum number of items to return in a single request.\n\nDefaults and limits:\n- Default page size varies by dimension. Default for time dimension is 1500 items. All other dimensions default to 10 items.\n- Maximum `limit` is 1500 for the time dimension and 1000 for all other dimensions.\n\nHow pagination works:\n- Start with `skip=0` and a desired `limit` (for example, `limit=1000`).\n- Retrieve the next page by increasing `skip` by the value of `limit`:\n- First page: `skip=0`, `limit=1000`\n- Second page: `skip=1000`, `limit=1000`\n- Third page: `skip=2000`, `limit=1000`\n- Continue paging until fewer items than the specified `limit` are returned.\n\nAdditional details:\n- The response includes a `pagination` object containing the total number of available items.\n- Results can be sorted using the `sort` parameter, for example `time:asc` or `time:desc`. \nFor consistent pagination, use a deterministic sort order.\n\n## Rate Limits and Quotas\n\n- API calls are subject to a rate limit of 500 requests every 10 seconds", "x-displayName": "Metrics" }, { "name": "Logs", "description": "Mailgun keeps track of every inbound and outbound message event and stores this log data. Using this logs API, this data can be queried and filtered to provide insights into the health of your email infrastructure.", "x-displayName": "Logs" }, { "name": "Tags New", "description": "Mailgun allows you to tag your email with unique identifiers. Tags are visible via our analytics tags API endpoint.", "x-displayName": "Tags New" }, { "name": "Send Alerts", "description": "Mailgun allows you to get instant notifications on the sending metrics that matter most, configured specifically for your unique business needs and assets. Route these alerts to the channels your team relies on. Stay on top of sending performance without the need to manually monitor.", "x-displayName": "Send Alerts" }, { "name": "Limits", "description": "Mailgun allows you to set limits on your subaccounts to help you manage usage and costs. You can create, update, retrieve, and delete limits for various pre-send features such as email previews and email validations.", "x-displayName": "Limits" }, { "name": "Alerts", "x-displayName": "Alerts" }, { "name": "Unsubscribe", "description": "Unsubscribe list stores email addresses of recipients who unsubscribed from your mailings by clicking a Mailgun generated unsubscribe link.", "x-displayName": "Unsubscribe" }, { "name": "Complaints", "description": "Email addresses of recipients who marked your messages as a spam (for ESPs that support FBL).", "x-displayName": "Complaints" }, { "name": "Bounces", "description": "Bounces - Bounce list stores events of delivery failures due to permanent recipient mailbox errors such as non-existent mailbox. Soft bounces (for example, mailbox is full) and other failures (for example, ESP rejects an email because it thinks it is spam) are not added to the list.", "x-displayName": "Bounces" }, { "name": "Allowlist", "description": "The allowlist API provides the ability to allowlist specific addresses from being added to bounce list. You can allowlist by domain name (i.e example.com) or by specific address (i.e. alice@example.com). Mailgun doesn’t add an address to bounce list if the address is allowlisted. This API is very useful if you test against your private services and don’t want to constantly clean up bounce lists", "x-displayName": "Allowlist" }, { "name": "Routes", "description": "Define a list of routes to handle incoming emails. When a message matches a route expression, Mailgun can forward it on to your application via HTTP or another email address, or store the message temporarily (3 days) for subsequent retrieval.", "x-displayName": "Routes" }, { "name": "Mailing Lists", "description": "Programatically create mailing lists.", "x-displayName": "Mailing Lists" }, { "name": "Account Templates", "description": "This API allows you to store predefined templates at the account level and use them to send messages using the Sending API.", "x-displayName": "Account Templates" }, { "name": "Domain Templates", "description": "This API allows you to store predefined templates at the domain level and use them to send messages using the Sending API.", "x-displayName": "Domain Templates" }, { "name": "Account Management", "description": "Perform account-level CRUD operations.", "x-displayName": "Account Management" }, { "name": "Custom Message Limit", "description": "The custom message limit imposes a hard limit on how many messages your account can send during a calendar month.", "x-displayName": "Custom Message Limit" }, { "name": "Subaccounts", "description": "Mailgun supports the creation, modification, and deletion of subaccounts. A subaccount is a child account of a parent account. The parent account can have multiple subaccounts. The subaccounts are created and managed by the parent account.", "x-displayName": "Subaccounts" }, { "name": "Credentials", "description": "The Credentials API lets you view and manage SMTP credentials.", "x-displayName": "Credentials" }, { "name": "IP Allowlist", "description": "The IP Allowlist API lets you view and manage allowlisted IP addresses to which API key and SMTP credential usage is restricted.", "x-displayName": "IP Allowlist" }, { "name": "Keys", "description": "The Keys API lets you view and manage API keys.", "x-displayName": "Keys" }, { "name": "Bounce Classification", "x-displayName": "Bounce Classification" }, { "name": "Users", "description": "Mailgun API supports viewing user entities.", "x-displayName": "Users" } ], "paths": { "/v3/{domain_name}/messages": { "post": { "tags": [ "Messages" ], "summary": "Send an email", "description": "Pass the components of the messages such as To, From, Subject, HTML, text parts, attachments, etc. Mailgun will build a MIME representation of the message and send it. In order to send you must provide one of the following parameters: 'text', 'html', 'amp-html' or 'template'. Important: Send options (parameters starting with o:, h:, v:, or t:) are limited to 16KB total", "operationId": "POST-v3--domain-name--messages", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name used to send the message", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domain_name-messages-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-SendMessageResponse" }, "examples": { "Example": { "value": { "id": "message-id", "message": "Queued. Thank you." } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-GetMessageResponseNotFound" }, "examples": { "Example": { "value": { "message": "A simple message describing the issue - A few examples:'to parameter is not a valid address. please check documentation.' 'Only one parameters 'html' or 'template' is allowed.' 'Need at least one of 'text', 'html', 'amp-html' or 'template' parameters specified.' 'from parameter is missing. ''Send options (parameters starting with o:, h:, or v:) are limited to 16KB total'" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": "Forbidden" } } } } }, "429": { "description": "A 429 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-GetMessageResponseNotFound" }, "examples": { "Example": { "value": { "message": "Domain example.com is not allowed to send: account-requests-per-sec limit exceeded, try again after 120 seconds" } } } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-GetMessageResponseNotFound" }, "examples": { "Example": { "value": { "message": "Internal Server Error" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/messages.mime": { "post": { "tags": [ "Messages" ], "summary": "Send an email in MIME format", "description": "Build a MIME string yourself using a MIME library and submit it to Mailgun. Important: Send options (parameters starting with o:, h:, v:, or t:) are limited to 16KB total", "operationId": "POST-v3--domain-name--messages-mime", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name used to send the message", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domain_name-messages-mime-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-SendMessageResponse" }, "examples": { "Example": { "value": { "id": "message-id", "message": "Queued. Thank you." } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-GetMessageResponseNotFound" }, "examples": { "Example": { "value": { "message": "A simple message describing the issue - A few examples:'to parameter is not a valid address. please check documentation.' 'Only one parameters 'html' or 'template' is allowed.' 'Need at least one of 'text', 'html', 'amp-html' or 'template' parameters specified.' 'from parameter is missing. ''Send options (parameters starting with o:, h:, or v:) are limited to 16KB total'" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": "Forbidden" } } } } }, "429": { "description": "A 429 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-GetMessageResponseNotFound" }, "examples": { "Example": { "value": { "message": "Domain example.com is not allowed to send: account-requests-per-sec limit exceeded, try again after 120 seconds" } } } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-GetMessageResponseNotFound" }, "examples": { "Example": { "value": { "message": "Internal Server Error" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{domain_name}/messages/{storage_key}": { "get": { "tags": [ "Messages" ], "summary": "Retrieve a stored email", "description": "Event(s) created from sending an email with Mailgun will contain a `storage.key` to use to retrieve the email.", "operationId": "GET-v3-domains--domain-name--messages--storage-key-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name that was used to send the email", "required": true, "schema": { "type": "string" } }, { "name": "storage_key", "in": "path", "description": "Storage key from the email's associated events (Example: Accepted/Delivered events `storage.key` field). Note: Storage keys are available for the duration of your domain's message retention policy.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-GetMessageResponseBasicExample" }, "examples": { "Example": { "value": { "Content-Transfer-Encoding": "7bit", "Content-Type": "multipart/form-data; boundary=----SomeFormBoundaryABC123", "From": "foo.bar@my-domain.com", "Message-Id": "", "Mime-Version": "1.0", "Subject": "\"Mailgun is awesome\"", "To": "Cool Bar , bar.baz@gmail.com", "X-Mailgun-Tag": "Earth", "sender": "foo.bar@my-domain.com", "recipients": "cool.barr@cool.com, bar.baz@gmail.com", "body-html": "This is some html", "body-plain": "This is some html", "stripped-html": "This is some html", "stripped-text": "This is some html", "stripped-signature": "the signature block stripped from the plain text message (if found)", "message-headers": [ [ "Mime-Version", "1.0" ], [ "Subject", "\"Mailgun is awesome\"" ], [ "From", "foo.bar@my-domain.com" ], [ "To", "cool.barr@cool.com, bar.baz@gmail.com" ], [ "X-Mailgun-Tag", "Earth" ], [ "Message-Id", "" ], [ "Content-Transfer-Encoding", "7bit" ], [ "Content-Type", "text/html; charset=ascii" ] ], "X-Mailgun-Template-Name": "my-awesome-template", "X-Mailgun-Template-Variables": "{\"name\":\"Foo\",\"phrase\":\"Bar\"}" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-GetMessageResponseBadRequest" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-GetMessageResponseNotFound" }, "examples": { "Example": { "value": { "message": "Message not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Messages" ], "summary": "Resend an email", "operationId": "POST-v3-domains--domain-name--messages--storage-key-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name used to send the message", "required": true, "schema": { "type": "string" } }, { "name": "storage_key", "in": "path", "description": "Storage key from the email's associated events (Example: Accepted/Delivered events `storage.key` field). Note: Storage keys are available for the duration of your domain's message retention policy.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domains-domain_name-messages-storage_key-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-influx-httpapi-SendMessageResponse" }, "examples": { "Example": { "value": { "id": "message-id", "message": "Queued. Thank you." } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/domains": { "get": { "tags": [ "Domains" ], "summary": "Get domains", "description": "Get the list of domains. Can be filtered by state or authority. Sorting is optional. The list is paginated and limited to 1000 items per page.", "operationId": "GET-v4-domains", "parameters": [ { "name": "limit", "in": "query", "description": "Max count of items. Max: 1000. Default: 100", "schema": { "type": "integer" } }, { "name": "skip", "in": "query", "description": "Get the list of items starting at the nth element. Default: 0", "schema": { "type": "integer" } }, { "name": "state", "in": "query", "description": "Get only domains with a specific state. Can be either active, unverified or disabled.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Valid sort options are `name` which defaults to asc order, `name:asc`, or `name:desc`. If sorting is not specified domains are returned in reverse creation date order.", "schema": { "type": "string" } }, { "name": "authority", "in": "query", "description": "Get only domains with a specific authority. If state is specified then only state filtering will be proceed", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search domains by the given partial or complete name. Does not support wildcards", "schema": { "type": "string" } }, { "name": "include_subaccounts", "in": "query", "description": "Search on every domain that belongs to any subaccounts under this account. Default to false.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-ListDomainResponse" }, "examples": { "200 without subaccount domains": { "value": { "total_count": 1, "items": [ { "created_at": "Mon, 02 Jan 2006 15:04:05 MST", "id": "1", "name": "example.com", "state": "unverified", "type": "custom", "web_prefix": "email", "disabled": { "code": "blacklisted", "note": "for debugging", "permanently": true, "reason": "bad customer" } } ] } }, "200 with subaccount domains": { "value": { "total_count": 1, "items": [ { "created_at": "Mon, 02 Jan 2006 15:04:05 MST", "id": "1", "name": "example.com", "subaccount_id": "6fr783930fhhriu673", "state": "unverified", "type": "custom", "web_prefix": "email", "disabled": { "code": "blacklisted", "note": "for debugging", "permanently": true, "reason": "bad customer" } } ] } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Domains" ], "summary": "Create a domain", "description": "Creates a domain for sending emails", "operationId": "POST-v4-domains", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v4-domains-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-CreateDomainResp" }, "examples": { "Example": { "value": { "message": "Domain DNS records have been created", "domain": { "created_at": "Thu, 13 Oct 2011 18:02:00 GMT", "id": "123456789012345678901234", "name": "example.com", "require_tls": true, "smtp_login": "postmaster@example.com", "spam_action": "disabled", "state": "active", "type": "sandbox", "use_automatic_sender_security": true, "web_prefix": "email", "web_scheme": "http", "encrypt_incoming_message": true, "message_ttl": 86400 }, "receiving_dns_records": [ { "cached": [], "name": "example.com", "priority": "10", "record_type": "MX", "valid": "unknown" } ], "sending_dns_records": [ { "cached": [ "mxa.example.com", "mxb.example.com" ], "name": "example.com", "priority": "10", "record_type": "A", "valid": "valid", "value": "1.2.3.4" } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "message": "Password is too short. It must be between 5 and 32 characters." } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/domains/{name}": { "get": { "tags": [ "Domains" ], "summary": "Get domain details", "description": "Fetches json representation of a domain that includes details about the domain's state and settings.", "operationId": "GET-v4-domains--name-", "parameters": [ { "name": "name", "in": "path", "description": "The name of the domain you want to fetch", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-FindDomainByNameResp" }, "examples": { "Example": { "value": { "domain": { "created_at": "Thu, 13 Oct 2011 18:02:00 GMT", "id": "123456789012345678901234", "name": "example.com", "require_tls": true, "smtp_login": "postmaster@example.com", "spam_action": "disabled", "state": "active", "type": "sandbox", "use_automatic_sender_security": true, "web_prefix": "email", "web_scheme": "http" }, "receiving_dns_records": [ { "is_active": true, "cached": [ "10 mxa.mailgun.org", "10 mxb.mailgun.org" ], "priority": "10", "record_type": "MX", "valid": "valid", "value": "mxa.mailgun.org" }, { "is_active": true, "cached": [ "10 mxa.mailgun.org", "10 mxb.mailgun.org" ], "priority": "10", "record_type": "MX", "valid": "valid", "value": "mxb.mailgun.org" } ], "sending_dns_records": [ { "is_active": true, "cached": [ "v=spf1 include:mailgun.org ~all" ], "name": "mg.example.com", "record_type": "TXT", "valid": "valid", "value": "v=spf1 include:mailgun.org ~all" }, { "is_active": true, "cached": [ "k=rsa; p=M......" ], "name": "mx._domainkey.mg.example.com", "record_type": "TXT", "valid": "valid", "value": "k=rsa; p=M......" }, { "is_active": true, "cached": [ "mailgun.org" ], "name": "email.mg.example.com", "record_type": "CNAME", "valid": "valid", "value": "mailgun.org" } ] } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Domains" ], "summary": "Update domain", "description": "Update domain configuration like smtp credentials, enable/disable automatic sender security, spam actions, wildcard, or tracking web scheme.", "operationId": "PUT-v4-domains--name-", "parameters": [ { "name": "name", "in": "path", "description": "The name of the domain you want to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v4-domains-name-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-UpdateDomainResp" }, "examples": { "Example": { "value": { "domain": { "created_at": "Thu, 13 Oct 2011 18:02:00 GMT", "id": "123456789012345678901234", "name": "example.com", "require_tls": true, "smtp_login": "postmaster@example.com", "spam_action": "disabled", "state": "active", "type": "sandbox", "use_automatic_sender_security": true, "web_prefix": "email", "web_scheme": "http" }, "receiving_dns_records": [ { "cached": [], "name": "example.com", "priority": "10", "record_type": "MX", "valid": "unknown" } ], "sending_dns_records": [ { "cached": [ "mxa.example.com", "mxb.example.com" ], "name": "example.com", "priority": "10", "record_type": "A", "valid": "valid", "value": "1.2.3.4" } ] } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/domains/{name}/verify": { "put": { "tags": [ "Domains" ], "summary": "Verify Domain", "description": "Verify the domains DNS records (includes A, CNAME, SPF, DKIM and MX records) to ensure the domain is ready and able to send", "operationId": "PUT-v4-domains--name--verify", "parameters": [ { "name": "name", "in": "path", "description": "The name of the domain you want to verify", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-VerifyDomainResponse" }, "examples": { "Example": { "value": { "message": "Domain DNS records have been updated", "domain": { "created_at": "Mon, 02 Jan 2006 15:04:05 MST", "id": "123456789012345678901234", "name": "example.com", "require_tls": true, "smtp_login": "postmaster@example.com", "spam_action": "disabled", "state": "unverified", "type": "sandbox", "use_automatic_sender_security": true, "web_prefix": "email", "web_scheme": "http", "disabled": { "code": "blacklisted", "note": "for debugging", "permanently": true, "reason": "bad customer" } }, "sending_dns_records": [ { "cached": [ "mxa.example.com", "mxb.example.com" ], "name": "example.com", "priority": "10", "record_type": "A", "valid": "valid", "value": "0.0.0.0" } ], "receiving_dns_records": [ { "cached": [ "mxa.example.com", "mxb.example.com" ], "name": "example.com", "priority": "10", "record_type": "A", "valid": "valid", "value": "0.0.0.0" } ] } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } }, "429": { "description": "A 429 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}": { "delete": { "tags": [ "Domains" ], "summary": "Delete a domain", "description": "The domain must not be disabled or used as an authority for an other domain. Sandbox domain can't be deleted.", "operationId": "DELETE-v3-domains--name-", "parameters": [ { "name": "name", "in": "path", "description": "The name of the domain to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain will be deleted in the background" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{domain}/webhooks": { "get": { "tags": [ "Domain Webhooks" ], "summary": "Get domain webhooks", "description": "Returns all webhooks for the domain.", "operationId": "GET-v3-domains--domain--webhooks", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name you want webhooks for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-GetAllDomainWebhooksResp" }, "examples": { "Example": { "value": { "webhooks": { "accepted": { "urls": [ "https://foo.com", "https://bar.com" ] }, "delivered": { "urls": [ "https://foo.com", "https://bar.com" ] }, "opened": { "urls": [ "https://foo.com", "https://bar.com" ] }, "clicked": { "urls": [ "https://foo.com", "https://bar.com" ] }, "unsubscribed": { "urls": [ "https://foo.com", "https://bar.com" ] }, "complained": { "urls": [ "https://foo.com", "https://bar.com" ] }, "temporary_fail": { "urls": [ "https://foo.com", "https://bar.com" ] }, "permanent_fail": { "urls": [ "https://foo.com", "https://bar.com" ] } } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Domain Webhooks" ], "summary": "Create a domain webhook", "description": "Create a list of webhook URLs you'd like to receive Mailgun's POST requests containing event information.", "operationId": "POST-v3-domains--domain--webhooks", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name to create the webhook for", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domains-domain-webhooks-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-CreateDomainWebhookResp" }, "examples": { "Example": { "value": { "message": "Webhook has been created", "webhook": { "urls": [ "https://foo.com", "https://bar.com" ] } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Reason": "https://example.com/ is not a valid url: host not found" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{domain_name}/webhooks/{webhook_name}": { "get": { "tags": [ "Domain Webhooks" ], "summary": "Get domain webhooks by type", "description": "Get the list of url(s) for a webhook identified by its webhook_name.", "operationId": "GET-v3-domains--domain-name--webhooks--webhook-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name you want webhooks for", "required": true, "schema": { "type": "string" } }, { "name": "webhook_name", "in": "path", "description": "The webhook type you wish to retrieve.", "required": true, "schema": { "type": "string", "enum": [ "accepted", "clicked", "opened", "unsubscribed", "delivered", "permanent_fail", "temporary_fail", "complained" ], "x-enumDescriptions": { "accepted": "The accepted event occurs when Mailgun accepts a message for delivery.", "clicked": "The clicked event occurs when a recipient clicks a link in the email. This requires click tracking to be enabled for the domain.", "opened": "The opened event occurs when a recipient opens the email. This requires open tracking to be enabled for the domain.", "unsubscribed": "The unsubscribed event occurs when a recipient unsubscribes using an unsubscribe mechanism in your email (for example, a list-unsubscribe link).", "delivered": "The delivered event occurs when an email is successfully delivered to the recipient's mail server.", "permanent_fail": "The permanent_fail event occurs when an email cannot be delivered due to a permanent error.", "temporary_fail": "The temporary_fail event occurs when an email cannot be delivered due to a temporary error.", "complained": "The complained event occurs when a recipient marks your email as spam or their email provider registers a spam complaint." } } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-GetDomainWebhookResp" }, "examples": { "Example": { "value": { "webhook": { "urls": [ "https://foo.com" ] } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Domain Webhooks" ], "summary": "Update domain webhook", "description": "Replace the list of urls by the given one with the `url` param. Here is the list of supported webhook: `accepted`, `opened`, `clicked`, `unsubscribed`, `delivered`, `permanent_fail`, `temporary_fail` and `complained`.", "operationId": "PUT-v3-domains--domain-name--webhooks--webhook-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "The name of the domain you want to get webhook from", "required": true, "schema": { "type": "string" } }, { "name": "webhook_name", "in": "path", "description": "The webhook type to update.", "required": true, "schema": { "type": "string", "enum": [ "accepted", "clicked", "opened", "unsubscribed", "delivered", "permanent_fail", "temporary_fail", "complained" ], "x-enumDescriptions": { "accepted": "The accepted event occurs when Mailgun accepts a message for delivery.", "clicked": "The clicked event occurs when a recipient clicks a link in the email. This requires click tracking to be enabled for the domain.", "opened": "The opened event occurs when a recipient opens the email. This requires open tracking to be enabled for the domain.", "unsubscribed": "The unsubscribed event occurs when a recipient unsubscribes using an unsubscribe mechanism in your email (for example, a list-unsubscribe link).", "delivered": "The delivered event occurs when an email is successfully delivered to the recipient's mail server.", "permanent_fail": "The permanent_fail event occurs when an email cannot be delivered due to a permanent error.", "temporary_fail": "The temporary_fail event occurs when an email cannot be delivered due to a temporary error.", "complained": "The complained event occurs when a recipient marks your email as spam or their email provider registers a spam complaint." } } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v3-domains-domain_name-webhooks-webhook_name-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-CreateDomainWebhookResp" }, "examples": { "Example": { "value": { "message": "Webhook has been updated", "webhook": { "urls": [ "https://foo.com" ] } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Reason": "https://example.com/ is not a valid url: host not found" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Domain Webhooks" ], "summary": "Delete domain webhooks by type", "description": "Remove all url(s) for a specified webhook type.", "operationId": "DELETE-v3-domains--domain-name--webhooks--webhook-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "The domain name you want to delete the webhook(s) for", "required": true, "schema": { "type": "string" } }, { "name": "webhook_name", "in": "path", "description": "The name of the webhook to delete.", "required": true, "schema": { "type": "string", "enum": [ "accepted", "clicked", "opened", "unsubscribed", "delivered", "permanent_fail", "temporary_fail", "complained" ], "x-enumDescriptions": { "accepted": "The accepted event occurs when Mailgun accepts a message for delivery.", "clicked": "The clicked event occurs when a recipient clicks a link in the email. This requires click tracking to be enabled for the domain.", "opened": "The opened event occurs when a recipient opens the email. This requires open tracking to be enabled for the domain.", "unsubscribed": "The unsubscribed event occurs when a recipient unsubscribes using an unsubscribe mechanism in your email (for example, a list-unsubscribe link).", "delivered": "The delivered event occurs when an email is successfully delivered to the recipient's mail server.", "permanent_fail": "The permanent_fail event occurs when an email cannot be delivered due to a permanent error.", "temporary_fail": "The temporary_fail event occurs when an email cannot be delivered due to a temporary error.", "complained": "The complained event occurs when a recipient marks your email as spam or their email provider registers a spam complaint." } } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-CreateDomainWebhookResp" }, "examples": { "Example": { "value": { "message": "Webhook has been deleted", "webhook": { "urls": [ "https://foo.com" ] } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/domains/{domain}/webhooks": { "put": { "tags": [ "Domain Webhooks" ], "summary": "Update domain webhooks (v4)", "description": "Update webhook URL to associate it with different event types. This replaces the existing event type associations for the given URL.", "operationId": "PUT-v4-domains--domain--webhooks", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name to update webhooks for", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PUT-v4-domains-domain-webhooks-application-x-www-form-urlencoded-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-GetAllDomainWebhooksResp" }, "examples": { "Example": { "value": { "webhooks": { "delivered": { "urls": [ "https://example.com/webhooks" ] }, "opened": { "urls": [ "https://example.com/webhooks" ] }, "clicked": { "urls": [ "https://foo.com" ] } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Reason": "invalid parameters: https://invalid is not a valid url: invalid URL scheme" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "Description": "Webhook not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Domain Webhooks" ], "summary": "Create domain webhooks (v4)", "description": "Create webhook URLs for multiple event types in a single operation. This v4 endpoint allows associating one URL with multiple webhook event types.", "operationId": "POST-v4-domains--domain--webhooks", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name to create webhooks for", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/POST-v4-domains-domain-webhooks-application-x-www-form-urlencoded-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-GetAllDomainWebhooksResp" }, "examples": { "Example": { "value": { "webhooks": { "accepted": { "urls": [ "https://example.com/webhooks" ] }, "delivered": { "urls": [ "https://example.com/webhooks" ] }, "clicked": { "urls": [ "https://foo.com" ] }, "permanent_fail": { "urls": [ "https://bar.com" ] } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Reason": "Webhook for event type 'clicked' with URL 'https://example.com/webhooks' already exists" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Domain Webhooks" ], "summary": "Delete domain webhooks (v4)", "description": "Delete webhook URLs from all event types they are associated with. Supports deleting multiple URLs at once by providing a comma-separated list.", "operationId": "DELETE-v4-domains--domain--webhooks", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name to delete webhooks from", "required": true, "schema": { "type": "string" } }, { "name": "url", "in": "query", "description": "The webhook URL(s) to delete. Supports comma-separated URLs to delete multiple at once (e.g., `url1,url2,url3`). Each URL will be removed from all event types.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-GetAllDomainWebhooksResp" }, "examples": { "Example": { "value": { "webhooks": { "delivered": { "urls": [ "https://example.com/webhooks" ] }, "clicked": { "urls": [ "https://foo.com" ] } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Field": "url" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}/tracking": { "get": { "tags": [ "Domain Tracking" ], "summary": "Get tracking settings", "description": "Use to check if open, click and unsubscribe tracking are active/inactive.", "operationId": "GET-v3-domains--name--tracking", "parameters": [ { "name": "name", "in": "path", "description": "The name of the domain to fetch tracking details for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-GetDomainTrackingResp" }, "examples": { "Example": { "value": { "tracking": { "open": { "active": true }, "click": { "active": true }, "unsubscribe": { "active": true, "html_footer": "off", "text_footer": "on" }, "web_scheme": "http" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}/tracking/click": { "put": { "tags": [ "Domain Tracking" ], "summary": "Update click tracking settings", "description": "Use to turn on/off the click tracking at the domain level.", "operationId": "PUT-v3-domains--name--tracking-click", "parameters": [ { "name": "name", "in": "path", "description": "The name of the domain you want to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v3-domains-name-tracking-click-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-UpdateDomainTrackingClickResp" }, "examples": { "Example": { "value": { "message": "Domain tracking settings have been updated", "click": { "active": true } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}/tracking/open": { "put": { "tags": [ "Domain Tracking" ], "summary": "Update open tracking settings", "description": "Use to turn on/off the open tracking at the domain level.", "operationId": "PUT-v3-domains--name--tracking-open", "parameters": [ { "name": "name", "in": "path", "description": "The name of the domain you want to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v3-domains-name-tracking-open-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-UpdateDomainTrackingOpenResp" }, "examples": { "Example": { "value": { "message": "Domain tracking settings have been updated", "open": { "active": true } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}/tracking/unsubscribe": { "put": { "tags": [ "Domain Tracking" ], "summary": "Update unsubscribe tracking settings", "description": "Use to turn on/off the unsubscribe tracking at the domain level.", "operationId": "PUT-v3-domains--name--tracking-unsubscribe", "parameters": [ { "name": "name", "in": "path", "description": "The name of the domain you want to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v3-domains-name-tracking-unsubscribe-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-UpdateDomainTrackingUnsubscribeResp" }, "examples": { "Example": { "value": { "message": "Domain tracking settings have been updated", "unsubscribe": { "active": true, "html_footer": "
\n

unsubscribe

\n", "text_footer": "To unsubscribe click: <%unsubscribe_url%>\n\n" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/dkim/keys": { "get": { "tags": [ "Domain Keys" ], "summary": "List keys for all domains", "description": "List domain keys, and optionally filter by signing domain or selector. Results are paginated - use the 'limit' parameter to control page size (default 10, max 100). Use the 'page' parameter from the paging response URLs to navigate through pages.", "operationId": "GET-v1-dkim-keys", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/GET-v1-dkim-keys-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-DomainKeyListResponse" }, "examples": { "Example": { "value": { "items": [ { "signing_domain": "authority.domain.tld", "selector": "s1", "dns_record": { "is_active": true, "cached": [ "cached dns value" ], "name": "s1._domainkey.authority.domain.tld", "record_type": "TXT", "valid": "VALID", "value": "expected dns value" } }, { "signing_domain": "authority.domain.tld", "selector": "s2", "dns_record": { "cached": [ "cached dns value" ], "name": "s2._domainkey.authority.domain.tld", "record_type": "TXT", "valid": "UNKNOWN", "value": "expected dns value" } } ], "paging": { "previous": "/v1/dkim/keys?page=", "first": "/v1/dkim/keys", "next": "/v1/dkim/keys?page=", "last": "/v1/dkim/keys?page=" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Domain Keys" ], "summary": "Create a domain key", "description": "Create a domain key. Note that once private keys are created or imported they are never exported.\nAlternatively, you can import an existing PEM file containing a RSA private key in PKCS #1, ASn.1 DER\n\t\t\t format. Note, the pem can be passed as a file attachment or as a form-string parameter.", "operationId": "POST-v1-dkim-keys", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v1-dkim-keys-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-DomainKeyResponse" }, "examples": { "Example": { "value": { "signing_domain": "example.com", "selector": "s1", "dns_record": { "cached": [], "name": "s1._domainkey.example.com", "record_type": "TXT", "valid": "unknown", "value": "k=rsa; p=" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Domain Keys" ], "summary": "Delete a domain key", "description": "Domain keys are not recoverable after deletion so use with care", "operationId": "DELETE-v1-dkim-keys", "parameters": [ { "name": "signing_domain", "in": "query", "description": "Signing Domain", "required": true, "schema": { "type": "string" } }, { "name": "selector", "in": "query", "description": "Selector", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "success" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "cannot delete domain key: must have at least one active domain key" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "domain key not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/domains/{authority_name}/keys/{selector}/activate": { "put": { "tags": [ "Domain Keys" ], "summary": "Activate a domain key", "description": "Activate a key to be used to DKIM sign emails with. Note: dns records must be valid for a domain key to be activated", "operationId": "PUT-v4-domains--authority-name--keys--selector--activate", "parameters": [ { "name": "authority_name", "in": "path", "description": "The domain authority name you want to activate. Must be a valid domain", "required": true, "schema": { "type": "string" } }, { "name": "selector", "in": "path", "description": "The selector you want to activate for the domain key. Must be a valid dot atom", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-UpdateDomainKeyResp" }, "examples": { "Example": { "value": { "message": "domain key activated", "authority": "authority.domain.tld", "selector": "selector", "active": true } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "domain key not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/domains/{authority_name}/keys": { "get": { "tags": [ "Domain Keys" ], "summary": "List domain keys", "description": "List all domain keys for your domain, including active/inactive and valid/invalid ones.", "operationId": "GET-v4-domains--authority-name--keys", "parameters": [ { "name": "authority_name", "in": "path", "description": "The domain authority name you want to list the domain keys for. Must be a valid domain", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-AuthorityKeysResponse" }, "examples": { "Example": { "value": { "items": [ { "signing_domain": "authority.domain.tld", "selector": "s1", "dns_record": { "is_active": true, "cached": [ "cached dns value" ], "name": "s1._domainkey.authority.domain.tld", "record_type": "TXT", "valid": "VALID", "value": "expected dns value" } }, { "signing_domain": "authority.domain.tld", "selector": "s2", "dns_record": { "cached": [ "cached dns value" ], "name": "s2._domainkey.authority.domain.tld", "record_type": "TXT", "valid": "UNKNOWN", "value": "expected dns value" } } ] } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/domains/{authority_name}/keys/{selector}/deactivate": { "put": { "tags": [ "Domain Keys" ], "summary": "Deactivate a domain key", "description": "Deactivating for a specified authority and/or selector means a key won't be used for signing email anymore, even if they are valid.", "operationId": "PUT-v4-domains--authority-name--keys--selector--deactivate", "parameters": [ { "name": "authority_name", "in": "path", "description": "The domain authority name you want to deactivate. Must be a valid domain", "required": true, "schema": { "type": "string" } }, { "name": "selector", "in": "path", "description": "The selector you want to deactivate for the domain key. Must be a valid dot atom", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-UpdateDomainKeyResp" }, "examples": { "Example": { "value": { "message": "domain key deactivated", "authority": "authority.domain.tld", "selector": "selector", "active": true } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "domain key not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}/dkim_authority": { "put": { "tags": [ "Domain Keys" ], "summary": "Update DKIM authority", "description": "You can delegate the domain authority to an other domain. Domain's authority is set to itself by default.", "operationId": "PUT-v3-domains--name--dkim-authority", "parameters": [ { "name": "name", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v3-domains-name-dkim_authority-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-ReassignDkimAuthorityResp" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}/dkim_selector": { "put": { "tags": [ "Domain Keys" ], "summary": "Update a DKIM selector", "description": "Selector is the unique identifier of your key. It has to be different from other keys selector.", "operationId": "PUT-v3-domains--name--dkim-selector", "parameters": [ { "name": "name", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v3-domains-name-dkim_selector-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "DKIM selector changed" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/webhooks": { "get": { "tags": [ "Account Webhooks" ], "summary": "List account-level webhooks", "description": "Retrieve all account-level webhooks or filter by specific webhook IDs. Returns webhook details including associated event types.", "operationId": "GET-v1-webhooks", "parameters": [ { "name": "webhook_ids", "in": "query", "description": "Comma-separated list of webhook IDs to filter results. If specified, only webhooks with matching IDs will be returned.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-AccountLevelWebhooksResp" }, "examples": { "Example": { "value": { "webhooks": [ { "webhook_id": "507f1f77bcf86cd799439011", "description": "Production alerts webhook", "url": "https://api.example.com/webhooks/mailgun", "event_types": [ "delivered", "permanent_fail", "complained" ], "created_at": "2026-02-16T19:06:01Z" }, { "webhook_id": "507f1f77bcf86cd799439012", "description": "Analytics webhook", "url": "https://analytics.example.com/mailgun", "event_types": [ "opened", "clicked" ], "created_at": "2026-02-16T19:06:01Z" } ] } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Forbidden" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Account Webhooks" ], "summary": "Create an account-level webhook", "description": "Create account-level webhook URLs to receive Mailgun's POST requests containing event information across all domains in your account. Note: Webhook changes can take up to 10 minutes to become effective due to caching.", "operationId": "POST-v1-webhooks", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v1-webhooks-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-CreateAccountLevelWebhookResp" }, "examples": { "Example": { "value": { "webhook_id": "507f1f77bcf86cd799439011" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "Field": "event_types", "Value": "duplicate event types: 'accepted'" } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Forbidden" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError" }, "examples": { "Example": { "value": { "Description": "event_type 'invalid_type' is invalid" } } } } } }, "409": { "description": "A 409 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-ConflictError" }, "examples": { "Example": { "value": { "Description": "unable to add more than 3 urls for event type delivered" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Account Webhooks" ], "summary": "Delete account-level webhooks", "description": "Delete account-level webhooks for the authenticated account. You can either delete all webhooks by setting all=true, or specify specific webhook IDs to delete via webhook_ids. If both are provided, the specific webhook_ids will be deleted. Note: Webhook changes can take up to 10 minutes to become effective due to caching.", "operationId": "DELETE-v1-webhooks", "parameters": [ { "name": "webhook_ids", "in": "query", "description": "Comma-separated list of webhook IDs to delete. If provided, only these specific webhooks will be deleted.", "schema": { "type": "string" } }, { "name": "all", "in": "query", "description": "Set to 'true' to delete all account-level webhooks. This acts as a safety mechanism to prevent accidental deletion of all webhooks.", "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "A 204 response" }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid parameter: webhook_ids malformed webhook_ids parameter: empty values not allowed" } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Forbidden" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError" }, "examples": { "Example": { "value": { "Description": "no webhooks found for account" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/webhooks/{webhook_id}": { "get": { "tags": [ "Account Webhooks" ], "summary": "Get account-level webhook by ID", "description": "Retrieve a specific account-level webhook by its webhook ID. Returns webhook details including associated event types.", "operationId": "GET-v1-webhooks--webhook-id-", "parameters": [ { "name": "webhook_id", "in": "path", "description": "The webhook ID to retrieve", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-AccountLevelWebhookView" }, "examples": { "Example": { "value": { "webhook_id": "507f1f77bcf86cd799439011", "description": "Production alerts webhook", "url": "https://api.example.com/webhooks/mailgun", "event_types": [ "delivered", "permanent_fail", "complained" ], "created_at": "2026-02-16T19:06:01Z" } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Forbidden" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError" }, "examples": { "Example": { "value": { "Description": "webhook not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Account Webhooks" ], "summary": "Update an account-level webhook", "description": "Update an existing account-level webhook by replacing its URL, description, and event types. The webhook is identified by webhook_id and completely replaced with the new configuration. Note: Webhook changes can take up to 10 minutes to become effective due to caching.", "operationId": "PUT-v1-webhooks--webhook-id-", "parameters": [ { "name": "webhook_id", "in": "path", "description": "The webhook ID to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v1-webhooks-webhook_id-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "204": { "description": "A 204 response" }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "Field": "url", "Value": "missing or invalid url parameter" } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Forbidden" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError" }, "examples": { "Example": { "value": { "Description": "webhook_id not found: 507f1f77bcf86cd799439011" } } } } } }, "409": { "description": "A 409 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-ConflictError" }, "examples": { "Example": { "value": { "Description": "url https://example.com already exists for event type delivered" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Account Webhooks" ], "summary": "Delete account-level webhook by ID", "description": "Delete a specific account-level webhook by its webhook ID. This removes the webhook from all associated event types. Note: Webhook changes can take up to 10 minutes to become effective due to caching.", "operationId": "DELETE-v1-webhooks--webhook-id-", "parameters": [ { "name": "webhook_id", "in": "path", "description": "The webhook ID to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "A 204 response" }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-InvalidParameterError" }, "examples": { "Example": { "value": { "Field": "webhook_id", "Value": "is not valid" } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Forbidden" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError" }, "examples": { "Example": { "value": { "Description": "webhook_id not found: 507f1f77bcf86cd799439011" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}/sending_queues": { "get": { "tags": [ "Messages" ], "summary": "Get messages queue status", "description": "Provides default and scheduled message queue information.", "operationId": "GET-v3-domains--name--sending-queues", "parameters": [ { "name": "name", "in": "path", "description": "The name of the domain you want get sending queues from", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-GetDomainSendingQueuesResp" }, "examples": { "Example": { "value": { "regular": { "is_disabled": true, "disabled": { "until": "Mon, 02 Jan 2006 15:04:05 MST", "reason": "You have too many messages in queue" } }, "scheduled": { "is_disabled": true, "disabled": { "until": "Mon, 02 Jan 2006 15:04:05 MST", "reason": "You have too many messages in queue" } } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/dkim_management/domains/{name}/rotation": { "put": { "tags": [ "DKIM Security" ], "summary": "Update Automatic Sender Security DKIM key rotation for a domain", "description": "The minimum allowed interval for rotation is 5 days.", "operationId": "PUT-v1-dkim-management-domains--name--rotation", "parameters": [ { "name": "name", "in": "path", "description": "The Domain name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v1-dkim_management-domains-name-rotation-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-pendulum-api-DomainResponse" }, "examples": { "Example": { "value": { "domain": { "id": "000000000000000000000002", "account_id": "000000000000000000000001", "sid": "789", "name": "example.com", "state": "enabled", "active_selector": "pdk1", "rotation_enabled": "true", "rotation_interval": "24h", "records": [ { "name": "pdk1._domainkey.example.com", "type": "CNAME", "identifier": "DKIM", "value": "pdk1._domainkey.1234567.service.mailgun.com", "comment": "Customer DKIM CNAME Record" }, { "name": "pdk2._domainkey.example.com", "type": "CNAME", "identifier": "DKIM", "value": "pdk2._domainkey.1234567.service.mailgun.com", "comment": "Customer DKIM CNAME Record" } ] } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Reason": "rotation_interval is not allowed unless also enabling DKIM rotation" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError" }, "examples": { "Example": { "value": { "Description": "domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/dkim_management/domains/{name}/rotate": { "post": { "tags": [ "DKIM Security" ], "summary": "Rotate Automatic Sender Security DKIM key for a domain", "description": "Immediately rotate your DKIM key. This will trigger a rotation even if auto-rotation is disabled on the domain.", "operationId": "POST-v1-dkim-management-domains--name--rotate", "parameters": [ { "name": "name", "in": "path", "description": "The Domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "ok" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Reason": "only domains in enabled can rotate their keys. Current state: wait_verify" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError" }, "examples": { "Example": { "value": { "Description": "domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/subaccounts/ip_pools/all": { "get": { "tags": [ "Delegated DIPPs" ], "summary": "List DIPPs delegated to subaccounts", "description": "#### Description\nLists all subaccounts of the parent account to which the parent account has\ndelegated DIPPs.", "operationId": "GET-v5-accounts-subaccounts-ip-pools-all", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-subaccounts-ListSubaccountDIPPsResponse" }, "examples": { "Example": { "value": { "items": [ { "pool_id": "69c15db8a432c65972c789db", "subaccount_id": "69c15db8a432c65972c789dc" }, { "pool_id": "69c15db8a432c65972c789dd", "subaccount_id": "69c15db8a432c65972c789de" } ], "total_count": 2 } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "account not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/subaccounts/{subaccountId}/ip_pool": { "put": { "summary": "Delegate a DIPP to a subaccount", "description": "#### Description\nInitiates the process to delegate a DIPP to a subaccount. If the subaccount already\nhas a DIPP delegated to it, that DIPP will be replaced. The success of this API call\nonly indicates that the process has been started; it can still fail midway for\nvarious reasons. This endpoint cannot be used with subaccounts that have multiple\ninherited DIPPs.\n\n#### Request Schema\nRequest parameters are encoded as form data.\n\nName | Description | Required | Type\n--- | --- | --- | ---\npool_id | Id of the DIPP to delegate | true | string", "operationId": "PUT-v5-accounts-subaccounts--subaccountId--ip-pool", "parameters": [ { "name": "subaccountId", "in": "path", "description": "Id of the subaccount to delegate the DIPP to", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-StartSagaResponse" }, "examples": { "Example": { "value": { "message": "started", "reference_id": "69c15db8a432c65972c789e0" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "invalid request parameters" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "account not found" } } } } } } }, "deprecated": true, "tags": [ "openapi-tower_other" ], "security": [ { "basicAuth": [] } ] }, "delete": { "summary": "Revoke a DIPP delegated to a subaccount", "description": "#### Description\nInitiates the process to revoke a DIPP delegated to a subaccount. All domains linked\nto the DIPP will be unlinked. This endpoint cannot be used with subaccounts that have\nmultiple inherited DIPPs.", "operationId": "DELETE-v5-accounts-subaccounts--subaccountId--ip-pool", "parameters": [ { "name": "subaccountId", "in": "path", "description": "Id of the subaccount to revoke the DIPP from", "required": true, "schema": { "type": "string" } }, { "name": "pool_id", "in": "query", "description": "Id of the DIPP to revoke", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-StartSagaResponse" }, "examples": { "Example": { "value": { "message": "started", "reference_id": "69c15db8a432c65972c789df" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "invalid request parameters" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "account not found" } } } } } } }, "deprecated": true, "tags": [ "openapi-tower_other" ], "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}/ips/{ip}": { "delete": { "tags": [ "IPs", "IP Pools" ], "summary": "Remove an IP from the domain pool, unlink a DIPP or remove the domain pool", "description": "The behavior of the endpoint depends on the value of the `ip` parameter. It can be\none of the following:\n * a valid IP address: this IP address will be removed from the domain pool.\n * string `all`: the entire domain pool will be removed. As far as the system is\n concerned, such domain will no longer exist.\n * string `ip_pool`: the DIPP which is currently linked to the domain will be\n unlinked.\n\n### Removing An IP\nNote that it's impossible to alter domain IPs if a DIPP is linked to the domain.\n\nIf the account is not eligible for shared IPs, additional rules apply:\n * removing the last IP from the domain is not allowed;\n * if all of the remaining dedicated IPs are on warmup, an extra IP might be added to\n the domain pool.\n\n### Unlinking The DIPP\nThe account must have 'DIPPs' feature enabled.\n\nEither `ip` or `pool_id` query parameter must be specified, but not both.\n\nIf the special value `shared` is used for the replacement IP, the account must be\neligible for shared IPs. In this case the system will assign a shared IP as the\nreplacement.", "operationId": "DELETE-v3-domains--name--ips--ip-", "parameters": [ { "name": "ip", "in": "path", "description": "One of the following: `all`, `ip_pool` or a valid IP address.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Domain name. Converted to `X-Mailgun-Domain-Id` header by the middleware.", "required": true, "schema": { "type": "string" } }, { "name": "ip", "in": "query", "description": "Replacement IP or special value `shared`.", "schema": { "type": "string" } }, { "name": "pool_id", "in": "query", "description": "Replacement DIPP id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}/pool/{ip}": { "delete": { "tags": [ "IPs", "IP Pools" ], "summary": "Remove an IP from the domain pool, unlink a DIPP or remove the domain pool", "description": "The behavior of the endpoint depends on the value of the `ip` parameter. It can be\none of the following:\n * a valid IP address: this IP address will be removed from the domain pool.\n * string `all`: the entire domain pool will be removed. As far as the system is\n concerned, such domain will no longer exist.\n * string `ip_pool`: the DIPP which is currently linked to the domain will be\n unlinked.\n\n### Removing An IP\nNote that it's impossible to alter domain IPs if a DIPP is linked to the domain.\n\nIf the account is not eligible for shared IPs, additional rules apply:\n * removing the last IP from the domain is not allowed;\n * if all of the remaining dedicated IPs are on warmup, an extra IP might be added to\n the domain pool.\n\n### Unlinking The DIPP\nThe account must have 'DIPPs' feature enabled.\n\nEither `ip` or `pool_id` query parameter must be specified, but not both.\n\nIf the special value `shared` is used for the replacement IP, the account must be\neligible for shared IPs. In this case the system will assign a shared IP as the\nreplacement.", "operationId": "DELETE-v3-domains--name--pool--ip-", "parameters": [ { "name": "ip", "in": "path", "description": "One of the following: `all`, `ip_pool` or a valid IP address.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Domain name. Converted to `X-Mailgun-Domain-Id` header by the middleware.", "required": true, "schema": { "type": "string" } }, { "name": "ip", "in": "query", "description": "Replacement IP or special value `shared`.", "schema": { "type": "string" } }, { "name": "pool_id", "in": "query", "description": "Replacement DIPP id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{name}/dynamic_pools": { "post": { "tags": [ "Dynamic IP Pools" ], "summary": "Enroll domain", "description": "Domains enrolled in the Dynamic IP pools feature will be assigned an IP pool based on reputation.\nThe feature must be enabled and configured before enrolling domains.", "operationId": "POST-v3-domains--name--dynamic-pools", "parameters": [ { "name": "name", "in": "path", "description": "Domain name", "required": true, "schema": { "type": "string" } }, { "name": "replacement_ip", "in": "query", "description": "A valid IP address or 'shared'", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Dynamic IP Pools" ], "summary": "Remove domain from dynamic IP pools", "description": "The behavior of this endpoint depends on the value of the `replacement_ip` and `replacement_pool_id` parameters.\nOne of these parameters (but not both) must be provided. If `replacement_ip` is provided, the IP(s) will be assigned to the domain.\n`replacement_ip` can include one of the following:\n * valid IP(s): this IP address or addresses will be added to the domain\n * string `shared`: if the account is eligible for shared IPs, a suitable shared IP will be chosen and added to the domain\nThe 'replacement_ip' parameter cannot include any IPs that are already assigned to a Dedicated IP Pool or a Dynamic IP Pool.\nIf `replacement_pool_id` is provided, the Dedicated IP Pool will be assigned to the domain.", "operationId": "DELETE-v3-domains--name--dynamic-pools", "parameters": [ { "name": "name", "in": "path", "description": "Domain name", "required": true, "schema": { "type": "string" } }, { "name": "replacement_ip", "in": "query", "description": "A valid IP address or 'shared'. This field can be specified multiple times if all provided IPs are dedicated. Cannot be provided if providing 'replacement_pool_id' param", "required": true, "schema": { "type": "string" } }, { "name": "replacement_pool_id", "in": "query", "description": "A valid dedicated IP pool ID to assign to the domain. Cannot be provided if providing 'replacement_ip' param", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/dynamic_pools/assignable": { "get": { "tags": [ "Dynamic IP Pools" ], "summary": "List assignable domains", "description": "Lists all domains that are not already enrolled in dynamic IP pools.", "operationId": "GET-v3-domains-dynamic-pools-assignable", "parameters": [ { "name": "subaccount_id", "in": "query", "description": "If provided, queries domains belonging to the subaccount. Must be a valid account ID", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "description": "Regex search term to query a domain by name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "items": [ { "account_id": "69c15db8a432c65972c789cd", "id": "69c15db8a432c65972c789cc", "name": "example.com" } ] } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/all/dynamic_pools/enroll": { "post": { "tags": [ "Dynamic IP Pools" ], "summary": "Enroll all account domains", "description": "Begins an asynchronous background job to assign all domains to Dynamic IP Pools.\nThis can also include domains belonging to subaccounts depending on the provided parameters.\nThe Dynamic IP Pools feature must be enabled for the account and the request must come from a parent account user.", "operationId": "POST-v3-domains-all-dynamic-pools-enroll", "parameters": [ { "name": "include_subaccounts", "in": "query", "description": "If true, domains belonging to subaccounts will also be enrolled in Dynamic IP Pools", "required": true, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "started" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ips": { "get": { "tags": [ "IPs" ], "summary": "List account IPs", "description": "`assignable_to_pool` in response lists which IPs can be assigned to DIPPs; this\nfield is present only if the account has 'DIPPs' feature enabled.\n\n`total_count` contains the number of items returned in `items` (this depends on the\nfilters applied).", "operationId": "GET-v3-ips", "parameters": [ { "name": "dedicated", "in": "query", "description": "Return only dedicated IPs", "schema": { "type": "boolean" } }, { "name": "enabled", "in": "query", "description": "Return only enabled IPs", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-account-list_ips-docResponse" }, "examples": { "Example": { "value": { "assignable_to_pools": [ "5.6.7.8" ], "details": [ { "ip": "1.2.3.4", "is_on_warmup": true }, { "ip": "5.6.7.8" } ], "items": [ "1.2.3.4", "5.6.7.8" ], "total_count": 2 } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ips/{ip}": { "get": { "tags": [ "IPs" ], "summary": "Get details about account IP", "operationId": "GET-v3-ips--ip-", "parameters": [ { "name": "ip", "in": "path", "description": "IP address to get details about", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-account-getDocResponse" }, "examples": { "Example": { "value": { "dedicated": true, "ip": "1.2.3.4", "rdns": "ip1-2-3-4.mailgun.net" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ips/{ip}/domains": { "get": { "tags": [ "IPs" ], "summary": "Get all domains of an account where a specific IP is assigned", "description": "The IP must belong to the account.\n\nMatching domains are ordered by increasing id, then the `limit` and `skip` parameters\nare applied.\n\nIf the `search` parameter is present, it is used to limit the results to domains\nwhose names match the search query. The search query is split into words by \nwhitespace and punctuation, then the logical OR is applied.", "operationId": "GET-v3-ips--ip--domains", "parameters": [ { "name": "ip", "in": "path", "description": "The IP to filter on", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit to apply to the returned domains", "required": true, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "The search query that the returned domains' names must match", "required": true, "schema": { "type": "string" } }, { "name": "skip", "in": "query", "description": "The number of matching domains to skip in the response", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-account-domainsResponse" }, "examples": { "Example": { "value": { "items": [ { "ips": [ "1.2.3.4", "5.6.7.8" ], "domain": "one.example.com" }, { "ips": [ "1.2.3.4" ], "domain": "two.example.com" } ], "total_count": 2 } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "IPs" ], "summary": "Assign an IP to all account domains", "description": "The IP must belong to the account.", "operationId": "POST-v3-ips--ip--domains", "parameters": [ { "name": "ip", "in": "path", "description": "The IP to Add", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-StartSagaResponse" }, "examples": { "Example": { "value": { "message": "started", "reference_id": "61926093321d1cba88f3b95b" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "IPs" ], "summary": "Remove an IP from all account domains", "description": "The IP must belong to the account.\n\nIf the `alternative` parameter is present, it is used to replace the removed ip on all domains.", "operationId": "DELETE-v3-ips--ip--domains", "parameters": [ { "name": "ip", "in": "path", "description": "The IP to Remove", "required": true, "schema": { "type": "string" } }, { "name": "alternative", "in": "query", "description": "An IP that will replace the removed IP on all domains", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-StartSagaResponse" }, "examples": { "Example": { "value": { "message": "started", "reference_id": "61926093321d1cba88f3b95b" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ips/{addr}/ip_band": { "post": { "tags": [ "IPs" ], "summary": "Place account IP into a dedicated IP band", "description": "The `Dedicated IP Bands` feature must be enabled for the account.\n\nThe IP must be a dedicated one belonging to the account.", "operationId": "POST-v3-ips--addr--ip-band", "parameters": [ { "name": "addr", "in": "path", "description": "IP address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-ips-addr-ip_band-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "success" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "error": "invalid parameters" } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "error": "\"Dedicated IP Bands\" feature is not enabled for this account" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "error": "IP not found or doesn't belong to the account" } } } } } }, "409": { "description": "A 409 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "error": "IP is already locked" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ips/request/new": { "get": { "tags": [ "IPs" ], "summary": "Return the number of IPs available to the account per its billing plan", "description": "This endpoint remains active for backwards compatibility. Do not use it in new code.\n\nField `shared` in the response is deprecated and should not be used.", "operationId": "GET-v3-ips-request-new", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "allowed": { "dedicated": 1, "shared": 2 } } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "IPs" ], "summary": "Add a new dedicated IP to the account", "description": "A new IP can be assigned only if billing limits allow that.", "operationId": "POST-v3-ips-request-new", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ips/details/all": { "get": { "tags": [ "IPs" ], "summary": "List account IPs - detailed view", "description": "List IPs belonging to the account and subaccounts. For IPs linked to subaccounts, there will be an additional record returned per subaccount\nThe detailed IP view feature must be enabled for the account.", "operationId": "GET-v3-ips-details-all", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum records to return", "schema": { "type": "integer", "maximum": 100, "minimum": 10, "default": 10 } }, { "name": "skip", "in": "query", "description": "The amount of returned records to skip", "schema": { "type": "integer", "default": 0 } }, { "name": "pool_id", "in": "query", "description": "Filter IPs linked to a pool. Value can be a specific pool ID, 'any' or 'none'", "schema": { "type": "string" } }, { "name": "domain_id", "in": "query", "description": "Filter IPs linked to a domain. Value can be a specific domain ID, 'any' or 'none'", "schema": { "type": "string" } }, { "name": "subaccount_id", "in": "query", "description": "Filter IPs linked to a subaccount. Value can be a specific subaccount ID, 'any' or 'none'", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Name of the field to sort results by", "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Sort results 'descending' or 'ascending'", "schema": { "type": "string", "default": "ascending" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-account-list_ips-DetailedIPsResponseDoc" }, "examples": { "Example": { "value": { "items": [ { "address": "1.0.0.1", "parent_account_id": "69c15db8a432c65972c789ce", "account_id": "69c15db8a432c65972c789ce", "pool_ids": [], "dedicated": true, "created_at": "2026-02-09T12:30:00Z", "pool_last_modified_at": "2026-02-09T15:30:00Z", "domains_last_modified_at": "2026-02-10T12:30:00Z" }, { "address": "1.0.0.2", "parent_account_id": "69c15db8a432c65972c789ce", "account_id": "69c15db8a432c65972c789ce", "pool_ids": [ "69c15db8a432c65972c789d1" ], "dedicated": true, "created_at": "2026-02-09T12:30:00Z", "pool_last_modified_at": "2026-02-09T15:30:00Z", "domains_last_modified_at": "2026-02-10T12:30:00Z" }, { "address": "1.0.0.2", "parent_account_id": "69c15db8a432c65972c789ce", "account_id": "69c15db8a432c65972c789d3", "pool_ids": [], "dedicated": true, "created_at": "2026-02-09T12:30:00Z", "pool_last_modified_at": "2026-02-09T15:30:00Z", "domains_last_modified_at": "2026-02-10T12:30:00Z" } ], "total_count": 3 } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/dynamic_pools": { "get": { "tags": [ "Dynamic IP Pools" ], "summary": "List all Dynamic IP pools", "description": "Returns the list of IPs belonging to each of the account's Dynamic IP Pools.", "operationId": "GET-v3-dynamic-pools", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-Response" }, "examples": { "Example": { "value": { "good_reputation": [ "1.0.0.1", "1.0.0.2" ], "poor_reputation": [ "1.0.0.3" ], "new_senders": [ "1.0.0.4" ], "pools": [ { "account_id": "69c15db8a432c65972c789d4", "enabled": true, "id": "69c15db8a432c65972c789d5", "ips": [ "1.0.0.1", "1.0.0.2" ], "name": "dynamic_good" }, { "account_id": "69c15db8a432c65972c789d4", "enabled": true, "id": "69c15db8a432c65972c789d6", "ips": [ "1.0.0.3" ], "name": "dynamic_poor" }, { "account_id": "69c15db8a432c65972c789d4", "enabled": true, "id": "69c15db8a432c65972c789d7", "ips": [ "1.0.0.4" ], "name": "dynamic_new" } ] } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/dynamic_pools/all": { "post": { "tags": [ "Dynamic IP Pools" ], "summary": "Initialize/set IPs for all pools", "description": "Any existing IPs in dynamic IP pools will be replaced. All IPs must be dedicated IPs and\nbelong to the account. Additionally, each dynamic IP pool must contain at least 1 IP that\nis not currently warming.", "operationId": "POST-v3-dynamic-pools-all", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-dynamic_pools-all-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "good_reputation": [ "1.0.0.1", "1.0.0.2" ], "poor_reputation": [ "1.0.0.3" ], "new_senders": [ "1.0.0.4" ] } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Dynamic IP Pools" ], "summary": "Remove all dynamic IP pools", "description": "Removes all dynamic IP pools from the account. All domains on the account (and subaccounts, if any) must be removed from dynamic IP pools before the pools can be removed. Any standard dedicated IP pools will not be modified.", "operationId": "DELETE-v3-dynamic-pools-all", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/dynamic_pools/{pool_name}/{ip}": { "post": { "tags": [ "Dynamic IP Pools" ], "summary": "Add IP to Dynamic IP Pool", "description": "Adds a given IP to a Dynamic IP Pool. The IP must be dedicated and belong to the account.", "operationId": "POST-v3-dynamic-pools--pool-name---ip-", "parameters": [ { "name": "pool_name", "in": "path", "description": "The name of the Dynamic IP Pool to add the IP to (ex: dynamic_good, dynamic_poor, etc.)", "required": true, "schema": { "type": "string" } }, { "name": "ip", "in": "path", "description": "The ip to add to the given Dynamic IP Pool", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": "this is needed just so that examples are included into the output" } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/dynamic_pools/{pool_name}": { "patch": { "tags": [ "Dynamic IP Pools" ], "summary": "Update pool IPs", "description": "Adds and/or removes IPs to/from the specified dynamic IP pool.\nA given pool is required to have at least 1 IP that is not\nactively warming. Additionally, a single IP cannot be assigned to\nmultiple dynamic pools.", "operationId": "PATCH-v3-dynamic-pools--pool-name-", "parameters": [ { "name": "pool_name", "in": "path", "description": "The name of the dynamic IP pool", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PATCH-v3-dynamic_pools-pool_name-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ip_pools": { "get": { "tags": [ "IP Pools" ], "summary": "List dedicated IP pools of the account", "description": "#### Description\nLists all dedicated IP pools of the account. For each pool\nreturns its basic properties (name, description, the list of IPs)\nand indicates whether the pool is linked to any domains and\nwhether it's an inherited one.", "operationId": "GET-v3-ip-pools", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-ip_pools-list-successResponse" }, "examples": { "Example": { "value": { "ip_pools": [ { "description": "long description of the dedicated IP pool", "ips": [ "1.0.0.1", "1.0.0.2" ], "is_inherited": true, "is_linked": true, "name": "short name of the dedicated IP pool", "pool_id": "the id of the dedicated IP pool" } ], "message": "success" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "description of the error" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "IP Pools" ], "summary": "Add a new DIPP to the account", "description": "The account must have 'DIPPs' feature enabled.\n\nReturns the id of the newly created DIPP.", "operationId": "POST-v3-ip-pools", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-ip_pools-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "message": "success", "pool_id": "658041ae44842b99ee2eaa1b" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ip_pools/{pool_id}": { "get": { "tags": [ "IP Pools" ], "summary": "Get DIPP details", "description": "`is_linked` in the response indicates whether the DIPP is currently linked to any\ndomains. If it's `true`, `linked_domain` lists those domains.", "operationId": "GET-v3-ip-pools--pool-id-", "parameters": [ { "name": "pool_id", "in": "path", "description": "Id of the DIPP to get details about", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "details": { "description": "A long description of the DIPP", "ips": [ "1.2.3.4", "5.6.7.8" ], "is_linked": true, "linked_domains": [ "a.example.com", "b.example.com" ], "name": "DIPP's short name", "pool_id": "658041ae44842b99ee2eaa1b" }, "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "IP Pools" ], "summary": "Delete the DIPP", "description": "The `DIPPs` feature must be enabled for the account.\n\nIt is not allowed to delete a DIPP inherited from the parent account.\n\nIf the DIPP is delegated to subaccounts, those will also be updated.\n\nIf the replacement DIPP is specified, all domains linked to the deleted DIPP will be\nrelinked to the replacement DIPP. The latter must contain at least one IP.\n\nIf the replacement IP is specified, all domains linked to the deleted DIPP will be\nunlinked, and the replacement IP will be assigned to them. It is not allowed to\ndelete a DIPP inherited from the parent account and replace it with an IP\n(subaccounts do not explicitly manage their IPs).\n\nThe replacement IP must be a dedicated one; it can't belong to another DIPP. If a\nspecial value `shared` is used, appropriate shared IPs will be used (the account must\nbe eligible for shared IPs in this case).\n\nOmitting both replacement DIPP and replacement IP is allowed only if the DIPP being\ndeleted contains no IPs.\n\nThe processing of affected domains and subaccounts happens asynchronously after the\nendpoint returns a response.", "operationId": "DELETE-v3-ip-pools--pool-id-", "parameters": [ { "name": "pool_id", "in": "path", "description": "Id of the DIPP to delete", "required": true, "schema": { "type": "string" } }, { "name": "ip", "in": "query", "description": "Replacement IP or a special value `shared`", "required": true, "schema": { "type": "string" } }, { "name": "pool_id", "in": "query", "description": "Id of the replacement DIPP", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "allowed": { "dedicated": 1, "shared": 2 } } } } } } } }, "security": [ { "basicAuth": [] } ] }, "patch": { "tags": [ "IP Pools" ], "summary": "Edit DIPP", "description": "The account must have 'DIPPs' feature enabled.\n\nIt's not allowed to edit a DIPP inherited from the parent account.\n\nIPs being added to the DIPP must be dedicated ones and belong to the account.\n\nIf IPs of the DIPP end up modified, and the DIPP is linked to domains, the domains\nwill be updated asynchronously (after this endpoint returns response).\n\nReturns an error if the passed parameters won't result in any changes.", "operationId": "PATCH-v3-ip-pools--pool-id-", "parameters": [ { "name": "pool_id", "in": "path", "description": "Id of the DIPP to edit", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PATCH-v3-ip_pools-pool_id-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ip_pools/{pool_id}/domains": { "get": { "tags": [ "IP Pools" ], "summary": "Get domains linked to DIPP", "description": "Returns a paginated list of domains that are linked to the specified\ndedicated IP pool.", "operationId": "GET-v3-ip-pools--pool-id--domains", "parameters": [ { "name": "pool_id", "in": "path", "description": "Id of the DIPP to get details about", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The maximum number of records to return", "schema": { "type": "integer", "maximum": 500, "minimum": 10, "default": 10 } }, { "name": "page", "in": "query", "description": "Encoded page identifier retrieved from previous call", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "domains": [ { "id": "69c15db8a432c65972c789d9", "name": "example1.com" }, { "id": "69c15db8a432c65972c789da", "name": "example2.com" } ], "paging": { "first": "http://api.mailgun.net/v3/ip_pools/69c15db8a432c65972c789d8/domains?page=eyJj...", "next": "http://api.mailgun.net/v3/ip_pools/69c15db8a432c65972c789d8/domains?page=eyJj..." } } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ip_pools/{pool_id}/ips/{ip}": { "put": { "tags": [ "IP Pools" ], "summary": "Add an IP to a DIPP", "description": "The account must have 'DIPPs' feature enabled.\n\nIt is not allowed to modify a DIPP inherited from the parent account.\n\nThe IP must be a dedicated one, belong to the account and not belong to any other\nDIPP.\n\nAll domains linked to the DIPP will be updated so that their IPs include the newly\nadded address. If the DIPP is delegated to subaccounts, those will also be updated.\n\nThe processing of affected domains and subaccounts happens asynchronously after the\nendpoint returns a response.", "operationId": "PUT-v3-ip-pools--pool-id--ips--ip-", "parameters": [ { "name": "ip", "in": "path", "description": "IP to add to the DIPP", "required": true, "schema": { "type": "string" } }, { "name": "pool_id", "in": "path", "description": "Id of the DIPP to update", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "message": "started" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "IP Pools" ], "summary": "Remove an IP from a DIPP", "description": "The account must have 'DIPPs' feature enabled.\n\nIt's not allowed to edit a DIPP inherited from the parent account.\n\nIf the DIPP is linked to domains, the domains will be updated asynchronously (after\nthis endpoint returns response).", "operationId": "DELETE-v3-ip-pools--pool-id--ips--ip-", "parameters": [ { "name": "ip", "in": "path", "description": "The IP to remove", "required": true, "schema": { "type": "string" } }, { "name": "pool_id", "in": "path", "description": "The id of the DIPP", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "message": "started" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ip_pools/{pool_id}/ips.json": { "post": { "tags": [ "IP Pools" ], "summary": "Add multiple IPs to the DIPP", "description": "The account must have 'DIPPs' feature enabled.\n\nIt is not allowed to modify a DIPP inherited from the parent account.\n\nAll IPs must be dedicated ones, belong to the account and not belong to any other\nDIPP.\n\nAll domains linked to the DIPP will be updated so that their IPs include the newly\nadded addresses. If the DIPP is delegated to subaccounts, those will also be updated.\n\nThe processing of affected domains and subaccounts happens asynchronously after the\nendpoint returns a response.", "operationId": "POST-v3-ip-pools--pool-id--ips-json", "parameters": [ { "name": "pool_id", "in": "path", "description": "Id of the DIPP to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-ip_pools-add_ip-addMultipleIPsRequestBody" }, "examples": { "Example": { "value": { "ips": [ "1.2.3.4", "5.6.7.8" ] } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "message": "started" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ip_pools/{pool_id}/delegate": { "put": { "tags": [ "IP Pools" ], "summary": "Delegate DIPP to Subaccount", "description": "Delegates a dedicated IP pool (DIPP) from the parent account to a specified subaccount.\nUnlike legacy endpoints, this supports accounts with multiple delegated DIPPs.\n\nRequest parameters are encoded as form data.", "operationId": "PUT-v3-ip-pools--pool-id--delegate", "parameters": [ { "name": "pool_id", "in": "path", "description": "The ID of the dedicated IP pool to delegate", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v3-ip_pools-pool_id-delegate-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "IP Pools" ], "summary": "Revoke DIPP from Subaccount", "description": "Revokes delegation of a dedicated IP pool (DIPP) from a specified subaccount.\nThe DIPP will no longer be available to the subaccount. Unlike\nlegacy endpoints, this supports accounts with multiple delegated DIPPs.\n\nRequest parameters are encoded as form data.", "operationId": "DELETE-v3-ip-pools--pool-id--delegate", "parameters": [ { "name": "pool_id", "in": "path", "description": "The ID of the dedicated IP pool to revoke", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DELETE-v3-ip_pools-pool_id-delegate-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ip_warmups": { "get": { "tags": [ "IP Address Warmup" ], "summary": "Retrieves the list of in-flight IP address warmup statuses.", "description": "Retrieves a list of in-flight IP warmup statuses for dedicated IP addresses owned by the account. The response includes pagination URLs for navigating through the results.", "operationId": "GET-v3-ip-warmups", "parameters": [ { "name": "page", "in": "query", "description": "The page to retrieve. If not specified, the first page is returned.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The number of results to return per page. Defaults to 10 if not specified.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "items": [ { "ip": "1.0.0.1", "sent_within_stage": "0%", "throttle": 78, "stage_number": 3, "stage_start_volume": 14000, "stage_start_time": "2025-01-01T00:00:00Z", "stage_volume_limit": 4000 }, { "ip": "1.0.0.2", "sent_within_stage": "25%", "throttle": 90, "stage_number": 4, "stage_start_volume": 10000, "stage_start_time": "2025-01-01T00:00:00Z", "stage_volume_limit": 8000 } ], "paging": { "first": "first", "next": "next" } } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/ip_warmups/{addr}": { "get": { "tags": [ "IP Address Warmup" ], "summary": "Retrieves the status of an in-flight IP warmup", "description": "Retrieves the status of an in-flight IP warmup, which must be a dedicated IP owned by the account.", "operationId": "GET-v3-ip-warmups--addr-", "parameters": [ { "name": "addr", "in": "path", "description": "The IP address to retrieve the warmup status for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "details": { "sent_within_stage": "20%", "throttle": 78, "start_volume": 10000, "stage": 2, "stage_limit": 4000, "hourly_limit": 100, "stage_started_at": "2025-01-01T00:00:00Z", "hour_started_at": "2025-01-01T00:00:00Z", "plan_started_at": "2025-01-01T00:00:00Z", "plan_last_updated_at": "2025-01-01T00:00:00Z", "total_stages": 15, "stage_history": [ { "first_updated_at": "0001-01-01T00:00:00Z", "completed_at": "2025-06-03T21:33:55.000000123Z", "limit": 1000 }, { "first_updated_at": "0001-01-01T00:00:00Z", "completed_at": "2025-06-04T18:11:20.000000456Z", "limit": 2000 }, { "first_updated_at": "0001-01-01T00:00:00Z", "completed_at": "2025-06-04T14:22:17.000000789Z", "limit": 4000 } ] } } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "IP Address Warmup" ], "summary": "Creates a warmup plan for an IP Address", "description": "Creates a new warmup plan for an IP address. The IP must be dedicated and owned by the account.", "operationId": "POST-v3-ip-warmups--addr-", "parameters": [ { "name": "addr", "in": "path", "description": "The IP address to create the warmup plan for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "IP Address Warmup" ], "summary": "Cancels the warmup plan for an IP address", "description": "Cancels the warmup plan for an IP address. The IP must be dedicated and owned by the account.", "operationId": "DELETE-v3-ip-warmups--addr-", "parameters": [ { "name": "addr", "in": "path", "description": "The IP address to cancel the warmup plan for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/dynamic_pools/domains": { "get": { "tags": [ "Dynamic IP Pools" ], "summary": "List all domains assigned to dynamic IP pools", "description": "Retrieves all domains enrolled in dynamic IP pools across the parent account and subaccounts.", "operationId": "GET-v1-dynamic-pools-domains", "parameters": [ { "name": "limit", "in": "query", "description": "The maximum number of domains to return", "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "account", "in": "query", "description": "Filter domains by account ID. Can be specified multiple times.", "schema": { "type": "string" } }, { "name": "pool", "in": "query", "description": "Filter domains to a specific Dynamic IP Pool. Can be specified multiple times.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Specify which field to use to sort domains", "schema": { "type": "string", "enum": [ "bounce_rate", "complaint_rate", "name" ], "default": "name", "x-enumDescriptions": { "bounce_rate": "Sort domains by bounce rate", "complaint_rate": "Sort domains by complaint rate", "name": "Sort domains alphabetically by name" } } }, { "name": "sort_order", "in": "query", "description": "Specify which field to use to sort domains", "schema": { "type": "string", "enum": [ "ascending", "descending" ], "default": "ascending", "x-enumDescriptions": { "ascending": "Sort domains ascending by the specified sort_by field", "descending": "Sort domains descending by the specified sort_by field" } } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bandersnatch-api-DomainListResponse" }, "examples": { "Example": { "value": { "items": [ { "id": "68d16780d1ffb196ac7b2cc8", "account_id": "68d16780d1ffb196ac7b2cc9", "name": "example.com", "registered_at": "0001-01-01T00:00:00Z", "pool": "dynamic_good", "bounce_rate": 0.01, "complaint_rate": 0.1, "processed_count": 100 }, { "id": "68d16780d1ffb196ac7b2cca", "account_id": "68d16780d1ffb196ac7b2ccb", "name": "example.com", "registered_at": "0001-01-01T00:00:00Z", "pool": "dynamic_good", "bounce_rate": 0.01, "complaint_rate": 0, "processed_count": 100 } ], "total_items": 2, "paging": {} } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "description of the error" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/dynamic_pools/domains/{name}/preview": { "get": { "tags": [ "Dynamic IP Pools" ], "summary": "Preview domain assignment", "description": "Runs a health check on a domain and returns which pool it would be placed in. It does NOT enroll the domain or set the band", "operationId": "GET-v1-dynamic-pools-domains--name--preview", "parameters": [ { "name": "name", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-Response" }, "examples": { "Example": { "value": { "pool": "dynamic_poor", "results": { "bounce_rate": { "value": 0.25, "band": "dynamic_poor" }, "complaint_rate": { "value": 0.0002, "band": "dynamic_good" }, "processed_count": { "value": 25000, "band": "dynamic_good" } } } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/dynamic_pools/domains/{name}/history": { "get": { "tags": [ "Dynamic IP Pools" ], "summary": "List domain history", "description": "Retrieves a domain's history records", "operationId": "GET-v1-dynamic-pools-domains--name--history", "parameters": [ { "name": "name", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bandersnatch-model-HistoryRecord" }, "examples": { "Example": { "value": { "id": "000000000000000000000000", "owning_account_id": "000000000000000000000000", "account_id": "68d16780d1ffb196ac7b2ccd", "domain_id": "68d16780d1ffb196ac7b2ccc", "domain_name": "test.com", "new_band": "dynamic_good", "prev_band": "dynamic_poor", "reason": "Multiple metrics in good threshold", "bounce_rate": 0.2, "complaint_rate": 0.1, "processed_count": 100, "timestamp": "2025-09-22T11:13:04.740262-04:00" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/dynamic_pools/domains/{name}/override": { "put": { "tags": [ "Dynamic IP Pools" ], "summary": "Override domain assignment", "description": "Overrides a domain's dynamic IP pool assignment. A domain's pool will not be updated by health checks while an override is present.", "operationId": "PUT-v1-dynamic-pools-domains--name--override", "parameters": [ { "name": "name", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v1-dynamic_pools-domains-name-override-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-Response" }, "examples": { "Example": { "value": { "message": "success" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-InvalidParameterError" }, "examples": { "Example": { "value": { "Field": "pool", "Value": "invalid_name" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Dynamic IP Pools" ], "summary": "Remove override", "description": "Removes any dynamic IP pool override for a domain. The domain's pool assignment will be managed by health checks.", "operationId": "DELETE-v1-dynamic-pools-domains--name--override", "parameters": [ { "name": "name", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-Response" }, "examples": { "Example": { "value": { "message": "success" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/dynamic_pools/history": { "get": { "tags": [ "Dynamic IP Pools" ], "summary": "List account history", "description": "Retrieve history records for all domains assigned to Dynamic IP Pools across the parent and subaccounts.", "operationId": "GET-v1-dynamic-pools-history", "parameters": [ { "name": "Limit", "in": "query", "description": "The maximum number of events to return", "schema": { "type": "integer", "maximum": 100, "minimum": 1 } }, { "name": "include_subaccounts", "in": "query", "description": "If true, includes events from all subaccounts in addition to events from the parent account", "schema": { "type": "boolean" } }, { "name": "domain", "in": "query", "description": "Filter events by domain name", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Filter events emitted before a given timestamp (Format: Mon, 02 Jan 2006 15:04:05 MST)", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Filter events emitted after a given timestamp (Format: Mon, 02 Jan 2006 15:04:05 MST)", "schema": { "type": "string" } }, { "name": "moved_to", "in": "query", "description": "Filter events by which Dynamic Pool a domain was moved to (ex. dynamic_good, dynamic_poor, etc.)", "schema": { "type": "string" } }, { "name": "moved_from", "in": "query", "description": "Filter events by which Dynamic Pool a domain was moved from (ex. dynamic_good, dynamic_poor, etc.)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bandersnatch-api-ListHistoryResponse" }, "examples": { "Example": { "value": { "items": [ { "id": "68d16780d1ffb196ac7b2cce", "owning_account_id": "000000000000000000000000", "account_id": "68d16780d1ffb196ac7b2ccf", "account_name": "My Account", "domain_id": "68d16780d1ffb196ac7b2cd0", "domain_name": "test.com", "new_band": "dynamic_good", "prev_band": "dynamic_poor", "reason": "bounce_rate in good threshold", "bounce_rate": 0.04, "complaint_rate": 0.0001, "initiated_by": "system", "timestamp": "0001-01-01T00:00:00Z" }, { "id": "68d16780d1ffb196ac7b2cd1", "owning_account_id": "000000000000000000000000", "account_id": "68d16780d1ffb196ac7b2cd2", "account_name": "My Account", "domain_id": "68d16780d1ffb196ac7b2cd3", "domain_name": "test.com", "new_band": "dynamic_good", "prev_band": "dynamic_new", "reason": "Multiple metrics in good threshold", "bounce_rate": 0.04, "complaint_rate": 0.0001, "initiated_by": "system", "timestamp": "0001-01-01T00:00:00Z" } ], "total_items": 2, "paging": {} } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "description of the error" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/envelopes": { "delete": { "tags": [ "Messages" ], "summary": "Delete scheduled and undelivered mail", "description": "Deletes all scheduled and undelivered mail from the domain queue. This endpoint must be called on the same storage API host as the mail's generated storage URL. e.g. https://storage-us-east4.api.mailgun.net/v3/example.com/envelopes\n\nThe storage hosts are: `storage-us-east4.api.mailgun.net`, `storage-us-west1.api.mailgun.net`, and `storage-europe-west1.api.mailgun.net`.", "operationId": "DELETE-v3--domain-name--envelopes", "parameters": [ { "name": "domain_name", "in": "path", "description": "The name of the domain you want to delete envelope from", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "done" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid private key" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "domain not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/x509/{domain}/status": { "get": { "tags": [ "Domain Tracking" ], "summary": "Tracking Certificate: Get certificate and status", "description": "Get x509 TLS certificate and status", "operationId": "GET-v2-x509--domain--status", "parameters": [ { "name": "domain", "in": "path", "description": "The tracking domain of the TLS certificate, formatted as `web_prefix.domain_name` (`web_prefix` is configured in your domains settings)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-terminator-httpapi-StatusResponse" }, "examples": { "Processing": { "value": { "status": "processing", "error": "Waiting for x509 key pair generation" } }, "Active": { "value": { "status": "active", "certificate": "{CERT}" } }, "Expired": { "value": { "status": "expired", "error": "x509 certificate has expired", "certificate": "{CERT}" } }, "Error": { "value": { "status": "error", "error": "TLS x509 key pair generation failed, please contact support", "certificate": "{CERT}" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError" }, "examples": { "Example": { "value": { "Description": "Please initiate x509 key pair generation at POST /v2/x509/{domain}" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/x509/{domain}": { "put": { "tags": [ "Domain Tracking" ], "summary": "Tracking Certificate: Regenerate expired certificate", "description": "Initiates regeneration of an expired TLS certificate for the tracking domain in a background task. Once generation is enqueued, you may poll status endpoint in location field to check for success. This will not regenerate an existing certificate that is still valid", "operationId": "PUT-v2-x509--domain-", "parameters": [ { "name": "domain", "in": "path", "description": "The tracking domain of the TLS certificate, formatted as webPrefix.domainName from domains settings", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "A 202 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-terminator-httpapi-GenerateResponse" }, "examples": { "Example": { "value": { "message": "Initiated x509 key pair generation", "location": "/v2/x509/example.com/status" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Reason": "invalid CNAME record" } } } } } }, "402": { "description": "A 402 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Reason": "upgrade your account to enable this feature" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError" }, "examples": { "Example": { "value": { "Description": "x509 cert not found" } } } } } }, "409": { "description": "A 409 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-ConflictError" }, "examples": { "Example": { "value": { "Description": "x509 certificate is still valid until 2009-11-10 23:00:00 +0000 UTC" } } } } } }, "429": { "description": "A 429 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-ConflictError" }, "examples": { "Example": { "value": { "Description": "x509 key pair generation job is already in progress for example.com" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Domain Tracking" ], "summary": "Tracking Certificate: Generate", "description": "Initiates generation of a TLS certificate for the tracking domain in a background task. Once generation is enqueued, you may poll the status endpoint in `location` field to check for success", "operationId": "POST-v2-x509--domain-", "parameters": [ { "name": "domain", "in": "path", "description": "The tracking domain of the TLS certificate, formatted as webPrefix.domainName from domains settings", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "A 202 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-terminator-httpapi-GenerateResponse" }, "examples": { "Example": { "value": { "message": "Initiated x509 key pair generation", "location": "/v2/x509/example.com/status" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Reason": "invalid CNAME record" } } } } } }, "402": { "description": "A 402 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError" }, "examples": { "Example": { "value": { "Reason": "upgrade your account to enable this feature" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError" }, "examples": { "Example": { "value": { "Description": "x509 cert not found" } } } } } }, "409": { "description": "A 409 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-ConflictError" }, "examples": { "Example": { "value": { "Description": "x509 key pair generation has already been initiated for example.com" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/events": { "get": { "tags": [ "Events" ], "summary": "Retrieves a paginated list of events", "description": "Mailgun tracks every inbound and outbound message event and retains this data for at least 3 days.\nSee [Filter expression](https://documentation.mailgun.com/docs/mailgun/user-manual/events/#filter-expression) for details about filtering expressions\n", "operationId": "get-v3-domain_name-events", "parameters": [ { "name": "begin", "in": "query", "description": "The beginning of the search time range in epoch seconds", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "The end of the search time range in epoch seconds", "schema": { "type": "string" } }, { "name": "ascending", "in": "query", "description": "Sort direction by time. Must be provided if the range end time is not specified. Can be either yes or no", "schema": { "type": "string", "enum": [ "yes", "no" ], "x-enumDescriptions": { "yes": "Sort by ascending time", "no": "Do not sort" } } }, { "name": "limit", "in": "query", "description": "The number of entries to return (300 max)", "schema": { "type": "integer", "maximum": 300 } }, { "name": "event", "in": "query", "description": "Filter by event type", "schema": { "type": "string" } }, { "name": "list", "in": "query", "description": "Filter by mailing list email address that message was originally sent to", "schema": { "type": "string" } }, { "name": "attachment", "in": "query", "description": "Filter by the name of an attached file", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Filter by email address mentioned in the From MIME header", "schema": { "type": "string" } }, { "name": "message-id", "in": "query", "description": "Filter by Mailgun message id returned by the messages API", "schema": { "type": "string" } }, { "name": "subject", "in": "query", "description": "Filter by subject line", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Filter by email address mentioned in the To MIME header", "schema": { "type": "string" } }, { "name": "size", "in": "query", "description": "Filter by message size. Mostly intended to be used with range filtering expressions", "schema": { "type": "string" } }, { "name": "recipient", "in": "query", "description": "Filter by email address of a recipient. While messages are addressable to one or more recipients, each event (with one exception) tracks one recipient. See stored events for use of recipients", "schema": { "type": "string" } }, { "name": "recipients", "in": "query", "description": "Specific to stored events, this field tracks all of the potential message recipients.", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "Filter by user defined tags", "schema": { "type": "string" } }, { "name": "severity", "in": "query", "description": "Filter by event severity, if exists. Currently for failed events only. See [Tracking Failures](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/#tracking-failures)", "schema": { "$ref": "#/components/schemas/EventSeverityType" } }, { "name": "domain_name", "in": "path", "description": "Filter by sending domain", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EventResponse" } }, "paging": { "type": "object", "properties": { "next": { "type": "string" }, "previous": { "type": "string" } } } } }, "examples": { "Rejected": { "value": { "items": [ { "event": "rejected", "id": "OMTXD3-sSmKIQa1gSKkYVA", "timestamp": 1529704976.104692, "log-level": "warn", "flags": { "is-test-mode": false }, "reject": { "reason": "Sandbox subdomains are for test purposes only. Please add your own domain or add the address to authorized recipients in Account Settings.", "description": "" }, "message": { "headers": { "to": "joan@example.org", "message-id": "20180622220256.1.B31A451A2E5422BB@sandbox55887fac92de874df5ae0023b75fd62f1d.mailgun.org", "from": "john@sandbox55887fac92de874df5ae0023b75fd62f1d.mailgun.org", "subject": "Test Subject" }, "attachments": [], "size": 867 }, "tags": [], "user-variables": {} } ], "paging": { "next": "https://api.mailgun.net/v3/samples.mailgun.org/events/W3siY...", "previous": "https://api.mailgun.net/v3/samples.mailgun.org/events/Lkawm..." } } }, "Stored": { "value": { "items": [ { "event": "stored", "id": "WRVmVc47QYi4DHth_xpRUA", "timestamp": 1529692198.691758, "log-level": "info", "flags": { "is-test-mode": false }, "message": { "headers": { "to": "team@example.org", "message-id": "20180622182958.1.48906CB188F1A454@exmple.org", "from": "sender@example.org", "subject": "Test Subject" }, "attachments": [], "recipients": [ "team@example.org" ], "size": 586 }, "storage": { "url": "https://se.api.mailgun.net/v3/domains/example.org/messages/eyJwI...", "key": "eyJwI..." }, "tags": [], "user-variables": {} } ], "paging": { "next": "https://api.mailgun.net/v3/samples.mailgun.org/events/W3siY...", "previous": "https://api.mailgun.net/v3/samples.mailgun.org/events/Lkawm..." } } }, "Complained": { "value": { "items": [ { "event": "complained", "id": "ncV2XwymRUKbPek_MIM-Gw", "timestamp": 1377214260.049634, "log-level": "warn", "recipient": "foo@example.com", "tags": [], "user-variables": {}, "flags": { "is-test-mode": false }, "message": { "headers": { "to": "foo@example.com", "message-id": "20130718032413.263EE2E0926@example.com", "from": "John Doe ", "subject": "This is the subject." }, "attachments": [], "size": 18937 } } ], "paging": { "next": "https://api.mailgun.net/v3/samples.mailgun.org/events/W3siY...", "previous": "https://api.mailgun.net/v3/samples.mailgun.org/events/Lkawm..." } } }, "Unsubscribed": { "value": { "items": [ { "event": "unsubscribed", "id": "W3X4JOhFT-OZidZGKKr9iA", "timestamp": 1377213791.421473, "log-level": "info", "recipient": "recipient@example.com", "geolocation": { "country": "US", "region": "TX", "city": "San Antonio" }, "tags": [], "user-variables": {}, "ip": "23.23.23.345", "client-info": { "client-type": "browser", "client-os": "OS X", "device-type": "desktop", "client-name": "Chrome", "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.95 Safari/537.36" }, "message": { "headers": { "message-id": "20130822232216.13966.79700@samples.mailgun.org" } } } ], "paging": { "next": "https://api.mailgun.net/v3/samples.mailgun.org/events/W3siY...", "previous": "https://api.mailgun.net/v3/samples.mailgun.org/events/Lkawm..." } } }, "Clicked": { "value": { "items": [ { "event": "clicked", "id": "G5zMz2ysS6OxZ2C8xb2Tqg", "timestamp": 1377075564.094891, "log-level": "info", "recipient": "recipient@example.com", "geolocation": { "country": "US", "region": "TX", "city": "Austin" }, "tags": [], "url": "http://example.com/signup", "recipient-provider": "Gmail", "ip": "123.123.123.321", "user-variables": {}, "client-info": { "client-type": "browser", "client-os": "Linux", "device-type": "desktop", "client-name": "Chromium", "user-agent": "Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.36 (KHTML, like Gecko) Ubuntu Chromium/28.0.1500.71 Chrome/28.0.1500.71 Safari/537.36", "bot": "" }, "message": { "headers": { "message-id": "20130821085807.30688.67706@samples.mailgun.org" } } } ], "paging": { "next": "https://api.mailgun.net/v3/samples.mailgun.org/events/W3siY...", "previous": "https://api.mailgun.net/v3/samples.mailgun.org/events/Lkawm..." } } }, "Opened": { "value": { "items": [ { "event": "opened", "id": "-laxIqj9QWubsjY_3pTq_g", "timestamp": 1377047343.042277, "log-level": "info", "recipient": "recipient@example.com", "recipient-provider": "Gmail", "geolocation": { "country": "US", "region": "Texas", "city": "Austin" }, "tags": [], "user-variables": {}, "ip": "111.111.111.111", "client-info": { "client-type": "mobile browser", "client-os": "iOS", "device-type": "mobile", "client-name": "Mobile Safari", "user-agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Mobile/10B143", "bot": "" }, "message": { "headers": { "message-id": "20130821005614.19826.35976@samples.mailgun.org" } } } ], "paging": { "next": "https://api.mailgun.net/v3/samples.mailgun.org/events/W3siY...", "previous": "https://api.mailgun.net/v3/samples.mailgun.org/events/Lkawm..." } } }, "Failed": { "value": { "items": [ { "event": "failed", "id": "pl271FzxTTmGRW8Uj3dUWw", "timestamp": 1529701969.818328, "log-level": "error", "severity": "permanent", "reason": "suppress-bounce", "envelope": { "sender": "john@example.org", "transport": "smtp", "targets": "joan@example.com" }, "flags": { "is-routed": false, "is-authenticated": true, "is-system-test": false, "is-test-mode": false }, "delivery-status": { "attempt-no": 1, "message": "", "code": 605, "description": "Not delivering to previously bounced address", "session-seconds": 0 }, "message": { "headers": { "to": "joan@example.com", "message-id": "20180622211249.1.2A6098970A380E12@example.org", "from": "john@example.org", "subject": "Test Subject" }, "attachments": [], "size": 867 }, "storage": { "url": "https://se.api.mailgun.net/v3/domains/example.org/messages/eyJwI...", "key": "eyJwI..." }, "recipient": "slava@mailgun.com", "recipient-domain": "mailgun.com", "recipient-provider": "Gmail", "tags": [], "user-variables": {} } ], "paging": { "next": "https://api.mailgun.net/v3/samples.mailgun.org/events/W3siY...", "previous": "https://api.mailgun.net/v3/samples.mailgun.org/events/Lkawm..." } } }, "Delivered": { "value": { "items": [ { "event": "delivered", "id": "hK7mQVt1QtqRiOfQXta4sw", "timestamp": 1529692199.626182, "log-level": "info", "envelope": { "transport": "smtp", "sender": "sender@example.org", "sending-ip": "123.123.123.123", "targets": "john@example.com" }, "flags": { "is-routed": false, "is-authenticated": false, "is-system-test": false, "is-test-mode": false }, "delivery-status": { "tls": true, "mx-host": "aspmx.l.example.com", "code": 250, "description": "", "session-seconds": 0.4367079734802246, "utf8": true, "attempt-no": 1, "message": "OK", "certificate-verified": true }, "message": { "headers": { "to": "team@example.org", "message-id": "20180622182958.1.48906CB188F1A454@exmple.org", "from": "sender@exmple.org", "subject": "Test Subject" }, "attachments": [], "size": 586 }, "storage": { "url": "https://storage-us-west1.api.mailgun.net/v3/domains/...", "region": "us-west1", "key": "AwABB...", "env": "production" }, "recipient": "john@example.com", "recipient-domain": "example.com", "recipient-provider": "Gmail", "tags": [], "user-variables": {} } ], "paging": { "next": "https://api.mailgun.net/v3/samples.mailgun.org/events/W3siY...", "previous": "https://api.mailgun.net/v3/samples.mailgun.org/events/Lkawm..." } } }, "Accepted": { "value": { "items": [ { "event": "accepted", "id": "jxVuhYlhReaK3QsggHfFRA", "timestamp": 1529692198.641821, "log-level": "info", "method": "smtp", "envelope": { "targets": "team@example.org", "transport": "smtp", "sender": "sender@example.org" }, "flags": { "is-authenticated": false }, "message": { "headers": { "to": "team@example.org", "message-id": "20180622182958.1.48906CB188F1A454@exmple.org", "from": "sender@example.org", "subject": "Test Subject" }, "attachments": [], "recipients": [ "team@example.org" ], "size": 586 }, "storage": { "url": "https://se.api.mailgun.net/v3/domains/example.org/messages/eyJwI...", "key": "eyJwI..." }, "recipient": "team@example.org", "recipient-domain": "example.org", "tags": [], "user-variables": {} } ], "paging": { "next": "https://api.mailgun.net/v3/samples.mailgun.org/events/W3siY...", "previous": "https://api.mailgun.net/v3/samples.mailgun.org/events/Lkawm..." } } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain}/tags": { "get": { "tags": [ "Tags" ], "summary": "List all tags", "description": "List all tags associated with a domain", "operationId": "GET-v3--domain--tags", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "The page direction based on the tag parameter; valid choices are (first, last, next, prev)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limits the number of items returned in a request", "schema": { "type": "integer" } }, { "name": "tag", "in": "query", "description": "The tag that marks the end of the current page and the start of the next", "schema": { "type": "string" } }, { "name": "prefix", "in": "query", "description": "List only tags that begin with this prefix", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-TagListResponse" }, "examples": { "Example": { "value": { "items": [ { "tag": "my-tag-1", "description": "Optional description", "first-seen": "2023-01-02 02:14:27 +0000 UTC", "last-seen": "2023-09-06 18:45:51 +0000 UTC" }, { "tag": "my-tag-2", "description": "Optional description", "first-seen": "2023-01-02 02:14:27 +0000 UTC", "last-seen": "2023-09-06 18:45:51 +0000 UTC" } ], "paging": { "previous": "https://api.mailgun.net/v3/example.com/tags?limit=1000&page=prev&tag=", "first": "https://api.mailgun.net/v3/example.com/tags?limit=1000&page=first&tag=", "next": "https://api.mailgun.net/v3/example.com/tags?limit=1000&page=next&tag=", "last": "https://api.mailgun.net/v3/example.com/tags?limit=1000&page=last&tag=" } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain}/tag": { "get": { "tags": [ "Tags" ], "summary": "Get a tag", "description": "Get a tag associated with a domain", "operationId": "GET-v3--domain--tag", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "The name of the tag", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-tags-TagItem" }, "examples": { "Example": { "value": { "tag": "my-tag-1", "description": "Optional description", "first-seen": "2023-01-02 02:14:27 +0000 UTC", "last-seen": "2023-09-06 18:45:51 +0000 UTC" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Tags" ], "summary": "Update tag ", "description": "Update a tag associated with a domain", "operationId": "PUT-v3--domain--tag", "parameters": [ { "name": "domain", "in": "path", "description": "The domain id", "required": true, "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "The name of the tag", "required": true, "schema": { "type": "string" } }, { "name": "description", "in": "query", "description": "The description of the tag", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Tag updated" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Tags" ], "summary": "Delete tag", "description": "Delete a tag associated with a domain", "operationId": "DELETE-v3--domain--tag", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "The name of the tag", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Tag deleted" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain}/tag/stats/aggregates": { "get": { "tags": [ "Tags" ], "summary": "Get aggregate stat types by tag", "description": "Returns a list for a given domain for different event types", "operationId": "GET-v3--domain--tag-stats-aggregates", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "The name of the tag", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "The type of aggregate (country, device, provider)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-TagAggregateResponse" }, "examples": { "Example": { "value": { "tag": "tag1", "provider": { "aol.com": { "accepted": 0, "clicked": 1, "opened": 1, "unique_clicked": 1, "unsubscribed": 0 }, "gmail.com": { "accepted": 0, "clicked": 2, "opened": 1, "unique_clicked": 1, "unsubscribed": 0 } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain}/tag/stats": { "get": { "tags": [ "Tags" ], "summary": "Get stats by tag", "description": "Retrieve stats by tag", "operationId": "GET-v3--domain--tag-stats", "parameters": [ { "name": "domain", "in": "path", "description": "The domain id", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "The start date in RFC 2822 format or unix epoch (default: 7 days ago)", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "The end date in RFC 2822 format or unix epoch (default: current time) ", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "The gregorian resolution the query is for 'day, month, hour` (default: day)", "schema": { "type": "string" } }, { "name": "duration", "in": "query", "description": "If duration is provided than it's calculated from the 'end' date and overwrites the 'start' date", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "description": "The provider value; see `GET /v3/domains/1/tag/providers` for possible values", "schema": { "type": "string" } }, { "name": "device", "in": "query", "description": "The device value; see `GET /v3/domains/1/tag/devices` for possible values", "schema": { "type": "string" } }, { "name": "country", "in": "query", "description": "The country value; see `GET /v3/domains/1/tag/providers` for possible values", "schema": { "type": "string" } }, { "name": "event", "in": "query", "description": "Name of the event(s) to receive the stats for (Multiple events are allowed). Supported events are: accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored", "required": true, "schema": { "type": "string" } }, { "name": "tag", "in": "query", "description": "The name of the tag", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-StatsResponse" }, "examples": { "Example": { "value": { "tag": "tag1", "description": "Optional Description", "start": "Tue, 14 Feb 2012 00:00:00 UTC", "end": "Fri, 01 Apr 2012 00:00:00 UTC", "resolution": "month", "stats": [ { "time": "Fri, 01 Apr 2012 00:00:00 UTC", "accepted": { "incoming": 2, "outgoing": 1, "total": 3 }, "delivered": { "smtp": 15, "http": 10, "optimized": 5, "total": 20 }, "opened": { "total": 20, "unique": 1 }, "clicked": { "total": 1, "unique": 1 } } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{domain}/tag/devices": { "get": { "summary": "List of supported devices", "description": "Gets a list of devices scout currently supports", "operationId": "GET-v3-domains--domain--tag-devices", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-StatTypesResponse" }, "examples": { "Example": { "value": { "items": [ "desktop", "mobile", "tablet", "unknown" ] } } } } } } }, "deprecated": true, "tags": [ "openapi-scout_other" ], "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{domain}/tag/providers": { "get": { "summary": "List of supported providers", "description": "Gets a list of providers scout currently supports", "operationId": "GET-v3-domains--domain--tag-providers", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-StatTypesResponse" }, "examples": { "Example": { "value": { "items": [ "gmail.com", "yahoo.com", "hotmail.com", "aol.com", "icloud.com", "mail.ru", "comcast.net", "outlook.com", "msn.com", "live.com", "orange.fr", "sbcglobal.net", "att.net", "ymail.com", "hotmail.co.uk", "verizon.net", "bellsouth.net", "me.com", "yandex.ru", "seznam.cz", "yahoo.co.uk", "hotmail.fr", "yahoo.com.tw", "rocketmail.com", "mailinator.com", "qq.com" ] } } } } } } }, "deprecated": true, "tags": [ "openapi-scout_other" ], "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{domain}/tag/countries": { "get": { "summary": "List of supported country codes", "description": "Gets a list of country codes scout curently supports", "operationId": "GET-v3-domains--domain--tag-countries", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-StatTypesResponse" } } } } }, "deprecated": true, "tags": [ "openapi-scout_other" ], "security": [ { "basicAuth": [] } ] } }, "/v3/stats/total": { "get": { "tags": [ "Stats" ], "summary": "Totals for entire account", "description": "Gets stat totals for an entire account", "operationId": "GET-v3-stats-total", "parameters": [ { "name": "start", "in": "query", "description": "The start date in RFC 2822 format or unix epoch (default: 7 days ago)", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "The end date in RFC 2822 format or unix epoch (default: current time) ", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "The gregorian resolution the query is for 'day, month, hour` (default: day)", "schema": { "type": "string" } }, { "name": "duration", "in": "query", "description": "If duration is provided than it's calculated from the 'end' date and overwrites the 'start' date", "schema": { "type": "string" } }, { "name": "event", "in": "query", "description": "Name of the event(s) to receive the stats for (Multiple events are allowed). Supported events are: accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-StatsResponse" }, "examples": { "Example": { "value": { "description": "Optional Description", "start": "Tue, 14 Feb 2012 00:00:00 UTC", "end": "Fri, 01 Apr 2012 00:00:00 UTC", "resolution": "month", "stats": [ { "time": "Fri, 01 Apr 2012 00:00:00 UTC", "accepted": { "incoming": 2, "outgoing": 1, "total": 3 }, "delivered": { "smtp": 15, "http": 10, "optimized": 5, "total": 20 }, "opened": { "total": 20, "unique": 1 }, "clicked": { "total": 1, "unique": 1 } } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain}/stats/total": { "get": { "tags": [ "Stats" ], "summary": "Totals for entire domain", "description": "Gets stat totals for an entire domain", "operationId": "GET-v3--domain--stats-total", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "The start date in RFC 2822 format or unix epoch (default: 7 days ago)", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "The end date in RFC 2822 format or unix epoch (default: current time) ", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "The gregorian resolution the query is for 'day, month, hour` (default: day)", "schema": { "type": "string" } }, { "name": "duration", "in": "query", "description": "If duration is provided than it's calculated from the 'end' date and overwrites the 'start' date", "schema": { "type": "string" } }, { "name": "event", "in": "query", "description": "Name of the event(s) to receive the stats for (Multiple events are allowed). Supported events are: accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-StatsResponse" }, "examples": { "Example": { "value": { "description": "Optional Description", "start": "Tue, 14 Feb 2012 00:00:00 UTC", "end": "Fri, 01 Apr 2012 00:00:00 UTC", "resolution": "month", "stats": [ { "time": "Fri, 01 Apr 2012 00:00:00 UTC", "accepted": { "incoming": 2, "outgoing": 1, "total": 3 }, "delivered": { "smtp": 15, "http": 10, "optimized": 5, "total": 20 }, "opened": { "total": 20, "unique": 1 }, "clicked": { "total": 1, "unique": 1 } } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/stats/total/domains": { "get": { "tags": [ "Stats" ], "summary": "Totals for account domains for a single time resolution", "description": "Gets stat totals for domains in an account for a single time resolution", "operationId": "GET-v3-stats-total-domains", "parameters": [ { "name": "event", "in": "query", "description": "Name of the event(s) to receive the stats for (Multiple events are allowed). Supported events are: accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Skip x number of domains; used to page through large numbers of domains", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "The gregorian resolution the query is for 'day, month, hour` (default: day)", "schema": { "type": "string" } }, { "name": "timestamp", "in": "query", "description": "The date/time of the 'resolution' we are retrieving", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-StatsResponse" }, "examples": { "Example": { "value": { "description": "Optional Description", "start": "Tue, 14 Feb 2012 00:00:00 UTC", "end": "Fri, 01 Apr 2012 00:00:00 UTC", "resolution": "month", "stats": [ { "time": "Fri, 01 Apr 2012 00:00:00 UTC", "accepted": { "incoming": 2, "outgoing": 1, "total": 3 }, "delivered": { "smtp": 15, "http": 10, "optimized": 5, "total": 20 }, "opened": { "total": 20, "unique": 1 }, "clicked": { "total": 1, "unique": 1 } } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/stats/filter": { "get": { "tags": [ "Stats" ], "summary": "Filtered/grouped totals for entire account", "description": "Gets filtered and group stat totals for an entire account", "operationId": "GET-v3-stats-filter", "parameters": [ { "name": "start", "in": "query", "description": "The start date in RFC 2822 format or unix epoch (default: 7 days ago)", "schema": { "type": "string" } }, { "name": "end", "in": "query", "description": "The end date in RFC 2822 format or unix epoch (default: current time) ", "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "The gregorian resolution the query is for 'day, month, hour` (default: day)", "schema": { "type": "string" } }, { "name": "duration", "in": "query", "description": "If duration is provided than it's calculated from the 'end' date and overwrites the 'start' date", "schema": { "type": "string" } }, { "name": "event", "in": "query", "description": "Name of the event(s) to receive the stats for (Multiple events are allowed). Supported events are: accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored", "required": true, "schema": { "type": "string" } }, { "name": "filter", "in": "query", "description": "A filter for account level metrics such as filter=domain:my.example.com", "schema": { "type": "string" } }, { "name": "group", "in": "query", "description": "The key to group metrics by. Must be one of total, time, day, month, domain, ip, provider, tag, country", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-StatsResponse" }, "examples": { "Example": { "value": { "description": "Optional Description", "start": "Tue, 14 Feb 2012 00:00:00 UTC", "end": "Fri, 01 Apr 2012 00:00:00 UTC", "resolution": "month", "stats": [ { "time": "Fri, 01 Apr 2012 00:00:00 UTC", "accepted": { "incoming": 2, "outgoing": 1, "total": 3 }, "delivered": { "smtp": 15, "http": 10, "optimized": 5, "total": 20 }, "opened": { "total": 20, "unique": 1 }, "clicked": { "total": 1, "unique": 1 } } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{domain}/limits/tag": { "get": { "tags": [ "Tags" ], "summary": "Get tag limits", "description": "Get tag limits by domain", "operationId": "GET-v3-domains--domain--limits-tag", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-types-TagLimitItem" }, "examples": { "Example": { "value": { "limit": 20000, "count": 1500 } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain}/aggregates/providers": { "get": { "tags": [ "Stats" ], "summary": "Aggregate counts by ESP", "description": "Gets aggregate counts by email service provider", "operationId": "GET-v3--domain--aggregates-providers", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-ProvidersAggregateResponse" }, "examples": { "Example": { "value": { "providers": { "aol.com": { "accepted": 0, "clicked": 1, "opened": 1, "unique_clicked": 1, "unsubscribed": 0 }, "gmail.com": { "accepted": 0, "clicked": 2, "opened": 1, "unique_clicked": 1, "unsubscribed": 0 } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain}/aggregates/devices": { "get": { "tags": [ "Stats" ], "summary": "Aggregate counts by devices triggering events ", "description": "Gets aggregate counts on devices that triggered events ('tablet', 'phone', 'pc', etc…)", "operationId": "GET-v3--domain--aggregates-devices", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-DevicesAggregateResponse" }, "examples": { "Example": { "value": { "devices": { "desktop": { "accepted": 0, "clicked": 1, "opened": 1, "unique_clicked": 1, "unsubscribed": 0 }, "mobile": { "accepted": 0, "clicked": 2, "opened": 1, "unique_clicked": 1, "unsubscribed": 0 }, "tablet": { "accepted": 0, "clicked": 2, "opened": 1, "unique_clicked": 1, "unsubscribed": 0 }, "unknown": { "accepted": 0, "clicked": 2, "opened": 1, "unique_clicked": 1, "unsubscribed": 0 } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain}/aggregates/countries": { "get": { "tags": [ "Stats" ], "summary": "Aggregate counts by country", "description": "Gets aggregate counts by country (USA, RUS, etc…)", "operationId": "GET-v3--domain--aggregates-countries", "parameters": [ { "name": "domain", "in": "path", "description": "The domain name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scout-api-CountriesAggregateResponse" }, "examples": { "Example": { "value": { "countries": { "ru": { "accepted": 0, "clicked": 2, "opened": 1, "unique_clicked": 1, "unsubscribed": 0 }, "us": { "accepted": 0, "clicked": 1, "opened": 1, "unique_clicked": 1, "unsubscribed": 0 } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v1/analytics/metrics": { "post": { "tags": [ "Metrics" ], "summary": "Query account metrics", "description": "Queries filtered metrics for an account", "operationId": "POST-v1-analytics-metrics", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-Query" }, "examples": { "Example": { "value": { "start": "Mon, 13 Nov 2023 20:56:50 -0600", "end": "Wed, 20 Dec 2023 20:56:50 -0600", "resolution": "month", "duration": "1m", "dimensions": [ "time" ], "metrics": [ "accepted_count", "delivered_count", "clicked_rate", "opened_rate" ], "filter": { "AND": [ { "attribute": "domain", "comparator": "=", "values": [ { "label": "example.com", "value": "example.com" } ] } ] }, "include_subaccounts": true, "include_aggregates": true } } } }, "none": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": {} } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-analytics-internal-api-RegularMetricsResponse" }, "examples": { "Example": { "value": { "start": "Mon, 13 Nov 2023 20:56:50 -0600", "end": "Wed, 20 Dec 2023 20:56:50 -0600", "resolution": "month", "duration": "1m", "pagination": { "sort": "timestamp:asc", "skip": 1, "limit": 10, "total": 1000 }, "items": [ { "dimensions": [ { "dimension": "time", "value": "Wed, 01 Nov 2023 00:00:00 +0000", "display_value": "Wed, 01 Nov 2023 00:00:00 +0000" } ], "metrics": { "accepted_incoming_count": 10, "accepted_outgoing_count": 30, "accepted_count": 40, "delivered_smtp_count": 40, "delivered_http_count": 20, "delivered_optimized_count": 0, "delivered_count": 60, "opened_count": 55, "clicked_count": 50, "clicked_rate": "0.8300" } }, { "dimensions": [ { "dimension": "time", "value": "Fri, 01 Dec 2023 00:00:00 +0000", "display_value": "Fri, 01 Dec 2023 00:00:00 +0000" } ], "metrics": { "accepted_incoming_count": 10, "accepted_outgoing_count": 30, "accepted_count": 40, "delivered_smtp_count": 40, "delivered_http_count": 20, "delivered_optimized_count": 0, "delivered_count": 60, "opened_count": 55, "clicked_count": 50, "clicked_rate": "0.8300" } } ], "aggregates": { "metrics": {} } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/analytics/usage/metrics": { "post": { "tags": [ "Metrics" ], "summary": "Query account usage metrics", "description": "Queries filtered usage metrics for an account", "operationId": "POST-v1-analytics-usage-metrics", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-UsageQuery" }, "examples": { "Example": { "value": { "start": "Mon, 13 Nov 2023 20:56:50 -0600", "end": "Wed, 20 Dec 2023 20:56:50 -0600", "resolution": "month", "duration": "1m", "dimensions": [ "time" ], "metrics": [ "accessibility_count", "accessibility_failed_count", "archived_count", "domain_blocklist_monitoring_count", "email_preview_count", "email_preview_failed_count", "email_validation_bulk_count", "email_validation_count", "email_validation_list_count", "email_validation_mailgun_count", "email_validation_mailjet_count", "email_validation_public_count", "email_validation_single_count", "email_validation_valid_count", "image_validation_count", "image_validation_failed_count", "ip_blocklist_monitoring_count", "link_validation_count", "link_validation_failed_count", "processed_count", "seed_test_count" ], "filter": { "AND": [ { "attribute": "subaccount", "comparator": "=", "values": [ { "label": "12345", "value": "12345" } ] } ] }, "include_subaccounts": true, "include_aggregates": true } } } }, "none": { "schema": { "$ref": "#/components/schemas/string" }, "examples": { "Example": {} } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-analytics-internal-api-UsageMetricsResponse" }, "examples": { "Example": { "value": { "start": "Mon, 13 Nov 2023 20:56:50 -0600", "end": "Wed, 20 Dec 2023 20:56:50 -0600", "resolution": "month", "duration": "1m", "pagination": { "sort": "timestamp:asc", "skip": 1, "limit": 10, "total": 1000 }, "items": [ { "dimensions": [ { "dimension": "time", "value": "Wed, 01 Nov 2023 00:00:00 +0000", "display_value": "Wed, 01 Nov 2023 00:00:00 +0000" } ], "metrics": { "processed_count": 3, "email_validation_count": 50, "email_validation_public_count": 55, "email_validation_valid_count": 10, "email_validation_single_count": 30, "email_validation_bulk_count": 40, "email_validation_list_count": 20, "email_validation_mailgun_count": 40, "email_validation_mailjet_count": 5, "email_preview_count": 60, "email_preview_failed_count": 16, "link_validation_count": 5, "link_validation_failed_count": 7, "seed_test_count": 9, "ip_blocklist_monitoring_count": 42, "domain_blocklist_monitoring_count": 1001 } }, { "dimensions": [ { "dimension": "time", "value": "Fri, 01 Dec 2023 00:00:00 +0000", "display_value": "Fri, 01 Dec 2023 00:00:00 +0000" } ], "metrics": { "processed_count": 3, "email_validation_count": 50, "email_validation_public_count": 55, "email_validation_valid_count": 10, "email_validation_single_count": 30, "email_validation_bulk_count": 40, "email_validation_list_count": 20, "email_validation_mailgun_count": 40, "email_validation_mailjet_count": 5, "email_preview_count": 60, "email_preview_failed_count": 16, "link_validation_count": 5, "link_validation_failed_count": 7, "seed_test_count": 9, "ip_blocklist_monitoring_count": 42, "domain_blocklist_monitoring_count": 1001 } } ], "aggregates": { "metrics": {} } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/analytics/logs": { "post": { "tags": [ "Logs" ], "summary": "List logs", "description": "Gets customer event logs for an account", "operationId": "POST-v1-analytics-logs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-LogsRequest" }, "examples": { "Example": { "value": { "start": "Mon, 08 Jul 2024 00:00:00 -0000", "end": "Fri, 12 Jul 2024 00:00:00 -0000", "filter": { "AND": [ { "attribute": "domain", "comparator": "=", "values": [ { "label": "example.com", "value": "example.com" } ] } ] }, "include_subaccounts": true, "pagination": { "sort": "timestamp:asc", "token": "cjsijbijewbu78t678tVTYUYU76754fyuiksin865g", "limit": 50 } } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-LogsResponse" }, "examples": { "Example": { "value": { "start": "Mon, 08 Jul 2024 00:00:00 -0000", "end": "Fri, 12 Jul 2024 00:00:00 -0000", "items": [ { "id": "JDhSWf9mT5OFxCkZfpDU5d", "event": "failed", "@timestamp": "2024-07-08T16:30:18.530Z", "account": { "id": "12345" }, "delivery-status": { "message": "Turret client: server connection failed", "attempt-no": 5, "code": 680, "session-seconds": 15.026, "retry-seconds": 145 }, "domain": { "name": "example.com" }, "recipient": "example@gmail.com", "recipient-domain": "gmail.com", "recipient-provider": "Gmail", "envelope": { "sender": "bob@example.com", "transport": "smtp", "sending-ip": "198.52.100.1", "targets": "bob@example.com" } } ], "pagination": { "previous": "cjsijbijewbu78t678tVTYUYU76754fyuiksi23h75", "next": "cjsijbijewbu78t678tVTYUYU76754fyuiksin98hh", "first": "cjsijbijewbu78t678tVTYUYU76754fyuiksin865g", "last": "875bunjnWkmis75bjklnsdk0s7jksnjknlknc64aTR", "total": 100 }, "aggregates": {} } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] }, { "basicAuth": [] } ] } }, "/v1/analytics/tags": { "put": { "tags": [ "Tags New" ], "summary": "Update account tag", "description": "Updates the tag description for an account", "operationId": "PUT-v1-analytics-tags", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-UpdateTagRequest" }, "examples": { "Example": { "value": { "tag": "name-of-tag-to-update", "description": "updated tag description" } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Tag updated" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Tags New" ], "summary": "Post query to list account tags or search for single tag", "description": "Gets the list of all tags, or filtered by tag prefix, for an account", "operationId": "POST-v1-analytics-tags", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-ListTagsRequest" }, "examples": { "Example": { "value": { "pagination": { "sort": "lastseen:desc", "limit": 10 }, "include_subaccounts": true } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-TagsResponse" }, "examples": { "Example": { "value": { "items": [ { "account_id": "12345", "parent_account_id": "12345", "tag": "tag1", "description": "tag used to identify campaign 1", "first_seen": {}, "last_seen": {}, "metrics": {}, "account_name": "account1" }, { "account_id": "67890", "parent_account_id": "12345", "tag": "tag2", "description": "tag used to identify campaign 2", "first_seen": {}, "last_seen": {}, "metrics": {}, "account_name": "account2" } ], "pagination": { "sort": "lastseen:desc", "limit": 10, "total": 2 } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "reason for bad request" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Tags New" ], "summary": "Delete account tag", "description": "Deletes the tag for an account", "operationId": "DELETE-v1-analytics-tags", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-DeleteTagRequest" }, "examples": { "Example": { "value": { "tag": "name-of-tag-to-delete" } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Tag deleted" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/analytics/tags/limits": { "get": { "tags": [ "Tags New" ], "summary": "Get account tag limit information", "description": "Gets the tag limit and current number of unique tags for an account", "operationId": "GET-v1-analytics-tags-limits", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-TagLimitCountResponse" } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/thresholds/alerts/send": { "get": { "tags": [ "Send Alerts" ], "summary": "List send alerts", "operationId": "GET-v1-thresholds-alerts-send", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-SendAlertListResponse" }, "examples": { "Example": { "value": { "items": [ { "id": "915ff385-0a9a-4087-86d5-6727ea7d9b49", "parent_account_id": "12345", "subaccount_id": "67890", "name": "hard bounce rate", "created_at": "2026-02-01T10:30:00Z", "updated_at": "2026-02-03T14:15:00Z", "last_checked": "2026-02-04T16:00:00Z", "alert_channels": [ "email", "webhook", "slack" ], "metric": "hard_bounce_rate", "comparator": "<", "limit": ".99", "dimension": "subaccount", "period": "1h" }, { "id": "734ff385-0a9a-4087-86d5-6727ea7d9c34", "parent_account_id": "12345", "subaccount_id": "67890", "name": "complaint rate", "created_at": "2026-02-01T10:30:00Z", "updated_at": "2026-02-03T14:15:00Z", "last_checked": "2026-02-01T10:30:00Z", "alert_channels": [ "email" ], "metric": "complained_rate", "comparator": ">", "limit": ".01", "dimension": "subaccount", "period": "1h" } ], "total": 2 } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Send Alerts" ], "summary": "Create a send alert for an account", "operationId": "POST-v1-thresholds-alerts-send", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-SendAlertRequest" }, "examples": { "Example": { "value": { "name": "hard bounce rate", "metric": "hard_bounce_rate", "comparator": "<", "limit": ".99", "dimension": "subaccount", "alert_channels": [ "email", "webhook", "slack" ], "period": "1h" } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-SendAlertItem" }, "examples": { "Example": { "value": { "id": "915ff385-0a9a-4087-86d5-6727ea7d9b49", "parent_account_id": "12345", "subaccount_id": "67890", "name": "delivery rate", "created_at": "2026-02-01T10:30:00Z", "updated_at": "2026-02-01T10:30:00Z", "last_checked": "2026-02-01T10:30:00Z", "alert_channels": [ "email", "webhook", "slack" ], "metric": "delivered_rate", "comparator": "<", "limit": ".99", "dimension": "subaccount", "period": "1h" } } } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/thresholds/alerts/send/{name}": { "get": { "tags": [ "Send Alerts" ], "summary": "Get a send alert", "operationId": "GET-v1-thresholds-alerts-send--name-", "parameters": [ { "name": "name", "in": "path", "description": "Threshold name that identifies this threshold", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-SendAlertItem" }, "examples": { "Example": { "value": { "id": "915ff385-0a9a-4087-86d5-6727ea7d9b49", "parent_account_id": "12345", "subaccount_id": "67890", "name": "delivery rate", "created_at": "2026-02-01T10:30:00Z", "updated_at": "2026-02-03T14:15:00Z", "last_checked": "2026-02-04T16:00:00Z", "alert_channels": [ "email", "webhook", "slack" ], "metric": "delivered_rate", "comparator": "<", "limit": ".99", "dimension": "subaccount", "period": "1h" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Send Alerts" ], "summary": "Update a send alert", "description": "Updates the configuration of an existing send alert.\n\nNOTE: This endpoint performs a full replacement (PUT) of the alert resource. To update specific fields like 'alert_channels' without losing existing configuration, you should first fetch the current alert object via a GET request.\n\nUse the attributes from the existing alert to populate the request body, modifying only the 'alert_channels' array (or other desired fields) before sending the PUT request. Omitting existing attributes may result in validation errors or the loss of current settings.", "operationId": "PUT-v1-thresholds-alerts-send--name-", "parameters": [ { "name": "name", "in": "path", "description": "Threshold name that identifies this threshold", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-SendAlertRequest" }, "examples": { "Example": { "value": { "name": "hard bounce rate", "metric": "hard_bounce_rate", "comparator": "<", "limit": ".98", "dimension": "subaccount", "alert_channels": [ "email", "webhook", "slack" ], "period": "1h" } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Send Alerts" ], "summary": "Delete a send alert", "operationId": "DELETE-v1-thresholds-alerts-send--name-", "parameters": [ { "name": "name", "in": "path", "description": "Threshold name that identifies this threshold", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/thresholds/limits": { "get": { "tags": [ "Limits" ], "summary": "List limit thresholds for an account", "operationId": "GET-v1-thresholds-limits", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-ThresholdLimitListResponse" }, "examples": { "Example": { "value": { "items": [ { "id": "915ff385-0a9a-4087-86d5-6727ea7d9b49", "parent_account_id": "12345", "subaccount_id": "67890", "name": "email preview", "created_at": "2026-02-01T10:30:00Z", "updated_at": "2026-02-03T14:15:00Z", "last_checked": "2026-02-04T16:00:00Z", "metric": "email_preview_success_count", "comparator": ">=", "limit": "2100", "dimension": "subaccount", "period": "1M" }, { "id": "734ff385-0a9a-4087-86d5-6727ea7d9c34", "parent_account_id": "12345", "subaccount_id": "67890", "name": "email preview strict", "created_at": "2026-02-01T10:30:00Z", "updated_at": "2026-02-03T14:15:00Z", "last_checked": "2026-02-04T16:00:00Z", "metric": "email_preview_success_count", "comparator": ">=", "limit": "1000", "dimension": "subaccount", "period": "1M" } ], "total": 2 } } } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Limits" ], "summary": "Create a limit threshold for an account", "operationId": "POST-v1-thresholds-limits", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-LimitRequest" }, "examples": { "Example": { "value": { "name": "email preview", "metric": "email_preview_success_count", "comparator": ">=", "limit": "2100", "dimension": "subaccount", "period": "1M" } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-ThresholdLimitItem" }, "examples": { "Example": { "value": { "id": "915ff385-0a9a-4087-86d5-6727ea7d9b49", "parent_account_id": "12345", "subaccount_id": "67890", "name": "email preview", "created_at": "2026-02-01T10:30:00Z", "updated_at": "0001-01-01T00:00:00Z", "last_checked": "0001-01-01T00:00:00Z", "metric": "email_preview_success_count", "comparator": ">=", "limit": "2100", "dimension": "subaccount", "period": "1M" } } } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/thresholds/limits/{name}": { "get": { "tags": [ "Limits" ], "summary": "Get a limit threshold for an account", "operationId": "GET-v1-thresholds-limits--name-", "parameters": [ { "name": "name", "in": "path", "description": "Threshold name that identifies this threshold", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-ThresholdLimitItem" }, "examples": { "Example": { "value": { "id": "915ff385-0a9a-4087-86d5-6727ea7d9b49", "parent_account_id": "12345", "subaccount_id": "67890", "name": "email preview", "created_at": "2026-02-01T10:30:00Z", "updated_at": "2026-02-03T14:15:00Z", "last_checked": "2026-02-04T16:00:00Z", "metric": "email_preview_success_count", "comparator": ">=", "limit": "2100", "dimension": "subaccount", "period": "1M" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Limits" ], "summary": "Update a limit threshold for an account", "operationId": "PUT-v1-thresholds-limits--name-", "parameters": [ { "name": "name", "in": "path", "description": "Threshold name that identifies this threshold", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-LimitRequest" }, "examples": { "Example": { "value": { "name": "email preview", "metric": "email_preview_success_count", "comparator": ">=", "limit": "2100", "dimension": "subaccount", "period": "1M" } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Limits" ], "summary": "Delete a limit threshold for an account", "operationId": "DELETE-v1-thresholds-limits--name-", "parameters": [ { "name": "name", "in": "path", "description": "Threshold name that identifies this threshold", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/thresholds/hits": { "get": { "tags": [ "Send Alerts" ], "summary": "List account hits", "operationId": "GET-v1-thresholds-hits", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-HitListResponse" }, "examples": { "Example": { "value": { "items": [ { "id": "915ff385-0a9a-4087-86d5-6727ea7d9b49", "name": "hard bounce rate", "created_at": "2026-02-01T10:30:00Z", "updated_at": "2026-02-03T14:15:00Z", "triggered": true, "expires_at": "0001-01-01T00:00:00Z", "latest_value": "10", "metric": "hard_bounce_rate", "comparator": "<", "limit": "2100", "parent_account_id": "12345", "subaccount_id": "67890", "dimension": "subaccount" }, { "id": "734ff385-0a9a-4087-86d5-6727ea7d9c34", "name": "complained rate", "created_at": "2026-02-01T10:30:00Z", "updated_at": "2026-02-03T14:15:00Z", "triggered": true, "expires_at": "0001-01-01T00:00:00Z", "latest_value": "7", "metric": "complained_rate", "comparator": ">", "limit": "1000", "parent_account_id": "12345", "subaccount_id": "67890", "dimension": "subaccount" } ], "total": 2 } } } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/events": { "get": { "tags": [ "Alerts" ], "summary": "List events", "description": "The current list of events that you can chose to receive alerts for.", "operationId": "GET-v1-alerts-events", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-ListAlertsEventsResp" }, "examples": { "Example": { "value": { "events": [ "ip_listed", "ip_delisted" ] } } } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/settings/events": { "post": { "tags": [ "Alerts" ], "summary": "Add Alert", "description": "Use this endpoint to add new alert settings record. This service facilitates notifications (Webhook, Slack, or Email) for both Mailgun Optimize and Send Alert threshold breaches.\n\n### Webhooks\n\nThis section covers details around consuming alerts via webhooks. If you are familiar with Mailgun Send webhooks (which provide status updates on individual email deliveries), \nthere is a lot of overlapping similarity, however, there are also a few minor nuances to account for.\n\n#### Securing Webhooks\n\nHMAC is used to verify the integrity as well as the authenticity of received webhooks. To verify the origin of a webhook:\n\n1. Encode the webhook’s entire POST request body with the HMAC algorithm (using your webhook signing key and SHA256 digest mode)\n2. Compare the resulting hexdigest to the signature provided in the POST request’s X-Sign header.\n\nNOTE: If you’re consuming Mailgun Send webhooks, please note that your Mailgun Send webhook signing key differs \nfrom your Alerts webhook signing key. \nYour Alerts webhook signing keys, used for both Optimize and Send Alert products, are available within the Mailgun Alerts UI.\n\n#### Webhook URL Validation\n\nWhen adding or updating a webhook URL for alerts, we will ensure the endpoint is reachable by sending a GET request to the provided URL. If a 200 response is not returned from your endpoint, the request will be rejected and your alert setting will not be saved. We intentionally chose to send a GET request instead of a POST when validating URLs so that your webhook endpoint does not have to account for test requests.\n\nAdditionally, when a POST request is sent to your webhook URL, if a 2xx is not returned, we will attempt retries via an exponential backoff strategy for up to ~8 hours. If the max retry count is reached, the alert will be disabled and the related alert settings record’s disabled_at field will be populated.", "operationId": "POST-v1-alerts-settings-events", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-mutateEventSettingReq" }, "examples": { "Example": { "value": { "event_type": "ip_listed", "channel": "webhook", "settings": { "url": "https://yourwebhookurl.com" } } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-settings-EventSettings" }, "examples": { "Example": { "value": { "id": "00000000-0000-0000-0000-000000000000", "event_type": "ip_listed", "channel": "webhook", "settings": { "url": "https://yourwebhookurl.com" } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "409": { "description": "A 409 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/settings/events/{id}": { "put": { "tags": [ "Alerts" ], "summary": "Update Alert", "description": "Use this endpoint to update an existing alert setting record.\n\nNOTE: When updating a webhook alert, we will ensure the endpoint is reachable by sending a GET request to the provided URL. If a 200 response is not returned, a 400 will be returned and the alert setting update will be rejected.", "operationId": "PUT-v1-alerts-settings-events--id-", "parameters": [ { "name": "id", "in": "path", "description": "The settings ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-mutateEventSettingReq" }, "examples": { "Example": { "value": { "event_type": "ip_delisted", "channel": "email", "settings": { "emails": [ "recipient-a@example.com", "recipient-b@example.com" ] } } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "settings updated" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Alerts" ], "summary": "Remove Alert", "operationId": "DELETE-v1-alerts-settings-events--id-", "parameters": [ { "name": "id", "in": "path", "description": "The settings ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "settings deleted" } } } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/settings": { "get": { "tags": [ "Alerts" ], "summary": "List Alerts", "description": "This endpoint returns a list of all configured alert settings for your account.", "operationId": "GET-v1-alerts-settings", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-SettingsResponse" }, "examples": { "Example": { "value": { "events": [ { "id": "00000000-0000-0000-0000-000000000000", "event_type": "ip_listed", "channel": "webhook", "settings": { "url": "https://example.com/delisted_hook" } }, { "id": "00000000-0000-0000-0000-000000000000", "event_type": "ip_delisted", "channel": "webhook", "settings": { "url": "https://yourwebhookurl.com" }, "disabled_at": "2006-01-02T22:04:05Z" }, { "id": "00000000-0000-0000-0000-000000000000", "event_type": "ip_delisted", "channel": "email", "settings": { "emails": [ "recipient-1@example.com", "recipient-2@example.com" ] } } ], "webhooks": {}, "slack": {} } } } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/settings/slack": { "put": { "tags": [ "Alerts" ], "summary": "Update Slack settings", "operationId": "PUT-v1-alerts-settings-slack", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-settings-Slack" } } }, "required": true }, "responses": { "204": { "description": "A 204 response" }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Alerts" ], "summary": "Delete Slack settings", "description": "Delete Slack settings and Slack event settings for the Mailgun account.\n\nTo revoke the Slack access token, use DELETE /v1/alerts/slack/oauth.\n\nTo completely remove the Slack App from Slack Workspace, go into App Configuration in Slack.", "operationId": "DELETE-v1-alerts-settings-slack", "responses": { "204": { "description": "A 204 response" }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/settings/webhooks/signing_key": { "put": { "tags": [ "Alerts" ], "summary": "Reset Webhook Signing Key", "operationId": "PUT-v1-alerts-settings-webhooks-signing-key", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-ResetWebhooksSigningKeyResp" } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/webhooks/test": { "post": { "tags": [ "Alerts" ], "summary": "Test webhook", "description": "Sends test webhook request to specified url with dummy data.", "operationId": "POST-v1-alerts-webhooks-test", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-TestWebhookRequest" }, "examples": { "Example": { "value": { "event_type": "some-event", "url": "https://some-webhook-url.com/webhook" } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/email/test": { "post": { "tags": [ "Alerts" ], "summary": "Test message", "description": "Sends test message to emails with dummy data.", "operationId": "POST-v1-alerts-email-test", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-TestEmailRequest" }, "examples": { "Example": { "value": { "event_type": "some-event", "emails": [ "email1@example.com", "email2@example.com" ] } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/slack/test": { "post": { "tags": [ "Alerts" ], "summary": "Test message", "description": "Sends test message to slack channels with dummy data.", "operationId": "POST-v1-alerts-slack-test", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-TestSlackRequest" }, "examples": { "Example": { "value": { "event_type": "some-event", "channel_ids": [ "C0123", "C0456" ] } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/slack/oauth": { "delete": { "tags": [ "Alerts" ], "summary": "Revoke Slack access token", "description": "Revoke Slack access token, delete Slack settings and Slack event settings.\n\nNOTE: All Mailgun accounts connected to the same Slack workspace share the same token.\n\nTo completely remove the Slack App from Slack Workspace, go into App Configuration in Slack.", "operationId": "DELETE-v1-alerts-slack-oauth", "responses": { "204": { "description": "A 204 response" }, "default": { "description": "A default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/slack/channels/{id}": { "get": { "tags": [ "Alerts" ], "summary": "Get Slack channel", "description": "Returns Slack channel.", "operationId": "GET-v1-alerts-slack-channels--id-", "parameters": [ { "name": "id", "in": "path", "description": "The Slack channel ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-SlackChannel" }, "examples": { "Example": { "value": { "id": "C012AB3CD", "name": "general" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "token should have 'xoxb-' prefix" } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "missing_scope: please reconnect the Slack App" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "no settings" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/alerts/slack/channels": { "get": { "tags": [ "Alerts" ], "summary": "List Slack channels", "description": "List Slack channels for the connected Slack workspace.", "operationId": "GET-v1-alerts-slack-channels", "parameters": [ { "name": "page", "in": "query", "description": "Encoded paging information, provided via 'next', 'first' links", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limits the number of items returned in a request", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-ListSlackChannelsResp" }, "examples": { "Example": { "value": { "items": [ { "id": "C012AB3CD", "name": "general" } ], "paging": { "first": "https://api.mailgun.net/v1/alerts/slack/channels?page=foo", "next": "https://api.mailgun.net/v1/alerts/slack/channels?page=bar" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "token should have 'xoxb-' prefix" } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "missing_scope: please reconnect the Slack App" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "no settings" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/unsubscribes/import": { "post": { "tags": [ "Unsubscribe" ], "summary": "Import unsubscribe list", "description": "Import a CSV file containing a list of addresses to add to the unsubscribe list. The CSV file must be 25MB or under and can contain the following column headers: address, tags, created_at. address is a valid email address (required). tags is tag to unsubscribe from, use * to unsubscribe an address from all domain's correspondence (optional, default: *). created_at is timestamp of unsubscribe event in RFC2822 format (optional, default: current time)", "operationId": "POST-v3--domainID--unsubscribes-import", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to update unsubscribes for", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "Content-Type must be `multipart/form-data`", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domainID-unsubscribes-import-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "202": { "description": "A 202 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "file uploaded successfully for processing. standby..." } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "while reading csv header" } } } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Internal Server Error" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/bounces/import": { "post": { "tags": [ "Bounces" ], "summary": "Import list of bounces", "description": "Import a CSV file containing a list of addresses to add to the bounce list. The CSV file must be 25MB or under and must contain the following column headers: address, code, error, created_at. address is a valid email address. code is error code (optional, default: 550). error is error description (optional, default: empty string). created_at is timestamp of bounce event in RFC2822 format (optional, default: current time)", "operationId": "POST-v3--domainID--bounces-import", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to update bounces for", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "Content-Type must be `multipart/form-data`", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domainID-bounces-import-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "202": { "description": "A 202 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "file uploaded successfully for processing. standby..." } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Internal Server Error" } } } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "while reading csv header" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/complaints/import": { "post": { "tags": [ "Complaints" ], "summary": "Import complaint list", "description": "Import a CSV file containing a list of addresses to add to the complaint list. The CSV file must be 25MB or under and can contain the following column headers: address, created_at. address is a valid email address (required). created_at is timestamp of complaint event in RFC2822 format (optional, default: current time)", "operationId": "POST-v3--domainID--complaints-import", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to update complaints for", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "Content-Type must be `multipart/form-data`", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domainID-complaints-import-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "202": { "description": "A 202 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "ffile uploaded successfully for processing. standby..." } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "while reading csv header" } } } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Internal Server Error" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/whitelists/import": { "post": { "tags": [ "Allowlist" ], "summary": "Import allowlist", "description": "Import a CSV file containing a list of addresses and/or domains to add to the allowlist. The CSV file must be 25MB or under and must contain the following column headers: address, domain. For each row provide either an address or a domain, but not both - choose one, keep the other blank.", "operationId": "POST-v3--domainID--whitelists-import", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to update allowlist for", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "Content-Type must be `multipart/form-data`", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domainID-whitelists-import-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "202": { "description": "A 202 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "file uploaded successfully for processing. standby..." } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "while reading csv header" } } } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Internal Server Error" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/bounces/{address}": { "get": { "tags": [ "Bounces" ], "summary": "Lookup bounce record", "description": "Fetch a single bounce event by a given email address.", "operationId": "GET-v3--domainID--bounces--address-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to retrieve the bounce from", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "The address to search for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Bounce" }, "examples": { "Example": { "value": { "address": "foo@bar.com", "code": "550", "error": "No such mailbox", "created_at": "Thu, 11 Dec 2025 01:49:40 UTC" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Address not found in bounces table" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Bounces" ], "summary": "Remove bounce", "description": "Delivery to the deleted email address resumes until it bounces again.", "operationId": "DELETE-v3--domainID--bounces--address-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to delete the bounce from", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "The address to remove", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-suppressionResponse" }, "examples": { "Example": { "value": { "message": "Bounced addresses for this domain have been removed", "address": "foo@bar.com" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Address not found in bounces table" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/bounces": { "get": { "tags": [ "Bounces" ], "summary": "List all bounces", "description": "Paginate over a list of bounces for a domain.", "operationId": "GET-v3--domainID--bounces", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to retrieve bounces from", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (optional, default: 100, max: 1000)", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page direction relative to the above address, can be `next`, `previous` or `last`, if empty, returns the first page", "required": true, "schema": { "type": "string" } }, { "name": "term", "in": "query", "description": "Filter records based on addresses that start with the specified substring.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-getBouncesPaginationResponse" }, "examples": { "Example": { "value": { "items": [ { "address": "foo@bar.com", "code": "550", "error": "No such mailbox", "created_at": "Thu, 11 Dec 2025 01:49:40 UTC" } ], "paging": { "previous": "", "first": "", "next": "", "last": "" } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Bounces" ], "summary": "Add bounces", "description": "Request body is expected to be a valid JSON encoded sting containing up to 1000 bounce records or a single bounce record as application/form-data", "operationId": "POST-v3--domainID--bounces", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to add the bounce to", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "Content-Type must be `application/json` if inserting using JSON, no header necessary for form-data insertion", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-BouncesList" }, "examples": { "Example": { "value": [ { "address": "alice@example.com", "code": "550", "error": "Bounced", "createdat": "Thu, 11 Dec 2025 01:49:40 UTC", "messagehash": "" }, { "address": "bob@example.com", "code": "550", "error": "Bounced", "createdat": "Mon, 01 Jan 0001 00:00:00 UTC", "messagehash": "" }, { "address": "carol@example.com", "code": "550", "error": "", "createdat": "Mon, 01 Jan 0001 00:00:00 UTC", "messagehash": "" }, { "address": "dan@example.com", "code": "", "error": "", "createdat": "Mon, 01 Jan 0001 00:00:00 UTC", "messagehash": "" } ] } } }, "application/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domainID-bounces-application-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "4 addresses have been added to the bounces table" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Batch size should be less than 1000" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Bounces" ], "summary": "Clear all bounces", "description": "Clears all email addresses with bounces from the domain. Delivery to the deleted email addresses will longer be suppressed.", "operationId": "DELETE-v3--domainID--bounces", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to delete bounces from", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Bounced addresses for this domain have been removed" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/unsubscribes/{address}": { "get": { "tags": [ "Unsubscribe" ], "summary": "Lookup unsubscribe record", "description": "Fetch a single unsubscribe record to check if a given address is present in a list of unsubscribed users.", "operationId": "GET-v3--domainID--unsubscribes--address-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to retrieve the unsubscribe from", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "The address to search for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Unsubscribe" }, "examples": { "Example": { "value": { "address": "alice@example.com", "tags": [ "some tag" ], "created_at": "Thu, 11 Dec 2025 01:49:40 UTC" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Address not found in unsubscribers table" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Unsubscribe" ], "summary": "Remove unsubscribe", "description": "Delivery to the deleted email address resumes until it unsubscribes again.", "operationId": "DELETE-v3--domainID--unsubscribes--address-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to delete the unsubscribe from", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "The address to remove", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-suppressionResponse" }, "examples": { "Example": { "value": { "message": "Unsubscribe event has been removed", "address": "foo@bar.com" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Unsubscribe event for this tag does not exist" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/unsubscribes": { "get": { "tags": [ "Unsubscribe" ], "summary": "List all unsubscribes", "description": "Paginate over a list of unsubscribes for domain.", "operationId": "GET-v3--domainID--unsubscribes", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to retrieve unsubscribes from", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (optional, default: 100, max: 1000)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page direction relative to the above address, can be `next`, `previous` or `last`, if empty, returns the first page", "schema": { "type": "string" } }, { "name": "address", "in": "query", "description": "address serving as a \"divider\" between pages", "required": true, "schema": { "type": "string" } }, { "name": "term", "in": "query", "description": "Filter records based on addresses that start with the specified substring.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-getUnsubscribesPaginationResponse" }, "examples": { "Example": { "value": { "items": [ { "address": "alice@example.com", "tags": [ "some tag" ], "created_at": "Thu, 11 Dec 2025 01:49:40 UTC" } ], "paging": { "previous": "", "first": "", "next": "", "last": "" } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Unsubscribe" ], "summary": "Add unsubscribes", "description": "Request body is expected to be a valid JSON encoded sting containing up to 1000 unsubscribe records or a single unsubscribe record as application/form-data", "operationId": "POST-v3--domainID--unsubscribes", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to add the unsubscribe to", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "Content-Type must be `application/json` if inserting using JSON, no header necessary for form-data insertion", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-UnsubscribesList" }, "examples": { "Example": { "value": [ { "address": "alice@example.com", "tags": [ "some tag" ], "createdat": "Thu, 11 Dec 2025 01:49:40 UTC" }, { "address": "bob@example.com", "tags": [ "*" ], "createdat": "Mon, 01 Jan 0001 00:00:00 UTC" }, { "address": "carol@example.com", "tags": [], "createdat": "Mon, 01 Jan 0001 00:00:00 UTC" } ] } } }, "application/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domainID-unsubscribes-application-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "4 addresses have been added to the unsubscribes table" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Batch size should be less than 1000" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Unsubscribe" ], "summary": "Clear all unsubscribes", "description": "Clear all unsubscribe email addresses for the domain. Delivery to the deleted email addresses will no longer be suppressed.", "operationId": "DELETE-v3--domainID--unsubscribes", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to delete unsubscribes from", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Unsubscribe addresses for this domain have been removed" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/complaints/{address}": { "get": { "tags": [ "Complaints" ], "summary": "Lookup complaint record", "description": "Fetch a single complaint records to check if a given address is present in the list of complaints.", "operationId": "GET-v3--domainID--complaints--address-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to retrieve the complaint from", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "The address to search for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Complaint" }, "examples": { "Example": { "value": { "address": "alice@example.com", "created_at": "Thu, 11 Dec 2025 01:49:40 UTC" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "No spam complaints found for this address" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Complaints" ], "summary": "Remove complaint", "description": "Delivery to the deleted email address resumes until there is another complaint.", "operationId": "DELETE-v3--domainID--complaints--address-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to delete the complaint from", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "path", "description": "The address to remove", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-suppressionResponse" }, "examples": { "Example": { "value": { "message": "Complaint addresses for this domain have been removed", "address": "foo@bar.com" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "No spam complaints found for this address" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/complaints": { "get": { "tags": [ "Complaints" ], "summary": "List all complaints", "description": "Paginate a list of complaints for the domain.", "operationId": "GET-v3--domainID--complaints", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to retrieve complaints from", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (optional, default: 100, max: 1000)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page direction relative to the above address, can be `next`, `previous` or `last`, if empty, returns the first page", "schema": { "type": "string" } }, { "name": "address", "in": "query", "description": "address serving as a \"divider\" between pages", "required": true, "schema": { "type": "string" } }, { "name": "term", "in": "query", "description": "Filter records based on addresses that start with the specified substring.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-getComplaintsPaginationResponse" }, "examples": { "Example": { "value": { "items": [ { "address": "alice@example.com", "created_at": "Thu, 11 Dec 2025 01:49:40 UTC" } ], "paging": { "previous": "", "first": "", "next": "", "last": "" } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Complaints" ], "summary": "Add complaints", "description": "Request body is expected to be a valid JSON encoded sting containing up to 1000 complaint records or a single complaint record as application/form-data", "operationId": "POST-v3--domainID--complaints", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to add the complaint to", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "Content-Type must be `application/json` if inserting using JSON, no header necessary for form-data insertion", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-ComplaintsList" }, "examples": { "Example": { "value": [ { "address": "alice@example.com", "createdat": "Thu, 11 Dec 2025 01:49:40 UTC" }, { "address": "bob@example.com", "createdat": "Mon, 01 Jan 0001 00:00:00 UTC" } ] } } }, "application/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domainID-complaints-application-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "2 complaint addresses have been added to the complaints table" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Batch size should be less than 1000" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Complaints" ], "summary": "Clear all complaints", "description": "Clears all email addresses with complaints from the domain. Delivery to the deleted email addresses will longer be suppressed.", "operationId": "DELETE-v3--domainID--complaints", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to delete complaints from", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Complaint addresses for this domain have been removed" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/whitelists/{value}": { "get": { "tags": [ "Allowlist" ], "summary": "Lookup allowlist record", "description": "Fetch a single allowlist record to check if a given address or domain is present.", "operationId": "GET-v3--domainID--whitelists--value-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to retrieve the allowlist entry from", "required": true, "schema": { "type": "string" } }, { "name": "value", "in": "path", "description": "The address to search for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Whitelist" }, "examples": { "Example": { "value": { "type": "domain", "value": "alice@example.com", "createdAt": "Thu, 11 Dec 2025 01:49:40 UTC", "reason": "why the record was created" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Address/Domain not found in allowlist table" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Allowlist" ], "summary": "Remove entry from allowlist", "description": "Remove a single entry from the allowlist", "operationId": "DELETE-v3--domainID--whitelists--value-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to delete the allowlist entry from", "required": true, "schema": { "type": "string" } }, { "name": "value", "in": "path", "description": "The address to remove", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-deleteWhitelistRecordResponse" }, "examples": { "Example": { "value": { "message": "Allowlist address/domain has been removed", "value": "example.com" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Address/Domain not found in allowlist table" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/whitelists": { "get": { "tags": [ "Allowlist" ], "summary": "List allowlist records for domain", "description": "Paginate over all allowlist records for a domain.", "operationId": "GET-v3--domainID--whitelists", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to retrieve allowlist entries from", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (optional, default: 100, max: 1000)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page direction relative to the above address, can be `next`, `previous` or `last`, if empty, returns the first page", "schema": { "type": "string" } }, { "name": "address", "in": "query", "description": "address serving as a \"divider\" between pages", "required": true, "schema": { "type": "string" } }, { "name": "term", "in": "query", "description": "Filter records based on addresses that start with the specified substring.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-getWhitelistPaginationResponse" }, "examples": { "Example": { "value": { "items": [ { "type": "domain", "value": "alice@example.com", "createdAt": "Thu, 11 Dec 2025 01:49:40 UTC", "reason": "why the record was created" } ], "paging": { "previous": "", "first": "", "next": "", "last": "" } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Allowlist" ], "summary": "Add allowlist record", "description": "Add an address or domain to the allowlist table", "operationId": "POST-v3--domainID--whitelists", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to add the allowlist entry to", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domainID-whitelists-application-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-api-insertWhitelistRecordResponse" }, "examples": { "Example": { "value": { "message": "Address/Domain has been added to the allowlists table", "type": "domain", "value": "example.com" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Missing mandatory parameter: address/domain" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Allowlist" ], "summary": "Clear allowlist", "description": "Delete an entire allowlist for a domain", "operationId": "DELETE-v3--domainID--whitelists", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain to delete allowlist entries from", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Allowlist addresses/domains for this domain have been removed" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/routes": { "post": { "tags": [ "Routes" ], "summary": "Create a route", "description": "Adds a new route to the account", "operationId": "post-v3-routes", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "priority": { "type": "integer", "description": "Smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0." }, "description": { "type": "string", "description": "An arbitrary string." }, "expression": { "type": "string", "description": "The filtering rule." }, "action": { "type": "array", "description": "This action is executed when the expression evaluates to True. You can pass multiple parameters.", "items": { "type": "string" } } }, "required": [ "expression" ] }, "encoding": { "action": { "style": "form", "explode": true } }, "examples": { "Example": { "value": { "priority": 0, "description": "it's a new route", "expression": "match_recipient('.*@gmail.com')", "action": [ "forward(\"http://myhost.com/messages/\")", "stop()" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A string describing the result of the operation" }, "route": { "$ref": "#/components/schemas/RouteResponse", "description": "The created route" } } }, "examples": { "Example": { "value": { "message": "Route has been created", "route": { "id": "4f3bad2335335426750048c6", "priority": 0, "description": "it's a new route", "expression": "match_recipient('.*@gmail.com')", "actions": [ "forward(\"http://myhost.com/messages/\")" ], "created_at": "Wed, 15 Feb 2012 13:03:31 GMT" } } } } } } } }, "security": [ { "basicAuth": [] } ] }, "get": { "tags": [ "Routes" ], "summary": "Get all routes", "description": "Get the list of routes. Note that routes are defined globally, per account, not per domain.", "operationId": "get-v3-routes", "parameters": [ { "name": "skip", "in": "query", "description": "Number of records to skip. Defaults to 0.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Defaults to 100.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total number of routes in the account" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RouteResponse" }, "description": "List of routes" } } }, "examples": { "Example": { "value": { "total_count": 1, "items": [ { "id": "4f3bad2335335426750048c6", "priority": 0, "description": "Sample route", "expression": "match_recipient(\".*@samples.mailgun.org\")", "actions": [ "forward(\"http://myhost.com/messages/\")", "stop()" ], "created_at": "Wed, 15 Feb 2012 13:03:31 GMT" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A string describing the error" } } }, "examples": { "Example": { "value": { "message": "The 'limit' parameter can't be larger than 1000" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/routes/{id}": { "get": { "tags": [ "Routes" ], "summary": "Get a route", "description": "Returns a detailed view of the route", "operationId": "get-v3-routes-id", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the route", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "route": { "$ref": "#/components/schemas/RouteResponse" } } }, "examples": { "Example": { "value": { "route": { "id": "4f3bad2335335426750048c6", "priority": 0, "description": "Sample route", "expression": "match_recipient(\".*@samples.mailgun.org\")", "actions": [ "forward(\"http://myhost.com/messages/\")", "stop()" ], "created_at": "Wed, 15 Feb 2012 13:03:31 GMT" } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A string describing the error" } } }, "examples": { "Example": { "value": { "message": "string" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Routes" ], "summary": "Update a route", "description": "Updates a given route. All parameters are optional. This only updates the specified fields, leaving others unchanged.", "operationId": "put-v3-routes-id", "parameters": [ { "name": "id", "in": "path", "description": "ID of the route", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the route" }, "priority": { "type": "integer", "description": "Smaller number indicates higher priority. Higher priority routes are handled first." }, "description": { "type": "string", "description": "An arbitrary string." }, "expression": { "type": "string", "description": "The filtering rule." }, "action": { "type": "array", "description": "This action is executed when the expression evaluates to True. You can pass multiple parameters.", "items": { "type": "string" } } } }, "examples": { "Example": { "value": { "priority": 0, "description": "Sample route", "expression": "match_recipient(\".*@samples.mailgun.org\")", "action": [ "forward(\"http://myhost.com/messages/\")", "stop()" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A string describing the result of the operation" }, "route": { "$ref": "#/components/schemas/RouteResponse" } } }, "examples": { "Example": { "value": { "message": "Route has been updated", "route": { "id": "4f3bad2335335426750048c6", "priority": 0, "description": "Sample route", "expression": "match_recipient(\".*@samples.mailgun.org\")", "actions": [ "forward(\"http://myhost.com/messages/\")", "stop()" ], "created_at": "Wed, 15 Feb 2012 13:03:31 GMT" } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A string describing the error" } } }, "examples": { "Example": { "value": { "message": "Route not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Routes" ], "summary": "Delete a route", "description": "Remove the rotue from the account.", "operationId": "delete-v3-routes-id", "parameters": [ { "name": "id", "in": "path", "description": "ID of the route", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A string describing the result of the operation" }, "id": { "type": "string", "description": "ID of the deleted route" } } }, "examples": { "Example": { "value": { "message": "Route has been deleted", "id": "4f3bad2335335426750048c6" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "Example": { "value": { "message": "Route not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/routes/match": { "get": { "tags": [ "Routes" ], "summary": "Match address to route", "description": "Checks if an address matches at least one route.", "operationId": "get-v3-routes-match", "parameters": [ { "name": "address", "in": "query", "description": "address to match routes on", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "route": { "$ref": "#/components/schemas/RouteResponse" } } }, "examples": { "Example": { "value": { "route": { "id": "4f3bad2335335426750048c6", "priority": 0, "description": "Sample route", "expression": "match_recipient(\".*@samples.mailgun.org\")", "actions": [ "forward(\"http://myhost.com/messages/\")", "stop()" ], "created_at": "Wed, 15 Feb 2012 13:03:31 GMT" } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "A string describing the error" } } }, "examples": { "Example": { "value": { "message": "Route not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/lists": { "post": { "tags": [ "Mailing Lists" ], "summary": "Create a mailing list", "description": "Adds a mailing list to the account.", "operationId": "post-v3-lists", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "A valid email address for the mailing list, e.g. developers@mailgun.net, or Developers " }, "name": { "type": "string", "description": "Mailing list name, e.g. Developers" }, "description": { "type": "string", "description": "A description" }, "access_level": { "type": "string", "description": "List access level, one of: readonly, members, everyone. Defaults to readonly" }, "reply_preference": { "type": "string", "description": "Set where replies should go: list or sender. Defaults to list" } }, "required": [ "address" ] }, "examples": { "Example": { "value": { "address": "developers@mailgun.net", "name": "Developers", "description": "Describe the mailing list", "access_level": "readonly", "reply_preference": "list" } } } } } }, "responses": { "201": { "description": "Mailing list creation success", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "$ref": "#/components/schemas/MailingListResponse" } } }, "examples": { "Example": { "value": { "list": { "address": "developers@mailgun.net", "name": "Developers", "description": "Describe the mailing list", "access_level": "readonly", "reply_preference": "list", "created_at": "Tue, 09 Aug 2011 20:50:27 -0000", "members_count": 2 }, "message": "Mailing list has been created" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example 1": { "value": { "message": "Invalid access level 'fake_access_level'. It can be any of: 'readonly', 'members', 'everyone'." } }, "Example 2": { "value": { "message": "Invalid reply preference 'wrong_preference'. It can be any of: 'sender', 'list'" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "get": { "tags": [ "Mailing Lists" ], "summary": "Get mailing lists", "description": "A mailing list is a group of members (recipients) which itself has an email address. This address becomes an ID for this mailing list.", "operationId": "get-v3-lists", "parameters": [ { "name": "limit", "in": "query", "description": "Set limit for the list length returned. Defaults to 100.", "schema": { "type": "string" } }, { "name": "skip", "in": "query", "description": "Skip the first n values in the list. Defaults to 0.", "schema": { "type": "string" } }, { "name": "address", "in": "query", "description": "Filter mailing lists matching a specific address", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MailingListResponse" } } } }, "examples": { "Example": { "value": { "total_count": 1, "items": [ { "address": "developers@mailgun.net", "name": "Developers", "description": "Describe the mailing list", "access_level": "readonly", "reply_preference": "list", "created_at": "Tue, 09 Aug 2011 20:50:27 -0000", "members_count": 2 } ] } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/lists/{list_address}/members": { "get": { "tags": [ "Mailing Lists" ], "summary": "Get mailing lists members", "description": "Lists members in a given mailing list", "operationId": "get-lists-string:list_address-members", "parameters": [ { "name": "address", "in": "query", "description": "A valid email address specification.", "schema": { "type": "string" } }, { "name": "subscribed", "in": "query", "description": "Filtering list on whether the member is subscribed or not.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return. Max is 100. Defaults to 100.", "schema": { "type": "integer" } }, { "name": "skip", "in": "query", "schema": { "type": "integer" } }, { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total number of members in the mailing list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListMemberResponse" } } } }, "examples": { "Example": { "value": { "total_count": 1, "items": [ { "address": "alice@example.com", "name": "Alice", "vars": { "gender": "female", "age": 27 }, "subscribed": true } ] } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Mailing Lists" ], "summary": "Create a mailing list member", "description": "Adds a new member to the mailing list. For adding many list members, consider bulk upload endpoints \"POST /v3/lists/{list_address}/members.json\" or \"members.csv\".", "operationId": "post-lists-string:list_address-members", "parameters": [ { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Valid email address specification." }, "name": { "type": "string", "description": "An optional member name." }, "vars": { "type": "object", "description": "JSON-encoded dictionary string with arbitrary parameters." }, "subscribed": { "type": "boolean", "description": "Set the member as subscribed or not. Defaults to true." }, "upsert": { "type": "boolean", "description": "Set to True to update member if present, False to raise error in case of a duplicate member. Defaults to false." } } }, "examples": { "Example": { "value": { "address": "alice@example.com", "name": "Alice", "vars": { "gender": "female", "age": 27 }, "subscribed": true, "upsert": true } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "$ref": "#/components/schemas/ListMemberResponse" }, "message": { "type": "string", "description": "Success message" } } }, "examples": { "Example": { "value": { "member": { "address": "alice@example.com", "name": "Alice", "vars": { "gender": "female", "age": 27 }, "subscribed": true }, "message": "Mailing list member has been created" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Address already exists 'alice@example.com'" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/lists/{list_address}/members.json": { "post": { "tags": [ "Mailing Lists" ], "summary": "Bulk upload members to a mailing list (JSON)", "description": "Adds multiple members, up to 1000 per call, to a mailing list, using JSON array format.\nIf the request includes more than 100 entries, the mailing list will be updated asynchronously.\n", "operationId": "post-lists-list_address-members.json", "parameters": [ { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } }, { "name": "members", "in": "query", "description": "Mailing list recipients in JSON array format. Can be, either, an array of string addresses or an array of ListMemberRequest JSON objects.", "required": true, "schema": { "oneOf": [ { "type": "string" }, { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListMemberRequest" } } } ] } }, { "name": "upsert", "in": "query", "description": "If true, an existing member will be updated. Defaults to false.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "$ref": "#/components/schemas/MailingListResponse" }, "task-id": { "type": "string", "description": "Unique identifier for the background upload task" }, "message": { "type": "string", "description": "Success message" } } }, "examples": { "Async update": { "value": { "list": { "address": "developers@mailgun.net", "name": "Developers", "description": "Describe the mailing list", "access_level": "readonly", "reply_preference": "list", "created_at": "Tue, 09 Aug 2011 20:50:27 -0000", "members_count": 2 }, "task-id": "4321", "message": "Mailing list upload started in background" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Mailing list 'devs@mg.net' not found" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/lists/{list_address}/members.csv": { "post": { "tags": [ "Mailing Lists" ], "summary": "Bulk upload members to a mailing list (CSV)", "description": "Adds multiple members, up to 1000 per call, to a mailing list via CSV file.", "operationId": "post-lists-list_address-members.csv", "parameters": [ { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "", "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "subscribed": { "type": "boolean" }, "upsert": { "type": "boolean" }, "members": { "type": "string", "description": "Absolute path to the CSV file" } } }, "examples": { "Example": { "value": { "upsert": true, "members": "absolute/path/to/file/members.csv" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "$ref": "#/components/schemas/MailingListResponse" }, "task-id": { "type": "string", "description": "Unique identifier for the background upload task" }, "message": { "type": "string", "description": "Success message" } } }, "examples": { "Example": { "value": { "list": { "address": "developers@mailgun.net", "name": "Developers", "description": "Describe the mailing list", "access_level": "readonly", "reply_preference": "list", "created_at": "Tue, 09 Aug 2011 20:50:27 -0000", "members_count": 2 }, "task-id": "4321", "message": "Mailing list upload started in background" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "CSV file is too big, max allowed size is 5 MB" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Mailing list 'devs@mg.net' not found" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/lists/{list_address}/members/{member_address}": { "get": { "tags": [ "Mailing Lists" ], "summary": "Get a member", "description": "Get details about a specific mailing list member", "operationId": "get-lists-list_address-members-member_address", "parameters": [ { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } }, { "name": "member_address", "in": "path", "description": "The member's address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMemberResponse" }, "examples": { "Example": { "value": { "address": "alice@example.com", "name": "Alice", "vars": { "gender": "female", "age": 27 }, "subscribed": true } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Mailing Lists" ], "summary": "Update a mailing list member", "description": "Updates a mailing list member with the given properties. Existing properties not included in the request will not be changed.", "operationId": "put-lists-list_address-members-member_address", "parameters": [ { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } }, { "name": "member_address", "in": "path", "description": "The member's address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "", "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "A valid email address specification." }, "name": { "type": "string", "description": "An optional member name." }, "vars": { "type": "object", "description": "JSON-encoded dictionary string with arbitrary parameters." }, "subscribed": { "type": "boolean", "description": "Set the member to subscribed or not. Defaults to True." } } }, "examples": { "Example": { "value": { "address": "alice@example.com", "name": "Alice", "vars": { "gender": "female", "age": 27 }, "subscribed": true } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "$ref": "#/components/schemas/ListMemberResponse" }, "message": { "type": "string", "description": "Success message" } } }, "examples": { "Example": { "value": { "member": { "address": "alice@example.com", "name": "Alice", "vars": { "gender": "female", "age": 27 }, "subscribed": true }, "message": "Mailing list member has been updated" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Mailing Lists" ], "summary": "Delete a member", "description": "Deletes a member from a mailing list", "operationId": "delete-lists-list_address-members-member_address", "parameters": [ { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } }, { "name": "member_address", "in": "path", "description": "The member's address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "properties": { "address": { "type": "string", "description": "The email address of the member" } } } } }, "examples": { "Example": { "value": { "member": { "address": "alice@example.com" }, "message": "Mailing list member has been deleted" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Member dev@example.com of mailing list alice@example.com not found" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/lists/{list_address}": { "put": { "tags": [ "Mailing Lists" ], "summary": "Update a mailing list", "description": "Update mailing list properties, such as address, description or name", "operationId": "put-v3-lists-address", "parameters": [ { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "The new mailing list address." }, "description": { "type": "string" }, "name": { "type": "string" }, "access_level": { "type": "string", "description": "One of: readonly, members, everyone. Defaults to readonly." }, "reply_reference": { "type": "string", "description": "Set where replies should go. Can be list or sender. Defaults to list." }, "list-id": { "type": "string" } } }, "examples": { "Example": { "value": { "address": "developers@mailgun.net", "name": "Developers", "description": "Describe the mailing list", "access_level": "readonly", "reply_preference": "list", "list_id": "123" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "list": { "$ref": "#/components/schemas/MailingListResponse" } } }, "examples": { "Example": { "value": { "message": "Mailing list has been updated", "list": { "address": "developers@mailgun.net", "name": "Developers", "description": "Describe the mailing list", "access_level": "readonly", "reply_preference": "list", "created_at": "Tue, 09 Aug 2011 20:50:27 -0000", "members_count": 2 } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Mailing list developers@mailgun.net not found" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Mailing Lists" ], "summary": "Delete a mailing list", "description": "Deletes a mailing list", "operationId": "delete-v3-lists-address", "parameters": [ { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "The email address of the mailing list" }, "message": { "type": "string", "description": "Success message" } } }, "examples": { "Example": { "value": { "address": "developers@mailgun.net", "message": "Mailing list has been removed" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Mailing list developers@mailgun.net not found" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "get": { "tags": [ "Mailing Lists" ], "summary": "Get a mailing list by address", "description": "Returns the matching mailing list for the given address", "operationId": "get-v3-lists-address", "parameters": [ { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "$ref": "#/components/schemas/MailingListResponse" } } }, "examples": { "Example": { "value": { "list": { "address": "developers@mailgun.net", "name": "Developers", "description": "Describe the mailing list", "access_level": "readonly", "reply_preference": "list", "created_at": "Tue, 09 Aug 2011 20:50:27 -0000", "members_count": 2 } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Mailing list developers@mailgun.net not found" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/lists/pages": { "get": { "tags": [ "Mailing Lists" ], "summary": "Get mailing lists by page", "description": "Paginate over mailing lists", "operationId": "get-v3-lists-pages", "parameters": [ { "name": "limit", "in": "query", "description": "Set limit for the list length returned. Defaults to 100.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginateMailingListResponse" }, "examples": { "Example": { "value": { "paging": { "first": "https://url_to_first_page", "last": "https://url_to_last_page", "next": "https://url_to_next_page", "previous": "https://url_to_previous_page" }, "items": [ { "access_level": "everyone", "address": "dev@samples.mailgun.org", "created_at": "Tue, 06 Mar 2012 05:44:45 GMT", "description": "Mailgun developers list", "members_count": 1, "name": "" }, { "access_level": "readonly", "address": "bar@example.com", "created_at": "Wed, 06 Mar 2013 11:39:51 GMT", "description": "", "members_count": 2, "name": "" } ] } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/lists/{list_address}/members/pages": { "get": { "tags": [ "Mailing Lists" ], "summary": "Get members by page", "description": "Paginate over list members in a given mailing list in ascending order", "operationId": "get-lists-list_address-members-pages", "parameters": [ { "name": "subscribed", "in": "query", "description": "Filtering list on whether the member is subscribed or not.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Set limit for the list length returned. Defaults to 100.", "schema": { "type": "integer" } }, { "name": "address", "in": "query", "description": "Use as pivot for pagination.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Could be either: first, last, next or prev", "schema": { "type": "string" } }, { "name": "list_address", "in": "path", "description": "The mailing list's address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginateListMemberResponse" }, "examples": { "Example": { "value": { "paging": { "first": "https://url_to_first_page", "last": "https://url_to_last_page", "next": "https://url_to_next_page", "previous": "https://url_to_previous_page" }, "items": [ { "access_level": "everyone", "address": "dev@samples.mailgun.org", "created_at": "Tue, 06 Mar 2012 05:44:45 GMT", "description": "Mailgun developers list", "members_count": 1, "name": "" }, { "access_level": "readonly", "address": "bar@example.com", "created_at": "Wed, 06 Mar 2013 11:39:51 GMT", "description": "", "members_count": 2, "name": "" } ] } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } }, "examples": { "Example": { "value": { "message": "Too Many Requests" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/templates": { "get": { "tags": [ "Domain Templates" ], "summary": "Get templates", "description": "Returns a list of templates for the domain.", "operationId": "GET-v3--domain-name--templates", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name to fetch the templates for.", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Name of the page to retrieve. Value can be `first`, `last`, `next`, or `previous`. Defaults to `first`.", "schema": { "type": "string", "enum": [ "first", "last", "next", "previous" ], "x-enumDescriptions": { "first": "Get the first list's page", "last": "Get the last list's page", "next": "Get the next list's page", "previous": "Get the previous list's page" } } }, { "name": "limit", "in": "query", "description": "Number of templates to retrieve. Default and max limit is 100.", "schema": { "type": "integer" } }, { "name": "p", "in": "query", "description": "Pivot used to retrieve the next page of templates.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-getPageResponse" }, "examples": { "Example": { "value": { "items": [ { "name": "template.0", "description": "Description for template 0", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "id": "48d63154-8c8f-4104-ab14-687d01dbf296" }, { "name": "template.1", "description": "Description for template 1", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "id": "8d9c0f0d-7bf7-43a4-92a9-791a854d12a4" } ], "paging": { "previous": "https://api.mailgun.net/v3/{domain}/templates?page=previous&p=template.0&limit=10", "first": "https://api.mailgun.net/v3/{domain}/templates?limit=10", "next": "https://api.mailgun.net/v3/{domain}/templates?page=next&p=template.2&limit=10", "last": "https://api.mailgun.net/v3/{domain}/templates?page=last&limit=10" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Domain Templates" ], "summary": "Create a template", "description": "Store a new template, including its name, description and (optionally) the template content. If the template content is provided, a new version is automatically created and becomes the active version.", "operationId": "POST-v3--domain-name--templates", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is associated with.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domain_name-templates-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-createTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "template has been stored", "template": { "name": "template_name", "description": "This is the description of the template", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "createdBy": "user-supplied-value", "id": "46565d87-68b6-4edb-8b3c-34554af4bb77", "domain": "header.tld", "version": { "tag": "tag", "template": "template content", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "Version comment", "active": true, "id": "3efd2b85-0f41-4a1d-9898-05d7e7459c4a", "headers": { "From": "from@header.tld", "Reply-To": "reply-to@header.tld", "Subject": "Subject Value" } } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "409": { "description": "A 409 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Domain Templates" ], "summary": "Delete all templates", "description": "Delete all templates and their versions for the domain.", "operationId": "DELETE-v3--domain-name--templates", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is associated with.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "templates have been deleted" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/templates/{template_name}/versions": { "get": { "tags": [ "Domain Templates" ], "summary": "Get all template versions", "description": "Returns a paginated list of template versions.", "operationId": "GET-v3--domain-name--templates--template-name--versions", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name to fetch the templates for.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "Template name to fetch the versions for.", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Name of the page to retrieve. Value can be `first`, `last`, `next`, or `previous`. Defaults to `first`.", "schema": { "type": "string", "enum": [ "first", "last", "next", "previous" ], "x-enumDescriptions": { "first": "Get the first list's page", "last": "Get the last list's page", "next": "Get the next list's page", "previous": "Get the previous list's page" } } }, { "name": "limit", "in": "query", "description": "Number of templates to retrieve. Default and max limit is 100.", "schema": { "type": "integer" } }, { "name": "p", "in": "query", "description": "Pivot used to retrieve the next page of templates.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-getVersionsPageResponse" }, "examples": { "Example": { "value": { "template": { "name": "template_name", "description": "This is the description of the template", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "createdBy": "user-supplied-value", "id": "46565d87-68b6-4edb-8b3c-34554af4bb77", "domain": "example.com", "versions": [ { "tag": "v0", "template": "", "engine": "", "mjml": "", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "version comment", "active": false, "id": "71bd07b8-fe81-4199-8fcf-67c956ccdc34", "headers": {}, "parsedhandlebar": null }, { "tag": "v1", "template": "", "engine": "", "mjml": "", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "version comment", "active": true, "id": "d4a36e91-1b5f-44e0-bf5a-3542ea712b62", "headers": {}, "parsedhandlebar": null }, { "tag": "v2", "template": "", "engine": "", "mjml": "", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "version comment", "active": true, "id": "d4a36e91-1b5f-44e0-bf5a-3542ea712b62", "headers": {}, "parsedhandlebar": null } ] }, "paging": { "previous": "https://api.mailgun.net/v3/{domain}/templates/z4ujt7CiEeik0RJbspqxaQ/versions?page=previous&p=v0&limit=10", "first": "https://api.mailgun.net/v3/{domain}/templates/z4ujt7CiEeik0RJbspqxaQ/versions?limit=10", "next": "https://api.mailgun.net/v3/{domain}/templates/z4ujt7CiEeik0RJbspqxaQ/versions?page=next&p=v2&limit=10", "last": "https://api.mailgun.net/v3/{domain}/templates/z4ujt7CiEeik0RJbspqxaQ/versions?page=last&limit=10" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Domain Templates" ], "summary": "Create a template version", "description": "Adds a new template version. If the template doesn’t contain any other versions, the first version becomes active. A template can store up to 40 versions.", "operationId": "POST-v3--domain-name--templates--template-name--versions", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is associated with.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "Template name to create the new version for.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domain_name-templates-template_name-versions-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-createTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "new version of the template has been stored", "template": { "name": "template_name", "description": "This is the description of the template", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "createdBy": "user-supplied-value", "id": "46565d87-68b6-4edb-8b3c-34554af4bb77", "domain": "header.tld", "version": { "tag": "tag", "template": "template content", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "Version comment", "active": true, "id": "3efd2b85-0f41-4a1d-9898-05d7e7459c4a", "headers": { "From": "from@header.tld", "Reply-To": "reply-to@header.tld", "Subject": "Subject Value" } } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "409": { "description": "A 409 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/templates/{template_name}": { "get": { "tags": [ "Domain Templates" ], "summary": "Get template", "description": "Returns metadata information about the stored template specified in the url. If the active flag is provided, the content of the active version of the template is returned. If the version_name flag is provided, version information will be included as well. By default: the `version` field is not provided. To see available versions other than the active version, use the `/versions` API instead", "operationId": "GET-v3--domain-name--templates--template-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is stored under.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "Template name to fetch.", "required": true, "schema": { "type": "string" } }, { "name": "active", "in": "query", "description": "If this flag is set to yes the active version of the template is included in the response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-getTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "template": { "name": "template_name", "description": "This is the description of the template", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "createdBy": "user-supplied-value", "id": "46565d87-68b6-4edb-8b3c-34554af4bb77", "domain": "header.tld", "version": { "tag": "tag", "template": "template content", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "Version comment", "active": true, "id": "3efd2b85-0f41-4a1d-9898-05d7e7459c4a", "headers": { "From": "from@header.tld", "Reply-To": "reply-to@header.tld", "Subject": "Subject Value" } } } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Domain Templates" ], "summary": "Update template", "description": "Update the description of a template.", "operationId": "PUT-v3--domain-name--templates--template-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is associated with.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "The template name.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v3-domain_name-templates-template_name-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "template has been updated", "template": { "name": "template_name" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Domain Templates" ], "summary": "Delete a template", "description": "Delete the template specified in the url. NOTE: This method deletes all versions of the specified template.", "operationId": "DELETE-v3--domain-name--templates--template-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is associated with.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "Template name to be deleted.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "template has been deleted", "template": { "name": "template_name" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/templates/{template_name}/versions/{version_name}": { "get": { "tags": [ "Domain Templates" ], "summary": "Get a version", "description": "Retrieve the information and content of the specified version of a template.", "operationId": "GET-v3--domain-name--templates--template-name--versions--version-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is stored under.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "Template name the version is for.", "required": true, "schema": { "type": "string" } }, { "name": "version_name", "in": "path", "description": "Tag of the version of the template to fetch.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-getTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "template": { "name": "template_name", "description": "This is the description of the template", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "createdBy": "user-supplied-value", "id": "46565d87-68b6-4edb-8b3c-34554af4bb77", "domain": "header.tld", "version": { "tag": "tag", "template": "template content", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "Version comment", "active": true, "id": "3efd2b85-0f41-4a1d-9898-05d7e7459c4a", "headers": { "From": "from@header.tld", "Reply-To": "reply-to@header.tld", "Subject": "Subject Value" } } } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Domain Templates" ], "summary": "Update a version", "description": "Update information or content of the specific template version. Existing fields not included in the request will not be changed", "operationId": "PUT-v3--domain-name--templates--template-name--versions--version-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is associated with.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "Template name the version is stored under.", "required": true, "schema": { "type": "string" } }, { "name": "version_name", "in": "path", "description": "Tag of the version of the template to be updated", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v3-domain_name-templates-template_name-versions-version_name-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "version has been updated", "template": { "name": "template_name", "version": { "tag": "tag" } } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Domain Templates" ], "summary": "Delete a version", "description": "Delete a specific template version.", "operationId": "DELETE-v3--domain-name--templates--template-name--versions--version-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is associated with.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "Template name the version is stored under.", "required": true, "schema": { "type": "string" } }, { "name": "version_name", "in": "path", "description": "Tag of the version of the template to be deleted.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "version has been deleted", "template": { "name": "template_name", "version": { "tag": "tag" } } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/templates/{template_name}/copy": { "put": { "tags": [ "Domain Templates" ], "summary": "Copy a template", "description": "Copies an existing template into new templates with the provided names and account IDs.", "operationId": "PUT-v3--domain-name--templates--template-name--copy", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is associated with.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "The name of the source template", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-TemplateCopyParams" }, "examples": { "Example": { "value": { "requests": [ { "account_id": "account-id-1", "name": "new-template-name-1" }, { "account_id": "account-id-2", "name": "new-template-name-2", "domain": "target-domain" } ] } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-TemplateCopyResponse" }, "examples": { "Example": { "value": { "message": "Templates have been copied", "failed_copies": [ { "account_id": "account-id-1", "name": "new-template-name-1" }, { "account_id": "account-id-2", "name": "new-template-name-2", "domain": "target-domain" } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-ResponseWithStatus" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/templates/{template_name}/versions/{version_name}/copy/{new_version_name}": { "put": { "tags": [ "Domain Templates" ], "summary": "Copy a version", "description": "Copies an existing version into a new version with the provided name.", "operationId": "PUT-v3--domain-name--templates--template-name--versions--version-name--copy--new-version-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is associated with.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "Template name the version is stored under.", "required": true, "schema": { "type": "string" } }, { "name": "version_name", "in": "path", "description": "Tag of the version to copy.", "required": true, "schema": { "type": "string" } }, { "name": "new_version_name", "in": "path", "description": "The name for the new version. If the version name already exists, the copy will fail.", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "query", "description": "Comment to be used for the new version.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-versionCopyResponse" }, "examples": { "Example": { "value": { "message": "version has been copied", "version": { "tag": "cloned version", "template": "

{{firstname}} {{lastname}}

", "createdAt": "Fri, 21 Mar 2025 15:00:44 UTC", "comment": "a comment value from copy", "id": "95658c55-e93a-40d5-a02f-a4fadfbbb3ca" } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/{domain_name}/templates/{template_name}/rename/{new_template_name}": { "put": { "tags": [ "Domain Templates" ], "summary": "Rename a template", "description": "Renames the specified template", "operationId": "PUT-v3--domain-name--templates--template-name--rename--new-template-name-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Domain name the template is associated with.", "required": true, "schema": { "type": "string" } }, { "name": "template_name", "in": "path", "description": "The current name of the template.", "required": true, "schema": { "type": "string" } }, { "name": "new_template_name", "in": "path", "description": "The name for the new template.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "Template has been renamed", "template": { "name": "new-template-name" } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/templates": { "get": { "tags": [ "Account Templates" ], "summary": "Get account-level templates", "description": "Returns a list of account-level templates.", "operationId": "GET-v4-templates", "parameters": [ { "name": "page", "in": "query", "description": "Name of the page to retrieve. Value can be `first`, `last`, `next`, or `previous`. Defaults to `first`.", "schema": { "type": "string", "enum": [ "first", "last", "next", "previous" ], "x-enumDescriptions": { "first": "Get the first list's page", "last": "Get the last list's page", "next": "Get the next list's page", "previous": "Get the previous list's page" } } }, { "name": "limit", "in": "query", "description": "Number of templates to retrieve. Default and max limit is 100.", "schema": { "type": "integer" } }, { "name": "p", "in": "query", "description": "Pivot used to retrieve the next page of templates.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-getPageResponse" }, "examples": { "Example": { "value": { "items": [ { "name": "template.0", "description": "Description for template 0", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "id": "48d63154-8c8f-4104-ab14-687d01dbf296" }, { "name": "template.1", "description": "Description for template 1", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "id": "8d9c0f0d-7bf7-43a4-92a9-791a854d12a4" } ], "paging": { "previous": "https://api.mailgun.net/v4/templates?page=previous&p=template.0&limit=10", "first": "https://api.mailgun.net/v4/templates?limit=10", "next": "https://api.mailgun.net/v4/templates?page=next&p=template.2&limit=10", "last": "https://api.mailgun.net/v4/templates?page=last&limit=10" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Account Templates" ], "summary": "Create an account-level template", "description": "Store a new account-level template that is available across all domains for the account. Include the template name, description and (optionally) the template content. If the template content is provided, a new version is automatically created and becomes the active version.", "operationId": "POST-v4-templates", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v4-templates-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-createTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "template has been stored", "template": { "name": "template_name", "description": "This is the description of the template", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "createdBy": "user-supplied-value", "id": "46565d87-68b6-4edb-8b3c-34554af4bb77", "domain": "header.tld", "version": { "tag": "tag", "template": "template content", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "Version comment", "active": true, "id": "3efd2b85-0f41-4a1d-9898-05d7e7459c4a", "headers": { "From": "from@header.tld", "Reply-To": "reply-to@header.tld", "Subject": "Subject Value" } } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "409": { "description": "A 409 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Account Templates" ], "summary": "Delete all account-level templates", "description": "Delete all account-level templates and their versions.", "operationId": "DELETE-v4-templates", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "templates have been deleted" } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/templates/{template_name}/versions": { "get": { "tags": [ "Account Templates" ], "summary": "Get all account-level template versions", "description": "Returns a paginated list of versions for an account-level template.", "operationId": "GET-v4-templates--template-name--versions", "parameters": [ { "name": "template_name", "in": "path", "description": "Template name to fetch the versions for.", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Name of the page to retrieve. Value can be `first`, `last`, `next`, or `previous`. Defaults to `first`.", "schema": { "type": "string", "enum": [ "first", "last", "next", "previous" ], "x-enumDescriptions": { "first": "Get the first list's page", "last": "Get the last list's page", "next": "Get the next list's page", "previous": "Get the previous list's page" } } }, { "name": "limit", "in": "query", "description": "Number of versions to retrieve. Default and max limit is 100.", "schema": { "type": "integer" } }, { "name": "p", "in": "query", "description": "Pivot used to retrieve the next page of versions.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-getVersionsPageResponse" }, "examples": { "Example": { "value": { "template": { "name": "template_name", "description": "This is the description of the template", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "createdBy": "user-supplied-value", "id": "46565d87-68b6-4edb-8b3c-34554af4bb77", "domain": "example.com", "versions": [ { "tag": "v0", "template": "", "engine": "", "mjml": "", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "version comment", "active": false, "id": "71bd07b8-fe81-4199-8fcf-67c956ccdc34", "headers": {}, "parsedhandlebar": null }, { "tag": "v1", "template": "", "engine": "", "mjml": "", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "version comment", "active": true, "id": "d4a36e91-1b5f-44e0-bf5a-3542ea712b62", "headers": {}, "parsedhandlebar": null } ] }, "paging": { "previous": "https://api.mailgun.net/v4/templates/my-template/versions?page=previous&p=v0&limit=10", "first": "https://api.mailgun.net/v4/templates/my-template/versions?limit=10", "next": "https://api.mailgun.net/v4/templates/my-template/versions?page=next&p=v1&limit=10", "last": "https://api.mailgun.net/v4/templates/my-template/versions?page=last&limit=10" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Account Templates" ], "summary": "Create an account-level template version", "description": "Adds a new version to an account-level template. If the template doesn't contain any other versions, the first version becomes active. A template can store up to 40 versions.", "operationId": "POST-v4-templates--template-name--versions", "parameters": [ { "name": "template_name", "in": "path", "description": "Template name to create the new version for.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v4-templates-template_name-versions-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-createTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "new version of the template has been stored", "template": { "name": "template_name", "description": "This is the description of the template", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "createdBy": "user-supplied-value", "id": "46565d87-68b6-4edb-8b3c-34554af4bb77", "domain": "header.tld", "version": { "tag": "tag", "template": "template content", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "Version comment", "active": true, "id": "3efd2b85-0f41-4a1d-9898-05d7e7459c4a", "headers": { "From": "from@header.tld", "Reply-To": "reply-to@header.tld", "Subject": "Subject Value" } } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/templates/{template_name}": { "get": { "tags": [ "Account Templates" ], "summary": "Get an account-level template", "description": "Returns metadata information about the stored account-level template. If the active flag is provided, the content of the active version of the template is returned.", "operationId": "GET-v4-templates--template-name-", "parameters": [ { "name": "template_name", "in": "path", "description": "Template name to fetch.", "required": true, "schema": { "type": "string" } }, { "name": "active", "in": "query", "description": "If this flag is set to yes the active version of the template is included in the response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-getTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "template": { "name": "template_name", "description": "This is the description of the template", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "createdBy": "user-supplied-value", "id": "46565d87-68b6-4edb-8b3c-34554af4bb77", "domain": "header.tld", "version": { "tag": "tag", "template": "template content", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "Version comment", "active": true, "id": "3efd2b85-0f41-4a1d-9898-05d7e7459c4a", "headers": { "From": "from@header.tld", "Reply-To": "reply-to@header.tld", "Subject": "Subject Value" } } } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Account Templates" ], "summary": "Update an account-level template", "description": "Update the description of an account-level template.", "operationId": "PUT-v4-templates--template-name-", "parameters": [ { "name": "template_name", "in": "path", "description": "The template name.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v4-templates-template_name-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "template has been updated", "template": { "name": "template_name" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Account Templates" ], "summary": "Delete an account-level template", "description": "Delete the account-level template specified in the url NOTE: This method deletes all versions of the specified template.", "operationId": "DELETE-v4-templates--template-name-", "parameters": [ { "name": "template_name", "in": "path", "description": "Template name to be deleted.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "template has been deleted", "template": { "name": "template_name" } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/templates/{template_name}/versions/{version_name}": { "get": { "tags": [ "Account Templates" ], "summary": "Get an account-level template version", "description": "Retrieve the information and content of the specified version of an account-level template.", "operationId": "GET-v4-templates--template-name--versions--version-name-", "parameters": [ { "name": "template_name", "in": "path", "description": "Template name the version is for.", "required": true, "schema": { "type": "string" } }, { "name": "version_name", "in": "path", "description": "Tag of the version of the template to fetch.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-getTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "template": { "name": "template_name", "description": "This is the description of the template", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "createdBy": "user-supplied-value", "id": "46565d87-68b6-4edb-8b3c-34554af4bb77", "domain": "header.tld", "version": { "tag": "tag", "template": "template content", "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC", "comment": "Version comment", "active": true, "id": "3efd2b85-0f41-4a1d-9898-05d7e7459c4a", "headers": { "From": "from@header.tld", "Reply-To": "reply-to@header.tld", "Subject": "Subject Value" } } } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Account Templates" ], "summary": "Update an account-level template version", "description": "Update information or content of the specific version of an account-level template. Existing fields not included in the request will not be changed.", "operationId": "PUT-v4-templates--template-name--versions--version-name-", "parameters": [ { "name": "template_name", "in": "path", "description": "Template name the version is stored under.", "required": true, "schema": { "type": "string" } }, { "name": "version_name", "in": "path", "description": "Tag of the version of the template to be updated.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v4-templates-template_name-versions-version_name-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "version has been updated", "template": { "name": "template_name", "version": { "tag": "tag" } } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Account Templates" ], "summary": "Delete an account-level template version", "description": "Delete a specific version of an account-level template.", "operationId": "DELETE-v4-templates--template-name--versions--version-name-", "parameters": [ { "name": "template_name", "in": "path", "description": "Template name the version is stored under.", "required": true, "schema": { "type": "string" } }, { "name": "version_name", "in": "path", "description": "Tag of the version of the template to be deleted.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "version has been deleted", "template": { "name": "template_name", "version": { "tag": "tag" } } } } } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/templates/{template_name}/copy": { "put": { "tags": [ "Account Templates" ], "summary": "Copy a template", "description": "Copies an existing template into new templates with the provided names and account IDs.", "operationId": "PUT-v4-templates--template-name--copy", "parameters": [ { "name": "template_name", "in": "path", "description": "The name of the source template", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-TemplateCopyParams" }, "examples": { "Example": { "value": { "requests": [ { "account_id": "account-id-1", "name": "new-template-name-1" }, { "account_id": "account-id-2", "name": "new-template-name-2", "domain": "target-domain" } ] } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-TemplateCopyResponse" }, "examples": { "Example": { "value": { "message": "Templates have been copied", "failed_copies": [ { "account_id": "account-id-1", "name": "new-template-name-1" }, { "account_id": "account-id-2", "name": "new-template-name-2", "domain": "target-domain" } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/templates/{template_name}/versions/{version_name}/copy/{new_version_name}": { "put": { "tags": [ "Account Templates" ], "summary": "Copy an account-level template version", "description": "Copies an existing version of an account-level template into a new version with the provided name.", "operationId": "PUT-v4-templates--template-name--versions--version-name--copy--new-version-name-", "parameters": [ { "name": "template_name", "in": "path", "description": "Template name the version is stored under.", "required": true, "schema": { "type": "string" } }, { "name": "version_name", "in": "path", "description": "Tag of the version to copy.", "required": true, "schema": { "type": "string" } }, { "name": "new_version_name", "in": "path", "description": "The name for the new version. If the version name already exists, the copy will fail.", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "query", "description": "Comment to be used for the new version.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-versionCopyResponse" }, "examples": { "Example": { "value": { "message": "version has been copied", "version": { "tag": "cloned version", "template": "

{{firstname}} {{lastname}}

", "createdAt": "Fri, 21 Mar 2025 15:00:44 UTC", "comment": "a comment value from copy", "id": "95658c55-e93a-40d5-a02f-a4fadfbbb3ca" } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v4/templates/{template_name}/rename/{new_template_name}": { "put": { "tags": [ "Account Templates" ], "summary": "Rename a template", "description": "Renames the specified account level template", "operationId": "PUT-v4-templates--template-name--rename--new-template-name-", "parameters": [ { "name": "template_name", "in": "path", "description": "The current name of the template.", "required": true, "schema": { "type": "string" } }, { "name": "new_template_name", "in": "path", "description": "The name for the new template.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse" }, "examples": { "Example": { "value": { "message": "Template has been renamed", "template": { "name": "new-template-name" } } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "401": { "description": "A 401 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "500": { "description": "A 500 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts": { "put": { "tags": [ "Account Management" ], "summary": "Update variable account settings", "description": "Update variable account settings", "operationId": "put-v5-accounts", "parameters": [ { "name": "name", "in": "query", "description": "The new account organization name", "required": false, "schema": { "type": "string" } }, { "name": "inactive_session_timeout", "in": "query", "description": "The login session timeout period for inactivity", "required": false, "schema": { "type": "integer" } }, { "name": "absolute_session_timeout", "in": "query", "description": "The login session timeout period limit", "required": false, "schema": { "type": "integer" } }, { "name": "logout_redirect_url", "in": "query", "description": "The url to redirect to upon logout", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully updated the account setting(s)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Account info has been updated" } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Either `name`, `absolute_timeout`, `inactive_timeout`, or `logout_redirect_url` must be provided to update account info." } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/http_signing_key": { "get": { "tags": [ "Account Management" ], "summary": "Get webhook signing key saved on the account", "description": "Get webhook signing key saved on the account", "operationId": "get-v5-accounts-http_signing_key", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-HTTPSigningKey" }, "examples": { "Example": { "value": { "http_signing_key": "key-55c5c5c5c55f55ca5cd5f55d5c555c55" } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "could not get HSK for account" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Account Management" ], "summary": "Create or regenerate webhook signing key on an account", "description": "Create or regenerate webhook signing key on an account", "operationId": "post-v5-accounts-http_signing_key", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-HTTPSigningKey" }, "examples": { "Example": { "value": { "message": "regenerated HTTP signing key for account", "http_signing_key": "key-55c5c5c5c55f55ca5cd5f55d5c555c55" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/sandbox/auth_recipients": { "get": { "tags": [ "Account Management" ], "summary": "Get authorized email recipients for a sandbox domain", "description": "Get webhook signing key saved on the account", "operationId": "get-v5-sandbox-auth_recipients", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-RecipientResponse" } } } }, "examples": { "Example": { "value": { "recipients": [ { "email": "test_recipient@sandbox.com", "activated": true } ] } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Account Management" ], "summary": "Add authorized email recipient for a sandbox domain", "description": "Add authorized email recipient for a sandbox domain", "operationId": "post-v5-sandbox-auth_recipients", "parameters": [ { "name": "email", "in": "query", "description": "The email address of the new recipient", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-RecipientResponse" } } }, "examples": { "Example": { "value": { "recipient": { "email": "test_recipient@sandbox.com", "activated": false } } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Only 5 sandbox recipients are allowed" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/sandbox/auth_recipients/{email}": { "delete": { "tags": [ "Account Management" ], "summary": "Remove an authorized sandbox domain email recipient", "description": "Remove an authorized sandbox domain email recipient", "operationId": "delete-v5-sandbox-auth_recipients-email", "parameters": [ { "name": "email", "in": "path", "description": "The email address of the authorized recipient to be removed", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Sandbox recipient deleted." } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Invalid email address." } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/resend_activation_email": { "post": { "tags": [ "Account Management" ], "summary": "Resend account activation email to the account owner", "description": "Resend account activation email to the account owner", "operationId": "post-v5-accounts-resend_activation_email", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericSuccess" }, "examples": { "Example": { "value": { "success": true } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/subaccounts/{subaccount_id}": { "get": { "tags": [ "Subaccounts" ], "summary": "Get a single subaccount", "description": "Fetch the details of a single subaccount", "operationId": "get-v5-accounts-subaccounts-subaccount_id", "parameters": [ { "name": "subaccount_id", "in": "path", "description": "The ID of the subaccount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-SubaccountResponse" }, "examples": { "Example": { "value": { "subaccount": { "id": "123", "name": "My subaccount", "created_at": "Wed, 06 Nov 2024 19:48:29 GMT", "updated_at": "Wed, 28 May 2025 20:03:05 GMT", "status": "open" } } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Not Found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/subaccounts": { "get": { "tags": [ "Subaccounts" ], "summary": "List all subaccounts", "description": "Fetch all subaccounts", "operationId": "get-v5-accounts-subaccounts", "parameters": [ { "name": "sort", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "asc", "desc" ], "x-enumDescriptions": { "asc": "Sort by ascending order of name field", "desc": "Sort by descending order of name field" } }, "required": false }, { "name": "filter", "in": "query", "description": "Name of account to filter by", "schema": { "type": "string" }, "required": false }, { "name": "limit", "in": "query", "description": "Number of subaccounts to return", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 1000 }, "required": false }, { "name": "skip", "in": "query", "description": "Number of subaccounts to skip", "schema": { "type": "integer", "default": 0 }, "required": false }, { "name": "enabled", "in": "query", "description": "Indicate to include enabled subaccounts (true) or disabled accounts (false). Leave unspecified to allow for either, depending on other parameters provided.", "schema": { "type": "boolean" }, "required": false }, { "name": "closed", "in": "query", "description": "Indicate to include closed subaccounts (true) or exclude closed accounts (false). Leave unspecified to allow for either, depending on other parameters provided.", "schema": { "type": "boolean" }, "required": false } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-SubaccountListResponse" }, "examples": { "Example": { "value": { "subaccounts": [ { "id": "123", "name": "My subaccount", "status": "open", "created_at": "Wed, 06 Nov 2024 19:48:29 GMT", "updated_at": "Wed, 28 May 2025 20:03:05 GMT" } ], "total": 1 } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Subaccounts" ], "summary": "Create a subaccount", "description": "Create a subaccount", "operationId": "post-v5-accounts-subaccounts", "parameters": [ { "name": "name", "in": "query", "description": "The name of the subaccount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully created a subaccount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-SubaccountResponse" }, "examples": { "Example": { "value": { "subaccount": { "id": "123", "name": "My subaccount", "created_at": "Wed, 06 Nov 2024 19:48:29 GMT", "updated_at": "Wed, 28 May 2025 20:03:05 GMT", "status": "open" } } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Bad request" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Subaccounts" ], "summary": "Delete a subaccount", "description": "Delete a subaccount", "operationId": "delete-v5-accounts-subaccounts-subaccount_id", "parameters": [ { "name": "X-Mailgun-On-Behalf-Of", "in": "header", "description": "The ID of the subaccount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Subaccount successfully deleted" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Bad request" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Forbidden" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/subaccounts/{subaccount_id}/disable": { "post": { "tags": [ "Subaccounts" ], "summary": "Disable a subaccount", "description": "Disable a subaccount", "operationId": "post-v5-accounts-subaccounts-subaccount_id-disable", "parameters": [ { "name": "subaccount_id", "in": "path", "description": "The ID of the subaccount", "required": true, "schema": { "type": "string" } }, { "name": "reason", "in": "query", "description": "The reason for disabling the subaccount", "required": false, "schema": { "type": "string" } }, { "name": "note", "in": "query", "description": "A note for the subaccount", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subaccount disabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-SubaccountResponse" }, "examples": { "Example": { "value": { "subaccount": { "id": "123", "name": "My subaccount", "created_at": "Wed, 06 Nov 2024 19:48:29 GMT", "updated_at": "Wed, 28 May 2025 20:03:05 GMT", "status": "disabled" } } } } } } }, "400": { "description": "Subaccount is already disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "subaccount is already disabled" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Not Found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/subaccounts/{subaccount_id}/enable": { "post": { "tags": [ "Subaccounts" ], "summary": "Enable a subaccount", "description": "Enable a subaccount", "operationId": "post-v5-accounts-subaccounts-subaccount_id-enable", "parameters": [ { "name": "subaccount_id", "in": "path", "description": "The ID of the subaccount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subaccount enabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-SubaccountResponse" }, "examples": { "Example": { "value": { "subaccount": { "id": "123", "name": "My subaccount", "created_at": "Wed, 06 Nov 2024 19:48:29 GMT", "updated_at": "Wed, 28 May 2025 20:03:05 GMT", "status": "open" } } } } } } }, "400": { "description": "Cannot enable due to limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Parent account has reached its allotted child limit" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Not Found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/subaccounts/{subaccount_id}/limit/custom/monthly": { "get": { "tags": [ "Subaccounts" ], "summary": "Get current custom sending limit", "description": "Fetch the details of custom sending limit on the account", "operationId": "get-v5-accounts-subaccounts-subaccount_id-limit-custom-monthly", "parameters": [ { "name": "subaccount_id", "in": "path", "description": "The ID of the subaccount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-CustomMessageLimitResponse" }, "examples": { "Example": { "value": { "limit": 10000, "current": 0, "period": "1m" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Not a subaccount" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Forbidden - user does not have permission to view this resource" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "No threshold for account" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Subaccounts" ], "summary": "Set a custom sending limit", "description": "Set a custom sending limit", "operationId": "put-v5-accounts-subaccounts-subaccount_id-limit-custom-monthly", "parameters": [ { "name": "subaccount_id", "in": "path", "description": "The ID of the subaccount", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The limit to set", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Successfully set the sending limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericSuccess" }, "examples": { "Example": { "value": { "success": true } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Invalid subaccount ID" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Subaccounts" ], "summary": "Delete a custom sending limit", "description": "Delete a custom sending limit", "operationId": "delete-v5-accounts-subaccounts-subaccount_id-limit-custom-monthly", "parameters": [ { "name": "subaccount_id", "in": "path", "description": "The ID of the subaccount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully deleted the sending limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericSuccess" }, "examples": { "Example": { "value": { "success": true } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Could not delete threshold for account" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/limit/custom/monthly": { "get": { "tags": [ "Custom Message Limit" ], "summary": "Get current custom sending limit", "description": "Fetch the details of custom sending limit on the account", "operationId": "get-v5-accounts-limit-custom-monthly", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-CustomMessageLimitResponse" }, "examples": { "Example": { "value": { "limit": 10000, "current": 0, "period": "1m" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "No threshold for account" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Custom Message Limit" ], "summary": "Set a custom sending limit", "description": "Set a custom sending limit", "operationId": "put-v5-accounts-limit-custom-monthly", "parameters": [ { "name": "limit", "in": "query", "description": "The limit to set", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Successfully set the sending limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericSuccess" }, "examples": { "Example": { "value": { "success": true } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "The limit parameter minumum is 1000" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Custom Message Limit" ], "summary": "Delete a custom sending limit", "description": "Delete a custom sending limit", "operationId": "delete-v5-accounts-limit-custom-monthly", "responses": { "200": { "description": "Successfully deleted the sending limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericSuccess" }, "examples": { "Example": { "value": { "success": true } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Could not delete threshold for account" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/limit/custom/enable": { "put": { "tags": [ "Custom Message Limit" ], "summary": "Re-enable account disabled for hitting send limit", "description": "Re-enable an account that was disabled for reaching the custom sending limit", "operationId": "put-v5-accounts-limit-custom-enable", "responses": { "200": { "description": "Successfully re-enabled the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericSuccess" }, "examples": { "Example": { "value": { "success": true } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Unable to re-enable account with current account disablement" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/accounts/subaccounts/{subaccount_id}/features": { "put": { "tags": [ "Subaccounts" ], "summary": "Update subaccount feature", "description": "Update subaccount feature", "operationId": "put-v5-accounts-subaccounts-subaccount_id-features", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "email_preview": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-FeatureOverrideEnabledParam" }, "inbox_placement": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-FeatureOverrideEnabledParam" }, "sending": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-FeatureOverrideEnabledParam" }, "validations": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-FeatureOverrideEnabledParam" }, "validations_bulk": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-FeatureOverrideEnabledParam" } } }, "encoding": { "email_preview": { "contentType": "application/json" }, "inbox_placement": { "contentType": "application/json" }, "sending": { "contentType": "application/json" }, "validations": { "contentType": "application/json" }, "validations_bulk": { "contentType": "application/json" } } } } }, "parameters": [ { "name": "subaccount_id", "in": "path", "description": "The ID of the subaccount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully updated subaccount features", "content": { "application/json": { "schema": { "type": "object", "properties": { "features": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-FeaturesResponse" } } }, "examples": { "Example": { "value": { "features": { "validations": { "enabled": true } } } } } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "No valid updates provided" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-GenericMessage" }, "examples": { "Example": { "value": { "message": "Not Found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/keys": { "get": { "tags": [ "Keys" ], "summary": "List Mailgun API keys", "description": "List Mailgun API keys", "operationId": "GET-v1-keys", "parameters": [ { "name": "domain_name", "in": "query", "description": "Domain name filter for domain keys", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Key kind filter", "schema": { "type": "string", "enum": [ "domain", "user", "web" ], "x-enumDescriptions": { "domain": "Filter for domain keys", "user": "Filter for user keys", "web": "Filter for web keys" } } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-keys-KeysResp" }, "examples": { "Example": { "value": { "total_count": 1, "items": [ { "id": "e2153fd0-e0277777", "description": "api key", "kind": "user", "role": "admin", "created_at": "2006-01-02T15:04:05", "updated_at": "2006-01-02T15:04:05", "requestor": "janedoe@example.com", "user_name": "Jane Doe", "domain_name": null, "is_disabled": false } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "expected `kind` param to be one of [domain user web] or absent" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Keys" ], "summary": "Create Mailgun API key", "description": "Create Mailgun API key", "operationId": "POST-v1-keys", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v1-keys-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-keys-CreateKeyResp" }, "examples": { "Example": { "value": { "message": "great success", "key": { "id": "f2153fd0-f1277777", "description": "api key", "kind": "domain", "role": "sending", "created_at": "2006-01-02T15:04:05", "updated_at": "2006-01-02T15:04:05", "requestor": null, "user_name": null, "domain_name": "example.com", "is_disabled": false, "secret": "api-key-be-careful" } } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "could not create key, account limit reached" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/keys/{key_id}": { "delete": { "tags": [ "Keys" ], "summary": "Delete Mailgun API key", "description": "Delete Mailgun API key", "operationId": "DELETE-v1-keys--key-id-", "parameters": [ { "name": "key_id", "in": "path", "description": "The Key ID generated by Mailgun on key creation", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "key deleted" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "no key matching id" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/keys/public": { "post": { "tags": [ "Keys" ], "summary": "Regenerate Mailgun Public API key", "description": "Regenerate Mailgun Public API key", "operationId": "POST-v1-keys-public", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-keys-PublicKeyResp" }, "examples": { "Example": { "value": { "key": "pubkey-626b31f321228ddddddddddcc5a7a1c9", "message": "The public API key has been successfully regenerated." } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Forbidden" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{domain_name}/credentials": { "get": { "tags": [ "Credentials" ], "summary": "List Mailgun SMTP credential metadata for a given domain", "description": "List Mailgun SMTP credential metadata for a given domain", "operationId": "GET-v3-domains--domain-name--credentials", "parameters": [ { "name": "domain_name", "in": "path", "description": "Hostname filter for credential results", "required": true, "schema": { "type": "string" } }, { "name": "skip", "in": "query", "description": "Number of results to skip, to help with pagination", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "description": "Limit results to this many", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-credentials-ListCredsResp" }, "examples": { "Example": { "value": { "items": [ { "mailbox": "someone@example.com", "login": "someone@example.com", "created_at": "Wed, 08 Mar 2023 23:34:57 +0000", "size_bytes": null } ], "total_count": 1 } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Limit parameter can't be larger than 1000" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Credentials" ], "summary": "Create Mailgun SMTP credentials for a given domain", "description": "Create Mailgun SMTP credentials for a given domain", "operationId": "POST-v3-domains--domain-name--credentials", "parameters": [ { "name": "domain_name", "in": "path", "description": "Hostname for new credentials", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v3-domains-domain_name-credentials-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-credentials-CreateCredsResp" }, "examples": { "Example": { "value": { "message": "Created 1 credentials pair(s)" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Parameter 'login' is missing" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Credentials" ], "summary": "Delete all Mailgun SMTP credentials for a domain", "description": "Delete Mailgun SMTP credentials for a given domain", "operationId": "DELETE-v3-domains--domain-name--credentials", "parameters": [ { "name": "domain_name", "in": "path", "description": "Hostname of credentials to be deleted", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-credentials-DeleteDomainCredsResp" }, "examples": { "Example": { "value": { "message": "All domain credentials have been deleted", "count": 2 } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "an error occurred, please try again later" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v3/domains/{domain_name}/credentials/{spec}": { "put": { "tags": [ "Credentials" ], "summary": "Update Mailgun SMTP credentials", "description": "Update Mailgun SMTP credentials for a given domain and SMTP user", "operationId": "PUT-v3-domains--domain-name--credentials--spec-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Hostname of credentials to be updated", "required": true, "schema": { "type": "string" } }, { "name": "spec", "in": "path", "description": "Login specification of credentials to be updated (email address)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v3-domains-domain_name-credentials-spec-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-credentials-CreateCredsResp" }, "examples": { "Example": { "value": { "message": "Created 1 credentials pair(s)" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Credentials not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Credentials" ], "summary": "Delete Mailgun SMTP credentials", "description": "Delete Mailgun SMTP credentials for a given domain and SMTP user", "operationId": "DELETE-v3-domains--domain-name--credentials--spec-", "parameters": [ { "name": "domain_name", "in": "path", "description": "Hostname of credentials to be deleted", "required": true, "schema": { "type": "string" } }, { "name": "spec", "in": "path", "description": "Login specification of credentials to be deleted (email address)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-credentials-DeleteCredsResp" }, "examples": { "Example": { "value": { "message": "Credentials have been deleted", "spec": "someone@example.com" } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Cannot delete system mailbox: postmaster@example.com" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v2/ip_whitelist": { "get": { "tags": [ "IP Allowlist" ], "summary": "List Mailgun account IP allowlist entries", "description": "List Mailgun account IP allowlist entries", "operationId": "GET-v2-ip-whitelist", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-whitelist-V2WhitelistResp" }, "examples": { "Example": { "value": { "addresses": [ { "ip_address": "10.11.11.111", "description": "OnPrem Server" } ] } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Forbidden" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "IP Allowlist" ], "summary": "Update individual Mailgun account IP allowlist entry's description", "description": "Update individual Mailgun account IP allowlist entry's description", "operationId": "PUT-v2-ip-whitelist", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PUT-v2-ip_whitelist-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-whitelist-V2WhitelistResp" }, "examples": { "Example": { "value": { "addresses": [ { "ip_address": "10.11.11.111", "description": "OnPrem Server 1" } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "IP not found" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "IP Allowlist" ], "summary": "Add Mailgun account IP allowlist entry", "description": "Add Mailgun account IP allowlist entry", "operationId": "POST-v2-ip-whitelist", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/POST-v2-ip_whitelist-multipart-form-data-RequestBody" } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-whitelist-V2WhitelistResp" }, "examples": { "Example": { "value": { "addresses": [ { "ip_address": "10.11.11.111", "description": "OnPrem Server" } ] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "Invalid IP Address or CIDR" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "IP Allowlist" ], "summary": "Delete Mailgun account IP allowlist entry", "description": "Delete Mailgun account IP allowlist entry", "operationId": "DELETE-v2-ip-whitelist", "parameters": [ { "name": "address", "in": "query", "description": "Address to be deleted from allowlist", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-whitelist-V2WhitelistResp" }, "examples": { "Example": { "value": { "addresses": [] } } } } } }, "400": { "description": "A 400 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" }, "examples": { "Example": { "value": { "message": "IP address can not be blank" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v1/bounce-classification/stats": { "get": { "tags": [ "Bounce Classification" ], "summary": "List statistics, ordered by total bounces", "description": "Deprecated: use POST /v2/bounce-classification/metrics instead", "operationId": "GET-v1-bounce-classification-stats", "parameters": [ { "name": "group", "in": "query", "description": "Group response by fields: subaccount.id, domain.name, entity-id, rule-id", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limits the number of items returned in a response", "schema": { "type": "integer" } }, { "name": "include_subaccounts", "in": "query", "description": "Include subaccounts", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-ListStatsResp" }, "examples": { "Example": { "value": { "items": [ { "subaccount": { "id": "subaccount_id" }, "domain": { "name": "example.com" }, "rule-id": "55ff", "entity-id": "spamhaus", "short-explanation": "You're listed on Spamhaus!", "bounced": { "total": 4 } } ], "_duration": "0s" } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v1/bounce-classification/domains": { "get": { "tags": [ "Bounce Classification" ], "summary": "List domains statistic per account", "description": "Deprecated: use POST /v2/bounce-classification/metrics", "operationId": "GET-v1-bounce-classification-domains", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of items returned in a response", "schema": { "type": "integer" } }, { "name": "skip", "in": "query", "description": "Skips N items in a response", "schema": { "type": "integer" } }, { "name": "query", "in": "query", "description": "Query filter, e.g.: 'domain.name:example.com'", "schema": { "type": "string" } }, { "name": "include_subaccounts", "in": "query", "description": "Include subaccounts", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-ListAccountStatsResp" }, "examples": { "Example": { "value": { "items": [ { "domain": { "name": "mailgun.net" }, "bounced": { "total": 4 } } ], "total": 1 } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v1/bounce-classification/domains/{domain}/entities": { "get": { "tags": [ "Bounce Classification" ], "summary": "List statistic per domain", "description": "Deprecated: use POST /v2/bounce-classification/metrics", "operationId": "GET-v1-bounce-classification-domains--domain--entities", "parameters": [ { "name": "domain", "in": "path", "description": "The sender domain name", "required": true, "schema": { "type": "string" } }, { "name": "include_subaccounts", "in": "query", "description": "Include subaccounts", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-ListDomainStatsResp" }, "examples": { "Example": { "value": { "items": [ { "entity-id": "gmail", "entity-name": "Gmail", "bounced": { "total": 1 } }, { "entity-id": "hotmail", "entity-name": "Microsoft (Hotmail)", "bounced": { "total": 3 } } ] } } } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v1/bounce-classification/domains/{domain}/entities/{entity-id}/rules": { "get": { "tags": [ "Bounce Classification" ], "summary": "List statistic per entity", "description": "Deprecated: use POST /v2/bounce-classification/metrics", "operationId": "GET-v1-bounce-classification-domains--domain--entities--entity-id--rules", "parameters": [ { "name": "domain", "in": "path", "description": "The sender domain name", "required": true, "schema": { "type": "string" } }, { "name": "entity-id", "in": "path", "description": "The entity ID(Email Service Entity or Spam Filter / BL)", "required": true, "schema": { "type": "string" } }, { "name": "include_subaccounts", "in": "query", "description": "Include subaccounts", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-ListEntityStatsResp" }, "examples": { "Example": { "value": { "items": [ { "rule-id": "55ff", "category": "ESPBLOCK", "severity": "PERMANENT", "sample-text": "5.4.1 recipient address rejected: access denied.", "explanation": "Access denied", "bounced": { "total": 3 } } ] } } } } } }, "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v1/bounce-classification/domains/{domain}/events": { "get": { "tags": [ "Bounce Classification" ], "summary": "List Bounce Logs", "description": "Deprecated: use POST /v1/analytics/logs - https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/logs", "operationId": "GET-v1-bounce-classification-domains--domain--events", "parameters": [ { "name": "domain", "in": "path", "description": "The sender domain name", "required": true, "schema": { "type": "string" } }, { "name": "rule-id", "in": "query", "description": "Optional if 'page' is passed", "schema": { "type": "string" } }, { "name": "entity-id", "in": "query", "description": "The entity ID(Email Service Entity or Spam Filter / BL)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort field and order. Default is '@timestamp:asc'", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Encoded paging information, provided via 'next', 'previous' links", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limits the number of items returned in a response", "schema": { "type": "integer" } } ], "responses": { "403": { "description": "A 403 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } }, "410": { "description": "A 410 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse" } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v1/bounce-classification/config/entities": { "get": { "tags": [ "Bounce Classification" ], "summary": "List entities", "description": "Deprecated: use POST /v2/bounce-classification/metrics", "operationId": "GET-v1-bounce-classification-config-entities", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-config-Entities" }, "examples": { "Example": {} } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v1/bounce-classification/config/rules": { "get": { "tags": [ "Bounce Classification" ], "summary": "List rules", "description": "Deprecated: use GET /v2/bounce-classification/config/groups/{group-id}", "operationId": "GET-v1-bounce-classification-config-rules", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-config-Rules" }, "examples": { "Example": {} } } } } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/v2/bounce-classification/metrics": { "post": { "tags": [ "Bounce Classification" ], "summary": "List statistic v2", "description": "Items that have no bounces and no delays(classified_failures_count==0) are not returned.", "operationId": "POST-v2-bounce-classification-metrics", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-MetricsRequest" }, "examples": { "Example": { "value": { "start": "Sun, 01 Jan 2006 22:04:05 UTC", "end": "Mon, 02 Jan 2006 22:04:05 UTC", "resolution": "day", "duration": "24h0m0s", "dimensions": [ "entity-name", "domain.name" ], "metrics": [ "critical_bounce_count", "non_critical_bounce_count", "critical_delay_count", "non_critical_delay_count", "delivered_smtp_count", "classified_failures_count", "critical_bounce_rate", "non_critical_bounce_rate", "critical_delay_rate", "non_critical_delay_rate" ], "filter": { "AND": [ { "attribute": "domain.name", "comparator": "=", "values": [ { "value": "example.com" } ] } ] }, "include_subaccounts": true, "pagination": { "sort": "entity-name:asc", "limit": 10 } } } } } }, "required": true }, "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-MetricsResponse" }, "examples": { "Example": { "value": { "start": "Sun, 01 Jan 2006 22:04:05 +0000", "end": "Mon, 02 Jan 2006 22:04:05 +0000", "resolution": "day", "duration": "24h0m0s", "dimensions": [ "entity-name", "domain.name" ], "pagination": { "sort": "entity-name:asc", "limit": 10, "total": 1 }, "items": [ { "account.name": "subaccount name", "entity-name": "Gmail", "domain.name": "example.com", "envelope.i-ip-pool-name": "default", "envelope.sending-ip": "1.2.3.4", "timestamp": "Mon, 02 Jan 2006 22:04:05 +0000", "tags": "daily, campaign1", "metrics": { "critical_bounce_count": 10, "non_critical_bounce_count": 20, "critical_delay_count": 30, "non_critical_delay_count": 40, "classified_failures_count": 100, "delivered_smtp_count": 1000, "critical_bounce_rate": 1, "non_critical_bounce_rate": 2, "critical_delay_rate": 3, "non_critical_delay_rate": 4 } } ] } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/users": { "get": { "tags": [ "Users" ], "summary": "Get users on an account", "description": "Get users on an account", "operationId": "get-v5-users", "parameters": [ { "name": "role", "in": "query", "description": "The user role by which to filter results (basic == analyst)", "required": false, "schema": { "type": "string", "enum": [ "basic", "billing", "support", "developer", "admin" ], "x-enumDescriptions": { "basic": "Basic/Analyst user role", "billing": "Billing user role", "support": "Support user role", "developer": "Developer user role", "admin": "Admin user role" } } }, { "name": "limit", "in": "query", "description": "The number of users to return", "required": false, "schema": { "type": "integer" } }, { "name": "skip", "in": "query", "description": "The number of users to skip", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-users-api-UserListResponse" }, "examples": { "Example": { "value": { "users": [ { "id": "123", "name": "John Doe", "activated": true, "is_disabled": false, "email": "johndoe@example.com", "email_details": { "address": "johndoe@example.com", "is_valid": true, "parts": { "local_part": "johndoe", "domain": "example.com" } }, "role": "basic", "account_id": "567", "opened_ip": "67.111.60.111", "is_master": true, "metadata": {}, "tfa_enabled": true, "tfa_active": true, "tfa_created_at": "2022-12-20T16:52:01.892000", "password_updated_at": "2022-12-20T16:52:01.892000", "preferences": { "programming_language": "curl", "time_format": "%m/%d/%y %I:%M %p", "time_zone": "US/Eastern" }, "auth": { "method": "sinch", "prior_details": {}, "prior_method": "" }, "github_user_id": null, "salesforce_user_id": null, "migration_status": "done" } ], "total": 1 } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/users/{user_id}": { "get": { "tags": [ "Users" ], "summary": "Get a user's details", "description": "Get details for a user on the account", "operationId": "get-v5-users-user_id", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user on the account", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-users-api-UserResponse" }, "examples": { "Example": { "value": { "id": "123", "name": "John Doe", "activated": true, "is_disabled": false, "email": "johndoe@example.com", "email_details": { "address": "johndoe@example.com", "is_valid": true, "parts": { "local_part": "johndoe", "domain": "example.com" } }, "role": "basic", "account_id": "567", "opened_ip": "67.111.60.111", "is_master": true, "metadata": {}, "tfa_enabled": true, "tfa_active": true, "tfa_created_at": "2022-12-20T16:52:01.892000", "password_updated_at": "2022-12-20T16:52:01.892000", "preferences": { "programming_language": "curl", "time_format": "%m/%d/%y %I:%M %p", "time_zone": "US/Eastern" }, "auth": { "method": "sinch", "prior_details": {}, "prior_method": "" }, "github_user_id": null, "salesforce_user_id": null, "migration_status": "done" } } } } } }, "404": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-users-api-GenericResponse" }, "examples": { "Example": { "value": { "message": "No such user exists" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/v5/users/me": { "get": { "tags": [ "Users" ], "summary": "Get one's own user details", "description": "Get one's own user details, requires use of an API key with a `user_id` saved on it, typically of 'web' kind", "operationId": "get-v5-users-me", "responses": { "200": { "description": "A 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-users-api-UserResponse" }, "examples": { "Example": { "value": { "id": "123", "name": "John Doe", "activated": true, "is_disabled": false, "email": "johndoe@example.com", "email_details": { "address": "johndoe@example.com", "is_valid": true, "parts": { "local_part": "johndoe", "domain": "example.com" } }, "role": "basic", "account_id": "567", "opened_ip": "67.111.60.111", "is_master": true, "metadata": {}, "tfa_enabled": true, "tfa_active": true, "tfa_created_at": "2022-12-20T16:52:01.892000", "password_updated_at": "2022-12-20T16:52:01.892000", "preferences": { "programming_language": "curl", "time_format": "%m/%d/%y %I:%M %p", "time_zone": "US/Eastern" }, "auth": { "method": "sinch", "prior_details": {}, "prior_method": "" }, "github_user_id": null, "salesforce_user_id": null, "migration_status": "done" } } } } } }, "403": { "description": "A 404 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github.com-mailgun-users-api-GenericResponse" }, "examples": { "Example": { "value": { "message": "Incompatible key for this endpoint" } } } } } } }, "security": [ { "basicAuth": [] } ] } } }, "components": { "schemas": { "github.com-mailgun-influx-httpapi-SendMessageResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the message as defined by [RFC-2392](https://datatracker.ietf.org/doc/html/rfc2392)." }, "message": { "type": "string", "description": "A success message" } }, "required": [ "id", "message" ] }, "github.com-mailgun-influx-httpapi-GetMessageResponseNotFound": { "type": "object", "properties": { "message": { "type": "string", "description": "A failure message" } }, "required": [ "message" ] }, "string": { "type": "string" }, "POST-v3-domain_name-messages-multipart-form-data-RequestBody": { "type": "object", "properties": { "from": { "type": "string", "description": "Email address of the `From` header. Can include a friendly name using the format `\"Friendly Name \"`. Note: not required if sending with a template that has a pre-set From header, but will override the template's From header if provided." }, "to": { "type": "array", "items": { "type": "string" }, "description": "Email address of the recipient(s). Supports friendly name format. Example: `\"Bob \"`. Use commas to separate multiple recipients. Duplicate addresses are automatically ignored." }, "cc": { "type": "array", "items": { "type": "string" }, "description": "Same as `to` but for carbon copy recipients. Supports friendly name format." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "Same as `to` but for blind carbon copy recipients. Supports friendly name format." }, "subject": { "type": "string", "description": "Message subject. Note: not required if sending with a template that has a pre-set Subject header, but it will override it if provided." }, "text": { "type": "string", "description": "Body of the message (text version)" }, "html": { "type": "string", "description": "Body of the message (HTML version)" }, "amp-html": { "type": "string", "description": "AMP part of the message. Please follow Google guidelines to compose and send AMP emails" }, "attachment": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "File attachment. You can post multiple `attachment` values. **Important:** You must use `multipart/form-data` encoding for sending attachments" }, "inline": { "type": "array", "items": { "type": "string", "format": "binary" }, "format": "binary", "description": "Attachment with `inline` disposition. Can be used to send inline images (see example). You can post multiple `inline` values" }, "template": { "type": "string", "description": "Name of a template stored via the Templates API to use to render the email body. See [Templates](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-templates) for more information" }, "t:version": { "type": "string", "description": "Render a specific version of the given template instead of the latest version. `template` option must also be provided." }, "t:text": { "type": "string", "enum": [ "yes" ], "description": "Generates a plain text version of the template alongside the HTML version when sending templated emails. When set to 'yes', instructs Mailgun to create a text/plain MIME part based on the template content, ensuring compatibility with email clients that don't support HTML or have HTML rendering disabled. This improves email deliverability and accessibility by providing a fallback text version in multipart emails.", "x-enumDescriptions": { "yes": "Render template in the text part of the message" } }, "t:variables": { "type": "string", "description": "A valid JSON-encoded dictionary used as the input for template variable expansion. See [Templates](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-templates) for more information" }, "o:tag": { "type": "array", "items": { "type": "string" }, "description": "Tag string. See [Tagging](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/track-tagging) for more information" }, "o:dkim": { "type": "string", "enum": [ "yes", "no", "true", "false" ], "description": "Enables or disables DKIM signatures on a per-message basis. Overrides the domain-level DKIM setting for this specific message.", "x-enumDescriptions": { "yes": "Enables DKIM signatures", "no": "Disable DKIM signatures", "true": "Enables DKIM signatures", "false": "Disable DKIM signatures" } }, "o:secondary-dkim": { "type": "string", "description": "Specify a second domain key to sign the email with. The value is formatted as `signing_domain/selector`, e.g. `example.com/s1`. This tells Mailgun to sign the message with the signing domain `example.com` using the selector `s1`. Note: the domain key specified must have been previously created and activated." }, "o:secondary-dkim-public": { "type": "string", "description": "Specify an alias of the domain key specified in `o:secondary-dkim`. Also formatted as `public_signing_domain/selector`. `o:secondary-dkim` option must also be provided. Mailgun will sign the message with the provided key of the secondary DKIM, but use the public secondary DKIM name and selector. Note: We will perform a DNS check prior to signing the message to ensure the public keys matches the secondary DKIM." }, "o:deliverytime": { "type": "string", "description": "Specifies the scheduled delivery time in [RFC-2822 format](https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview#date-format). Depending on your plan, you can schedule messages up to 3 or 7 days in advance. If your domain has a custom message_ttl (time-to-live) setting, this value determines the maximum scheduling duration. Example: 'Fri, 14 Oct 2011 12:00:00 +0000'" }, "o:deliver-within": { "type": "string", "description": "Specifies the maximum time window for delivering the message. Accepts values in format `[0-9]+h[0-9]+m` (e.g., `1h30m`, `30m`, `24h`), with a minimum of `5m` and maximum of `24h`. For scheduled messages, the delivery window starts from the scheduled time. The standard retry schedule applies within this window, so shorter timeframes may result in fewer delivery attempts." }, "o:deliverytime-optimize-period": { "type": "string", "description": "Toggles Send Time Optimization (STO) on a per-message basis. String should be set to the number of hours in `[0-9]+h` format, with the minimum being `24h` and the maximum being `72h`. This value defines the time window in which Mailgun will run the optimization algorithm based on prior engagement data of a given recipient. See [Sending a Message with STO](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-sto) for details. *Please note that STO is only available on certain plans. See www.mailgun.com/pricing for more info*" }, "o:time-zone-localize": { "type": "string", "description": "Toggles Timezone Optimization (TZO) on a per message basis. String should be set to preferred delivery time in `HH:mm` or `hh:mmaa` format, where `HH:mm` is used for 24 hour format without AM/PM and hh:mmaa is used for 12 hour format with AM/PM. See [Sending a Message with TZO](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-tzo) for details. *Please note that TZO is only available on certain plans. See www.mailgun.com/pricing for more info*" }, "o:testmode": { "type": "string", "enum": [ "yes" ], "description": "Enables sending in test mode. Messages are processed normally but not actually delivered to recipients. Useful for testing without sending real emails. See [Sending in Test Mode](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/test-mode)", "x-enumDescriptions": { "yes": "Send in test mode" } }, "o:tracking": { "type": "string", "enum": [ "yes", "no", "true", "false", "htmlonly" ], "description": "Toggles both click and open tracking on a per-message basis", "x-enumDescriptions": { "yes": "Enable tracking on a per-message basis", "no": "Disable tracking on a per-message basis", "true": "Enable tracking on a per-message basis", "false": "Disable tracking on a per-message basis", "htmlonly": "Use if you only want links rewritten in the HTML part of the message" } }, "o:tracking-clicks": { "type": "string", "enum": [ "yes", "no", "true", "false", "htmlonly" ], "description": "Toggles click tracking on a per-message basis, see [Tracking Clicks](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/tracking-clicks). This overrides the domain-level click tracking setting.", "x-enumDescriptions": { "yes": "Enable tracking on a per-message basis", "no": "Disable tracking on a per-message basis", "true": "Enable tracking on a per-message basis", "false": "Disable tracking on a per-message basis", "htmlonly": "Use if you only want links rewritten in the HTML part of the message" } }, "o:tracking-opens": { "type": "string", "enum": [ "yes", "no", "true", "false" ], "description": "Toggles opens tracking on a per-message basis, see [Tracking Opens](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/tracking-opens). Has higher priority than domain-level setting.", "x-enumDescriptions": { "yes": "Enables opens tracking", "no": "Disable opens tracking", "true": "Enables opens tracking", "false": "Disable opens tracking" } }, "o:require-tls": { "type": "string", "enum": [ "yes", "no", "true", "false" ], "description": "When set to 'yes', requires the message to be sent only over a TLS connection to the Email Service Provider. If TLS cannot be established, the message will not be delivered. When set to 'no' (default), Mailgun attempts TLS but falls back to plaintext SMTP if needed.", "x-enumDescriptions": { "yes": "Message only be sent over a TLS connection", "no": "Message do not require to be sent over a TLS connection", "true": "Message only be sent over a TLS connection", "false": "Message do not require to be sent over a TLS connection" } }, "o:skip-verification": { "type": "string", "enum": [ "yes", "no", "true", "false" ], "description": "If `true`, the certificate and hostname of the resolved MX Host will not be verified when trying to establish a TLS connection. If `false`, Mailgun will verify the certificate and hostname. If either one can not be verified, a TLS connection will not be established. The default is `false`", "x-enumDescriptions": { "yes": "Verification skipped", "no": "Verification active", "true": "Verification skipped", "false": "Verification active" } }, "o:sending-ip": { "type": "string", "description": "Used to specify an IP Address to send an email that is owned by your account" }, "o:sending-ip-pool": { "type": "string", "description": "If an IP Pool ID is provided, the email will be delivered with an IP that belongs in that pool" }, "o:tracking-pixel-location-top": { "type": "string", "enum": [ "yes", "no", "true", "false", "htmlonly" ], "description": "Places the tracking pixel at the top of emails instead of the bottom. Useful for long emails that may be truncated or have rendering issues, ensuring open tracking works accurately.", "x-enumDescriptions": { "yes": "Enables tracking", "no": "Disable tracking", "true": "Enables tracking", "false": "Disable tracking", "htmlonly": "Use if you only want links rewritten in the HTML part of the message" } }, "o:archive-to": { "type": "string", "description": "Sends a copy of successfully delivered messages to the specified URL via HTTP POST. The request uses Content-Type: application/mime and contains the exact message the recipient's SMTP server received. NOTE: These are accounted for and billed as delivered messages" }, "o:suppress-headers": { "type": "string", "description": "Removes specified X-Mailgun headers from the delivered message. Provide header names separated by commas (e.g., 'X-Mailgun-Variables,X-Mailgun-Tag') or use 'all' to remove all X-Mailgun headers.Note: X-Mailgun-Sid header is currently used to process complains received via feedback loops." }, "h:X-My-Header": { "type": "string", "description": "Adds custom headers to the email. Use 'h:' prefix followed by header name and value. Example: 'h:X-Custom-Header=my-value'" }, "v:my-var": { "type": "string", "description": "Attaches custom data to the message using the 'v:' prefix followed by a variable name. When sending with templates, provides values for template variable substitution (overridden by 't:variables' if both are provided). When not using templates, treated as metadata and included in events/webhooks. Variables are visible in the delivered email's X-Mailgun-Variables header. Example: 'v:user-id=123'. NOTE: Anything over 4KB will be truncated in the event/webhooks." }, "recipient-variables": { "type": "string", "description": "A JSON-encoded dictionary for batch sending with personalized variables per recipient. Each key is a recipient email address, each value is a dictionary of variables for that recipient. Variables can be referenced in the message using %recipient.variablename%. Example: '{\"alice@example.com\": {\"name\":\"Alice\", \"id\":1}, \"bob@example.com\": {\"name\":\"Bob\", \"id\":2}}'. Maximum 1,000 recipients per batch. See [Batch Sending](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/batch-sending) for more information" } }, "required": [ "from", "to", "subject" ], "additionalProperties": true }, "POST-v3-domain_name-messages-mime-multipart-form-data-RequestBody": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string" }, "description": "Email address of the recipient(s). Supports friendly name format. Example: `\"Bob \"`. Use commas to separate multiple recipients. Duplicate addresses are automatically ignored." }, "message": { "type": "string", "format": "binary", "description": "MIME string of the message. Make sure to use `multipart/form-data` content type to send this as a file upload" }, "template": { "type": "string", "description": "Name of a template stored via template API to use to render the email body. See [Templates](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-templates) for more information" }, "t:version": { "type": "string", "description": "Render a specific version of the given template instead of the latest version. `template` option must also be provided." }, "t:text": { "type": "string", "enum": [ "yes" ], "description": "Generates a plain text version of the template alongside the HTML version when sending templated emails. When set to 'yes', instructs Mailgun to create a text/plain MIME part based on the template content, ensuring compatibility with email clients that don't support HTML or have HTML rendering disabled. This improves email deliverability and accessibility by providing a fallback text version in multipart emails.", "x-enumDescriptions": { "yes": "Render template in the text part of the message" } }, "t:variables": { "type": "string", "description": "A valid JSON-encoded dictionary used as the input for template variable expansion. See [Templates](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-templates) for more information" }, "o:tag": { "type": "array", "items": { "type": "string" }, "description": "Tag string. See [Tags](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/track-tagging) for more information" }, "o:dkim": { "type": "string", "enum": [ "yes", "no", "true", "false" ], "description": "Enables or disables DKIM signatures on a per-message basis. Overrides the domain-level DKIM setting for this specific message.", "x-enumDescriptions": { "yes": "Enables DKIM signatures", "no": "Disable DKIM signatures", "true": "Enables DKIM signatures", "false": "Disable DKIM signatures" } }, "o:secondary-dkim": { "type": "string", "description": "Specify a second domain key to sign the email with. The value is formatted as `signing_domain/selector`, e.g. `example.com/s1`. This tells Mailgun to sign the message with the signing domain `example.com` using the selector `s1`. Note: the domain key specified must have been previously created and activated." }, "o:secondary-dkim-public": { "type": "string", "description": "Specify an alias of the domain key specified in `o:secondary-dkim`. Also formatted as `public_signing_domain/selector`. `o:secondary-dkim` option must also be provided. Mailgun will sign the message with the provided key of the secondary DKIM, but use the public secondary DKIM name and selector. Note: We will perform a DNS check prior to signing the message to ensure the public keys matches the secondary DKIM." }, "o:deliverytime": { "type": "string", "description": "Specifies the scheduled delivery time in [RFC-2822 format](https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview#date-format). Depending on your plan, you can schedule messages up to 3 or 7 days in advance. If your domain has a custom message_ttl (time-to-live) setting, this value determines the maximum scheduling duration. Example: 'Fri, 14 Oct 2011 12:00:00 +0000'" }, "o:deliver-within": { "type": "string", "description": "Specifies the maximum time window for delivering the message. Accepts values in format `[0-9]+h[0-9]+m` (e.g., `1h30m`, `30m`, `24h`), with a minimum of `5m` and maximum of `24h`. For scheduled messages, the delivery window starts from the scheduled time. The standard retry schedule applies within this window, so shorter timeframes may result in fewer delivery attempts." }, "o:deliverytime-optimize-period": { "type": "string", "description": "Toggles Send Time Optimization (STO) on a per-message basis. String should be set to the number of hours in `[0-9]+h` format, with the minimum being `24h` and the maximum being `72h`. This value defines the time window in which Mailgun will run the optimization algorithm based on prior engagement data of a given recipient. See [Sending a Message with STO](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-sto) for details. *Please note that STO is only available on certain plans. See www.mailgun.com/pricing for more info*" }, "o:time-zone-localize": { "type": "string", "description": "Toggles Timezone Optimization (TZO) on a per message basis. String should be set to preferred delivery time in `HH:mm` or `hh:mmaa` format, where `HH:mm` is used for 24 hour format without AM/PM and hh:mmaa is used for 12 hour format with AM/PM. See [Sending a Message with TZO](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-tzo) for details. *Please note that TZO is only available on certain plans. See www.mailgun.com/pricing for more info*" }, "o:testmode": { "type": "string", "enum": [ "yes" ], "description": "Enables sending in test mode. Messages are processed normally but not actually delivered to recipients. Useful for testing without sending real emails. See [Sending in Test Mode](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/test-mode)", "x-enumDescriptions": { "yes": "Send in test mode" } }, "o:tracking": { "type": "string", "enum": [ "yes", "no", "true", "false", "htmlonly" ], "description": "Toggles both click and open tracking on a per-message basis, see [Tracking Messages](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages) for details.", "x-enumDescriptions": { "yes": "Enable tracking on a per-message basis", "no": "Disable tracking on a per-message basis", "true": "Enable tracking on a per-message basis", "false": "Disable tracking on a per-message basis", "htmlonly": "Use if you only want links rewritten in the HTML part of the message" } }, "o:tracking-clicks": { "type": "string", "enum": [ "yes", "no", "true", "false", "htmlonly" ], "description": "Toggles click tracking on a per-message basis, see [Tracking Clicks](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/tracking-clicks). This overrides the domain-level click tracking setting", "x-enumDescriptions": { "yes": "Enable tracking on a per-message basis", "no": "Disable tracking on a per-message basis", "true": "Enable tracking on a per-message basis", "false": "Disable tracking on a per-message basis", "htmlonly": "Use if you only want links rewritten in the HTML part of the message" } }, "o:tracking-opens": { "type": "string", "enum": [ "yes", "no", "true", "false" ], "description": "Toggles opens tracking on a per-message basis, see [Tracking Opens](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/tracking-opens). Has higher priority than domain-level setting.", "x-enumDescriptions": { "yes": "Enables opens tracking", "no": "Disable opens tracking", "true": "Enables opens tracking", "false": "Disable opens tracking" } }, "o:require-tls": { "type": "string", "enum": [ "yes", "no", "true", "false" ], "description": "When set to 'yes', requires the message to be sent only over a TLS connection. If TLS cannot be established, the message will not be delivered. When set to 'no' (default), Mailgun attempts TLS but falls back to plaintext SMTP if needed.", "x-enumDescriptions": { "yes": "Message only be sent over a TLS connection", "no": "Message do not require to be sent over a TLS connection", "true": "Message only be sent over a TLS connection", "false": "Message do not require to be sent over a TLS connection" } }, "o:skip-verification": { "type": "string", "enum": [ "yes", "no", "true", "false" ], "description": "When set to 'true', skips certificate and hostname verification for TLS connections. When 'false' (default), Mailgun verifies certificates and hostnames - if verification fails, TLS connection is not established.", "x-enumDescriptions": { "yes": "Verification skipped", "no": "Verification active", "true": "Verification skipped", "false": "Verification active" } }, "o:sending-ip": { "type": "string", "description": "Used to specify an IP Address to send an email that is owned by your account" }, "o:sending-ip-pool": { "type": "string", "description": "If an IP Pool ID is provided, the email will be delivered with an IP that belongs in that pool" }, "o:tracking-pixel-location-top": { "type": "string", "enum": [ "yes", "no", "true", "false", "htmlonly" ], "description": "Places the tracking pixel at the top of emails instead of the bottom. Useful for long emails that may be truncated or have rendering issues, ensuring open tracking works accurately.", "x-enumDescriptions": { "yes": "Enables tracking", "no": "Disable tracking", "true": "Enables tracking", "false": "Disable tracking", "htmlonly": "Use if you only want links rewritten in the HTML part of the message" } }, "o:archive-to": { "type": "string", "description": "Sends a copy of successfully delivered messages to the specified URL via HTTP POST. The request uses Content-Type: application/mime and contains the exact message the recipient's SMTP server received. NOTE: These are accounted for and billed as delivered messages" }, "o:suppress-headers": { "type": "string", "description": "Removes specified X-Mailgun headers from the delivered message. Provide header names separated by commas (e.g., 'X-Mailgun-Variables,X-Mailgun-Tag') or use 'all' to remove all X-Mailgun headers.Note: X-Mailgun-Sid header is currently used to process complains received via feedback loops." }, "h:X-My-Header": { "type": "string", "description": "Adds custom headers to the email. Use 'h:' prefix followed by header name and value. Example: 'h:X-Custom-Header=my-value'" }, "v:my-var": { "type": "string", "description": "Attaches custom data to the message using the 'v:' prefix followed by a variable name. When sending with templates, provides values for template variable substitution (overridden by 't:variables' if both are provided). When not using templates, treated as metadata and included in events/webhooks. Variables are visible in the delivered email's X-Mailgun-Variables header. Example: 'v:user-id=123'.NOTE: Anything over 4KB will be truncated in the event/webhooks" }, "recipient-variables": { "type": "string", "description": "A JSON-encoded dictionary for batch sending with personalized variables per recipient. Each key is a recipient email address, each value is a dictionary of variables for that recipient. Variables can be referenced in the message using %recipient.variablename%. Example: '{\"alice@example.com\": {\"name\":\"Alice\", \"id\":1}, \"bob@example.com\": {\"name\":\"Bob\", \"id\":2}}'. Maximum 1,000 recipients per batch. See [Batch Sending](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/batch-sending) for more information." } }, "required": [ "to", "message" ], "additionalProperties": true }, "POST-v3-domains-domain_name-messages-storage_key-multipart-form-data-RequestBody": { "type": "object", "properties": { "to": { "type": "string", "description": "Email address of the recipient(s). Supports friendly name format. Example: `\"Bob \"`. Use commas to separate multiple recipients. Duplicate addresses are automatically ignored." } }, "required": [ "to" ] }, "github.com-mailgun-influx-httpapi-GetMessageResponseBasicExample": { "type": "object", "properties": { "Content-Transfer-Encoding": { "type": "string", "description": "The content transfer encoding if enabled" }, "Content-Type": { "type": "string", "description": "The content type sent with the message with a possible boundary" }, "From": { "type": "string", "description": "The full 'From' email address entry of the email" }, "Message-Id": { "type": "string", "description": "The unique identifier of the message as defined by [RFC-2392](https://datatracker.ietf.org/doc/html/rfc2392)" }, "Mime-Version": { "type": "string", "description": "The MIME version of the email" }, "Subject": { "type": "string", "description": "Subject of the email" }, "To": { "type": "string", "description": "The full 'To' email address entries" }, "X-Mailgun-Tag": { "type": "string", "description": "The raw tags of the message if provided" }, "sender": { "type": "string", "description": "Just the email address from the provided 'From'' field" }, "recipients": { "type": "string", "description": "A list of email addresses from the 'To'' field" }, "body-html": { "type": "string", "description": "The full HTML body of the full message" }, "body-plain": { "type": "string", "description": "The plain text body of the full message" }, "stripped-html": { "type": "string", "description": "Only the body of the email in HTML" }, "stripped-text": { "type": "string", "description": "Only the body of the email in plain text" }, "stripped-signature": { "type": "string", "description": "The signature stripped from the body" }, "message-headers": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "The full list of headers of the MIME upon send" }, "X-Mailgun-Template-Name": { "type": "string", "description": "The name of the template if one was used" }, "X-Mailgun-Template-Variables": { "type": "string", "description": "The variables used in the template if one was used" } }, "required": [ "Content-Transfer-Encoding", "Content-Type", "From", "Message-Id", "Mime-Version", "Subject", "To", "X-Mailgun-Tag", "sender", "recipients", "body-html", "body-plain", "stripped-html", "stripped-text", "stripped-signature", "message-headers", "X-Mailgun-Template-Name", "X-Mailgun-Template-Variables" ] }, "github.com-mailgun-influx-httpapi-GetMessageResponseBadRequest": { "type": "object", "properties": { "message": { "type": "string", "description": "A failure message" } }, "required": [ "message" ] }, "github.com-mailgun-domains-client-golang-Disabled": { "type": "object", "properties": { "code": { "type": "string", "description": "Code indicating the reason for the domain being disabled" }, "note": { "type": "string", "description": "Additional information about why the domain was disabled" }, "permanently": { "type": "boolean", "description": "Indicates whether the domain is permanently disabled" }, "reason": { "type": "string", "description": "Additional information about why the domain was disabled" }, "until": { "type": "string", "description": "Timestamp in RFC1123 format indicating when the domain will be re-enabled if the disablement is temporary" } }, "required": [ "code", "note", "permanently", "reason" ] }, "github.com-mailgun-domains-client-golang-Domain": { "type": "object", "properties": { "archive_to": { "type": "string", "description": "URL that a copy of each successfully delivered message is going to be posted to." }, "created_at": { "type": "string", "description": "Timestamp indicating when the domain was created in RFC1123 format" }, "id": { "type": "string", "description": "Unique identifier of the domain" }, "is_disabled": { "type": "boolean", "description": "Indicates whether the domain is currently disabled" }, "name": { "type": "string", "description": "Fully qualified domain name registered with Mailgun" }, "require_tls": { "type": "boolean", "description": "If true Mailgun will only send messages over a TLS connection" }, "skip_verification": { "type": "boolean", "description": "If true Mailgun will not verify the certificate and hostname when setting up a TLS connection" }, "smtp_login": { "type": "string", "description": "SMTP login username for the domain, only present if the user provides an smtp_password. Use the Credentials API for SMTP credentials management" }, "smtp_password": { "type": "string", "description": "Optional SMTP password for the domain used for SMTP authentication" }, "spam_action": { "type": "string", "description": "Action to take when a message is flagged as spam. Options are disabled, tag, or block" }, "subaccount_id": { "type": "string", "description": "The subaccount ID the domain belongs to. This field is only present if the domain is associated with a subaccount" }, "state": { "type": "string", "description": "Current verification status of the domain" }, "type": { "type": "string", "description": "Classification of the domain. Possible values are custom or sandbox" }, "tracking_host": { "type": "string", "description": "Custom tracking host for the domain used for tracking opens and clicks if configured" }, "use_automatic_sender_security": { "type": "boolean", "description": "If true Mailgun manages DKIM key generation and DNS record configuration automatically" }, "web_prefix": { "type": "string", "description": "Subdomain prefix used for open and click tracking" }, "web_scheme": { "type": "string", "description": "Protocol scheme used for tracking" }, "wildcard": { "type": "boolean", "description": "Indicates if the domain is a wildcard domain and can receive emails for any subdomain" }, "disabled": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Disabled" }, { "type": "null" } ], "description": "Optional field containing additional details about the domain's disabled status if applicable" }, "encrypt_incoming_message": { "type": "boolean", "description": "If true incoming messages to this domain will be encrypted" }, "message_ttl": { "type": "integer", "format": "int32", "description": "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" } }, "required": [ "created_at", "id", "is_disabled", "name", "require_tls", "skip_verification", "smtp_login", "spam_action", "state", "type", "use_automatic_sender_security", "web_prefix", "web_scheme", "wildcard", "encrypt_incoming_message", "message_ttl" ] }, "github.com-mailgun-domains-client-golang-Record": { "type": "object", "properties": { "is_active": { "type": "boolean", "description": "Indicates whether the DNS record is currently active" }, "cached": { "type": "array", "items": { "type": "string" }, "description": "List of Mailguns cached values for the DNS record" }, "name": { "type": "string", "description": "Name of the DNS record if applicable" }, "priority": { "type": "string", "description": "Priority value for MX DNS records" }, "record_type": { "type": "string", "description": "Type of DNS record such as MX TXT or CNAME" }, "valid": { "type": "string", "description": "Indicates whether the DNS record is valid" }, "value": { "type": "string", "description": "Expected value of the DNS record" } }, "required": [ "is_active", "cached", "record_type", "valid", "value" ] }, "github.com-mailgun-domains-httpapi-CreateDomainResp": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "domain": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Domain" }, { "type": "null" } ], "description": "Details of the newly created domain" }, "receiving_dns_records": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Record" }, { "type": "null" } ] }, "description": "List of DNS records required for receiving emails" }, "sending_dns_records": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Record" }, { "type": "null" } ] }, "description": "List of DNS records required for sending emails" } }, "required": [ "message", "domain", "receiving_dns_records", "sending_dns_records" ] }, "github.com-mailgun-scaffold-httpapi-GenericAPIError": { "type": "object", "properties": { "Reason": { "type": "string" } }, "required": [ "Reason" ] }, "github.com-mailgun-scaffold-httpapi-GenericResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" } }, "required": [ "message" ] }, "POST-v4-domains-multipart-form-data-RequestBody": { "type": "object", "properties": { "archive_to": { "type": "string", "description": "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." }, "dkim_host_name": { "type": "string", "description": "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": { "type": "string", "description": "The size of the new domain's DKIM key. Shall be either 1024 or 2048." }, "dkim_selector": { "type": "string", "description": "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`\n\nhttps://datatracker.ietf.org/doc/html/rfc2822#section-3.2.4" }, "encrypt_incoming_message": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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 does not effect the smtp mail-from host for the domain being created. The mail-from host will remain the domain name being created, not the root domain." }, "wildcard": { "type": "boolean", "description": "Allows domain to accept inbound messages received on subdomains that have MX records pointed to Mailgun. Default is false." }, "name": { "type": "string", "description": "The name of the new domain" }, "pool_id": { "type": "string", "description": "Requested IP Pool to be assigned to the domain at creation." }, "ips": { "type": "string", "description": "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." }, "require_tls": { "type": "boolean", "description": "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.\n\nIf set to false, Mailgun will still try and upgrade the connection, but if Mailgun cannot, the message will be delivered over a plaintext SMTP connection.\n\nThe default value is false." }, "skip_verification": { "type": "boolean", "description": "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.\n\nIf set to false, Mailgun will verify the certificate and hostname. If either one can not be verified, a TLS connection will not be established.\n\nThe default value is false." }, "spam_action": { "type": "string", "description": "Disabled, block or tag. Default to disabled. If disabled, no spam filtering will occur for inbound messages.\n\nIf block, inbound spam messages will not be delivered.\n\nIf tag, inbound messages will be tagged with a spam header. See Spam Filter." }, "smtp_password": { "type": "string", "description": "Password for SMTP authentication" }, "use_automatic_sender_security": { "type": "boolean", "description": "Enable Automatic Sender Security. This requires setting DNS CNAME entries for DKIM keys instead of a TXT record. Defaults to false." }, "web_prefix": { "type": "string", "description": "Sets your open, click and unsubscribe URLs domain name prefix. Links rewritten or added by Mailgun in your emails will look like ://./... Default to email" }, "web_scheme": { "type": "string", "description": "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." }, "message_ttl": { "type": "integer", "description": "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." } }, "required": [ "name" ] }, "github.com-mailgun-domains-httpapi-ListDomainResponse": { "type": "object", "properties": { "total_count": { "type": "integer", "format": "int32", "description": "Total number of domains" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Domain" }, "description": "List of domains" } }, "required": [ "total_count", "items" ] }, "github.com-mailgun-domains-httpapi-FindDomainByNameResp": { "type": "object", "properties": { "domain": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Domain" }, { "type": "null" } ], "description": "Domain details" }, "receiving_dns_records": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Record" }, { "type": "null" } ] }, "description": "List of DNS records required for receiving emails" }, "sending_dns_records": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Record" }, { "type": "null" } ] }, "description": "List of DNS records required for sending emails" } }, "required": [ "domain" ] }, "github.com-mailgun-domains-httpapi-VerifyDomainResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "domain": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Domain" }, { "type": "null" } ], "description": "Domain record information" }, "sending_dns_records": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Record" }, { "type": "null" } ] }, "description": "List of DNS records required for sending emails" }, "receiving_dns_records": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Record" }, { "type": "null" } ] }, "description": "List of DNS records required for receiving emails" } }, "required": [ "message", "domain", "sending_dns_records", "receiving_dns_records" ] }, "github.com-mailgun-domains-httpapi-WebhookResponse": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" }, "description": "List of webhooks" } } }, "github.com-mailgun-domains-httpapi-CreateDomainWebhookResp": { "type": "object", "properties": { "message": { "type": "string", "description": "A message indicating success" }, "webhook": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhookResponse" } ], "description": "Webhook details" } }, "required": [ "message", "webhook" ] }, "POST-v3-domains-domain-webhooks-multipart-form-data-RequestBody": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "accepted", "clicked", "opened", "unsubscribed", "delivered", "permanent_fail", "temporary_fail", "complained" ], "description": "Webhook type to create.", "x-enumDescriptions": { "accepted": "The accepted event occurs when Mailgun accepts a message for delivery.", "clicked": "The clicked event occurs when a recipient clicks a link in the email. This requires click tracking to be enabled for the domain.", "opened": "The opened event occurs when a recipient opens the email. This requires open tracking to be enabled for the domain.", "unsubscribed": "The unsubscribed event occurs when a recipient unsubscribes using an unsubscribe mechanism in your email (for example, a list-unsubscribe link).", "delivered": "The delivered event occurs when an email is successfully delivered to the recipient's mail server.", "permanent_fail": "The permanent_fail event occurs when an email cannot be delivered due to a permanent error.", "temporary_fail": "The temporary_fail event occurs when an email cannot be delivered due to a temporary error.", "complained": "The complained event occurs when a recipient marks your email as spam or their email provider registers a spam complaint." } }, "url": { "type": "string", "description": "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." } }, "required": [ "id", "url" ] }, "PUT-v3-domains-domain_name-webhooks-webhook_name-multipart-form-data-RequestBody": { "type": "object", "properties": { "url": { "type": "string", "description": "New url(s) to associate to webhook. Use multiple times to associate more than one url. Maximum of 3 urls for a given type." } }, "required": [ "url" ] }, "github.com-mailgun-domains-httpapi-GetDomainWebhookResp": { "type": "object", "properties": { "webhook": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhookResponse" } ], "description": "List of webhooks" } }, "required": [ "webhook" ] }, "github.com-mailgun-domains-httpapi-WebhookURLs": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" }, "description": "List of URLs" } }, "required": [ "urls" ] }, "github.com-mailgun-domains-httpapi-WebhooksResponse": { "type": "object", "properties": { "accepted": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs" }, { "type": "null" } ], "description": "Accepted webhook URLs" }, "delivered": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs" }, { "type": "null" } ], "description": "Delivered webhook URLs" }, "opened": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs" }, { "type": "null" } ], "description": "Opened webhook URLs" }, "clicked": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs" }, { "type": "null" } ], "description": "Clicked webhook URLs" }, "unsubscribed": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs" }, { "type": "null" } ], "description": "Unsubscribed webhook URLs" }, "complained": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs" }, { "type": "null" } ], "description": "Complained webhook URLs" }, "temporary_fail": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs" }, { "type": "null" } ], "description": "Temporary fail webhook URLs" }, "permanent_fail": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs" }, { "type": "null" } ], "description": "Permanent fail webhook URLs" } } }, "github.com-mailgun-domains-httpapi-GetAllDomainWebhooksResp": { "type": "object", "properties": { "webhooks": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-WebhooksResponse" } ], "description": "List of webhooks" } }, "required": [ "webhooks" ] }, "POST-v4-domains-domain-webhooks-application-x-www-form-urlencoded-RequestBody": { "type": "object", "properties": { "url": { "type": "string", "description": "The webhook URL that will receive POST requests" }, "event_types": { "type": "string", "enum": [ "accepted", "clicked", "opened", "unsubscribed", "delivered", "permanent_fail", "temporary_fail", "complained" ], "description": "Event types. Use multiple times to specify multiple event types. ", "x-enumDescriptions": { "accepted": "The accepted event occurs when Mailgun accepts a message for delivery.", "clicked": "The clicked event occurs when a recipient clicks a link in the email. This requires click tracking to be enabled for the domain.", "opened": "The opened event occurs when a recipient opens the email. This requires open tracking to be enabled for the domain.", "unsubscribed": "The unsubscribed event occurs when a recipient unsubscribes using an unsubscribe mechanism in your email (for example, a list-unsubscribe link).", "delivered": "The delivered event occurs when an email is successfully delivered to the recipient's mail server.", "permanent_fail": "The permanent_fail event occurs when an email cannot be delivered due to a permanent error.", "temporary_fail": "The temporary_fail event occurs when an email cannot be delivered due to a temporary error.", "complained": "The complained event occurs when a recipient marks your email as spam or their email provider registers a spam complaint." } } }, "required": [ "url", "event_types" ] }, "PUT-v4-domains-domain-webhooks-application-x-www-form-urlencoded-RequestBody": { "type": "object", "properties": { "url": { "type": "string", "description": "The webhook URL to update" }, "event_types": { "type": "string", "enum": [ "accepted", "clicked", "opened", "unsubscribed", "delivered", "permanent_fail", "temporary_fail", "complained" ], "description": "Event types to associate with this URL. Use multiple times to specify multiple event types. This replaces the existing associations. ", "x-enumDescriptions": { "accepted": "The accepted event occurs when Mailgun accepts a message for delivery.", "clicked": "The clicked event occurs when a recipient clicks a link in the email. This requires click tracking to be enabled for the domain.", "opened": "The opened event occurs when a recipient opens the email. This requires open tracking to be enabled for the domain.", "unsubscribed": "The unsubscribed event occurs when a recipient unsubscribes using an unsubscribe mechanism in your email (for example, a list-unsubscribe link).", "delivered": "The delivered event occurs when an email is successfully delivered to the recipient's mail server.", "permanent_fail": "The permanent_fail event occurs when an email cannot be delivered due to a permanent error.", "temporary_fail": "The temporary_fail event occurs when an email cannot be delivered due to a temporary error.", "complained": "The complained event occurs when a recipient marks your email as spam or their email provider registers a spam complaint." } } }, "required": [ "url", "event_types" ] }, "github.com-mailgun-domains-httpapi-openSettings": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether open tracking is enabled or not" }, "place_at_the_top": { "type": "boolean", "description": "If the pixel should be placed at the top of the email" } }, "required": [ "active", "place_at_the_top" ] }, "github.com-mailgun-domains-httpapi-clickSettings": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether click tracking is enabled or not" } }, "required": [ "active" ] }, "github.com-mailgun-domains-httpapi-unsubscribeSettings": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether unsubscribe tracking is enabled or not" }, "html_footer": { "type": "string", "description": "The HTML footer for the unsubscribe link" }, "text_footer": { "type": "string", "description": "The text footer for the unsubscribe link" } }, "required": [ "active", "html_footer", "text_footer" ] }, "github.com-mailgun-domains-httpapi-trackingSettings": { "type": "object", "properties": { "open": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-openSettings" } ], "description": "Open tracking settings" }, "click": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-clickSettings" } ], "description": "Click tracking settings" }, "unsubscribe": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-unsubscribeSettings" } ], "description": "Unsubscribe tracking settings" }, "web_scheme": { "type": "string", "description": "The web scheme for the domain" } }, "required": [ "open", "click", "unsubscribe", "web_scheme" ] }, "github.com-mailgun-domains-httpapi-GetDomainTrackingResp": { "type": "object", "properties": { "tracking": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-trackingSettings" } }, "required": [ "tracking" ] }, "github.com-mailgun-domains-httpapi-UpdateDomainTrackingClickResp": { "type": "object", "properties": { "message": { "type": "string", "description": "A message indicating success" }, "click": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-clickSettings" } ], "description": "Click settings" } }, "required": [ "message", "click" ] }, "PUT-v3-domains-name-tracking-click-multipart-form-data-RequestBody": { "type": "object", "properties": { "active": { "type": "string", "description": "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" } } }, "github.com-mailgun-domains-httpapi-UpdateDomainTrackingOpenResp": { "type": "object", "properties": { "message": { "type": "string", "description": "A message indicating success" }, "open": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-openSettings" } ], "description": "Open settings" } }, "required": [ "message", "open" ] }, "PUT-v3-domains-name-tracking-open-multipart-form-data-RequestBody": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Set this param to true or false to toggle open tracking active status. Omit this param to keep current settings." }, "place_at_the_top": { "type": "boolean", "description": "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." } } }, "github.com-mailgun-domains-httpapi-UpdateDomainTrackingUnsubscribeResp": { "type": "object", "properties": { "message": { "type": "string", "description": "A message indicating success" }, "unsubscribe": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-unsubscribeSettings" } ], "description": "Unsubscribe settings" } }, "required": [ "message", "unsubscribe" ] }, "PUT-v3-domains-name-tracking-unsubscribe-multipart-form-data-RequestBody": { "type": "object", "properties": { "active": { "type": "boolean", "description": "This param will toggle the active status of unsubscribe tracking on the domain." }, "html_footer": { "type": "string", "description": "Updates the html footer for the unsubscribe link inserted into the email html part of the mime." }, "text_footer": { "type": "string", "description": "Updates the text footer for the unsubscribe link inserted into the email plain part of the mime." } } }, "github.com-mailgun-domains-httpapi-DomainKeyResponse": { "type": "object", "properties": { "signing_domain": { "type": "string" }, "selector": { "type": "string" }, "dns_record": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Record" }, { "type": "null" } ] } }, "required": [ "signing_domain", "selector" ] }, "POST-v1-dkim-keys-multipart-form-data-RequestBody": { "type": "object", "properties": { "signing_domain": { "type": "string", "description": "Signing domain to be used for the new domain key" }, "selector": { "type": "string", "description": "Selector to be used for the new domain key" }, "bits": { "type": "integer", "description": "Key size, can be 1024 or 2048" }, "pem": { "type": "string", "description": "Private key PEM file" } }, "required": [ "signing_domain", "selector" ] }, "github.com-mailgun-domains-httpapi-UpdateDomainKeyResp": { "type": "object", "properties": { "message": { "type": "string" }, "authority": { "type": "string" }, "selector": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "message", "authority", "selector", "active" ] }, "github.com-mailgun-scaffold-httpapi-paging-PagingResponse": { "type": "object", "properties": { "previous": { "type": "string", "description": "Previous page URL" }, "first": { "type": "string", "description": "First page URL" }, "next": { "type": "string", "description": "Next page URL" }, "last": { "type": "string", "description": "Last page URL" } }, "required": [ "previous", "first", "next", "last" ] }, "github.com-mailgun-domains-httpapi-DomainKeyListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-DomainKeyResponse" }, { "type": "null" } ] } }, "paging": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse" }, { "type": "null" } ] } }, "required": [ "items" ] }, "GET-v1-dkim-keys-multipart-form-data-RequestBody": { "type": "object", "properties": { "page": { "type": "string", "description": "Encoded paging information, provided via 'next', 'previous' links" }, "limit": { "type": "integer", "description": "Limits the number of items returned in a request" }, "signing_domain": { "type": "string", "description": "Filter by signing domain" }, "selector": { "type": "string", "description": "Filter by selector" } }, "required": [ "page", "limit" ] }, "github.com-mailgun-domains-httpapi-AuthorityKeysResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-DomainKeyResponse" }, { "type": "null" } ] } } }, "required": [ "items" ] }, "github.com-mailgun-domains-httpapi-ReassignDkimAuthorityResp": { "type": "object", "properties": { "message": { "type": "string" }, "sending_dns_records": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Record" }, { "type": "null" } ] } }, "changed": { "type": "boolean" } }, "required": [ "message", "sending_dns_records", "changed" ] }, "PUT-v3-domains-name-dkim_authority-multipart-form-data-RequestBody": { "type": "object", "properties": { "self": { "type": "boolean", "description": "Change the DKIM authority for a domain.\nIf set to true, the domain will be the DKIM authority for itself even if the root domain is registered on the same mailgun account\n If set to false, the domain will have the same DKIM authority as the root domain registered on the same mailgun account." } } }, "PUT-v3-domains-name-dkim_selector-multipart-form-data-RequestBody": { "type": "object", "properties": { "dkim_selector": { "type": "string", "description": "Update the DKIM selector for a domain. If omitted no change is committed." } } }, "github.com-mailgun-domains-httpapi-CreateAccountLevelWebhookResp": { "type": "object", "properties": { "webhook_id": { "type": "string", "description": "Unique identifier for the webhook" } }, "required": [ "webhook_id" ] }, "github.com-mailgun-scaffold-httpapi-NotFoundError": { "type": "object", "properties": { "Description": { "type": "string" } }, "required": [ "Description" ] }, "github.com-mailgun-scaffold-httpapi-ConflictError": { "type": "object", "properties": { "Description": { "type": "string" } }, "required": [ "Description" ] }, "POST-v1-webhooks-multipart-form-data-RequestBody": { "type": "object", "properties": { "description": { "type": "string", "description": "Description for the webhook" }, "event_types": { "type": "string", "enum": [ "accepted", "clicked", "opened", "unsubscribed", "delivered", "permanent_fail", "temporary_fail", "complained" ], "description": "Event types to subscribe to. Use multiple times to specify multiple event types. Maximum of 3 unique URLs per event type.", "x-enumDescriptions": { "accepted": "The accepted event occurs when Mailgun accepts a message for delivery.", "clicked": "The clicked event occurs when a recipient clicks a link in the email. This requires click tracking to be enabled for the domain.", "opened": "The opened event occurs when a recipient opens the email. This requires open tracking to be enabled for the domain.", "unsubscribed": "The unsubscribed event occurs when a recipient unsubscribes using an unsubscribe mechanism in your email (for example, a list-unsubscribe link).", "delivered": "The delivered event occurs when an email is successfully delivered to the recipient's mail server.", "permanent_fail": "The permanent_fail event occurs when an email cannot be delivered due to a permanent error.", "temporary_fail": "The temporary_fail event occurs when an email cannot be delivered due to a temporary error.", "complained": "The complained event occurs when a recipient marks your email as spam or their email provider registers a spam complaint." } }, "url": { "type": "string", "description": "URL for webhook to be sent to" } }, "required": [ "event_types", "url" ] }, "github.com-mailgun-domains-httpapi-AccountLevelWebhookView": { "type": "object", "properties": { "webhook_id": { "type": "string", "description": "Unique identifier for the webhook" }, "description": { "type": "string", "description": "User-provided description of the webhook" }, "url": { "type": "string", "description": "The endpoint URL where webhook events are delivered" }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "List of event types that trigger this webhook" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the webhook was created in RFC3339 format" } }, "required": [ "webhook_id", "description", "url", "event_types", "created_at" ] }, "github.com-mailgun-domains-httpapi-AccountLevelWebhooksResp": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-AccountLevelWebhookView" } } }, "required": [ "webhooks" ] }, "PUT-v1-webhooks-webhook_id-multipart-form-data-RequestBody": { "type": "object", "properties": { "description": { "type": "string", "description": "Description for the webhook" }, "event_types": { "type": "string", "enum": [ "accepted", "clicked", "opened", "unsubscribed", "delivered", "permanent_fail", "temporary_fail", "complained" ], "description": "Event types to subscribe to. Use multiple times to specify multiple event types. Maximum of 3 unique URLs per event type.", "x-enumDescriptions": { "accepted": "The accepted event occurs when Mailgun accepts a message for delivery.", "clicked": "The clicked event occurs when a recipient clicks a link in the email. This requires click tracking to be enabled for the domain.", "opened": "The opened event occurs when a recipient opens the email. This requires open tracking to be enabled for the domain.", "unsubscribed": "The unsubscribed event occurs when a recipient unsubscribes using an unsubscribe mechanism in your email (for example, a list-unsubscribe link).", "delivered": "The delivered event occurs when an email is successfully delivered to the recipient's mail server.", "permanent_fail": "The permanent_fail event occurs when an email cannot be delivered due to a permanent error.", "temporary_fail": "The temporary_fail event occurs when an email cannot be delivered due to a temporary error.", "complained": "The complained event occurs when a recipient marks your email as spam or their email provider registers a spam complaint." } }, "url": { "type": "string", "description": "URL for webhook to be sent to" } }, "required": [ "event_types", "url" ] }, "github.com-mailgun-scaffold-httpapi-InvalidParameterError": { "type": "object", "properties": { "Field": { "type": "string" }, "Value": { "type": "string" } }, "required": [ "Field", "Value" ] }, "github.com-mailgun-domains-httpapi-UpdateDomainResp": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "domain": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Domain" }, { "type": "null" } ], "description": "Domain object" }, "receiving_dns_records": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Record" }, { "type": "null" } ] }, "description": "List of DNS records required for receiving emails" }, "sending_dns_records": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-client-golang-Record" }, { "type": "null" } ] }, "description": " List of DNS records required for sending emails" } }, "required": [ "message", "domain" ] }, "PUT-v4-domains-name-multipart-form-data-RequestBody": { "type": "object", "properties": { "archive_to": { "type": "string", "description": "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": { "type": "string", "description": "The hostname to update to. Must be in lower case" }, "message_ttl": { "type": "integer", "description": "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": { "type": "boolean", "description": "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.\n\nIf set to false, Mailgun will still try and upgrade the connection, but if Mailgun cannot, the message will be delivered over a plaintext SMTP connection.\n\nThe default value is false." }, "skip_verification": { "type": "boolean", "description": "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.\n\nIf set to false, Mailgun will verify the certificate and hostname. If either one can not be verified, a TLS connection will not be established.\n\nThe default value is false." }, "smtp_password": { "type": "string", "description": "Updates the domain's SMTP credentials with the given string" }, "spam_action": { "type": "string", "description": "Updates the domain's spam action. Valid values are 'disabled', 'tag', and 'block'" }, "use_automatic_sender_security": { "type": "boolean", "description": "Enable or disable Automatic Sender Security. If enabled, requires setting DNS CNAME entries for DKIM keys instead of a TXT record. Domain must be reverified after changing this field. Defaults to false" }, "web_scheme": { "type": "string", "description": "Updates 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": { "type": "string", "description": "This updates the web prefix used for a domain's tracking features. Must be a valid atom. Nothing will be updated if omitted. This impacts click, open, and unsubscribe tracking features. \n\n Note: Updating the web prefix for a domain will require also updating the domain's DNS to include the CNAME record to match. For example, if you set the web prefix to `zed` for the domain `my-domain.com`, the corresponding CNAME `zed.my-domain.com` will need to be created in your domain's dns zone." }, "wildcard": { "type": "boolean", "description": "Updates the domain's wildcard status with the given boolean" } } }, "github.com-mailgun-domains-httpapi-ExceededQueueQuotaDisabledJSON": { "type": "object", "properties": { "until": { "type": "string", "description": "End date in RFC-822 date format" }, "reason": { "type": "string", "description": "Cause description" } }, "required": [ "until", "reason" ] }, "github.com-mailgun-domains-httpapi-ExceededQueueQuotaJSON": { "type": "object", "properties": { "is_disabled": { "type": "boolean", "description": "Flag indicating no new messages are able to be submitted" }, "disabled": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-ExceededQueueQuotaDisabledJSON" } ], "description": "Disabled info" } }, "required": [ "is_disabled" ] }, "github.com-mailgun-domains-httpapi-GetDomainSendingQueuesResp": { "type": "object", "properties": { "regular": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-ExceededQueueQuotaJSON" } ], "description": "Message queue response" }, "scheduled": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-domains-httpapi-ExceededQueueQuotaJSON" } ], "description": "Scheduled message queue response" } }, "required": [ "regular", "scheduled" ] }, "github.com-mailgun-pendulum-dkim-DNSRecord": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "identifier": { "type": "string" }, "value": { "type": "string" }, "comment": { "type": "string" } }, "required": [ "name", "type", "identifier", "value", "comment" ] }, "github.com-mailgun-pendulum-api-Domain": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "sid": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "active_selector": { "type": "string" }, "rotation_enabled": { "type": "string" }, "rotation_interval": { "type": "string" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-pendulum-dkim-DNSRecord" } } }, "required": [ "id", "account_id", "sid", "name", "state", "rotation_enabled", "rotation_interval" ] }, "github.com-mailgun-pendulum-api-DomainResponse": { "type": "object", "properties": { "domain": { "$ref": "#/components/schemas/github.com-mailgun-pendulum-api-Domain" } }, "required": [ "domain" ] }, "PUT-v1-dkim_management-domains-name-rotation-multipart-form-data-RequestBody": { "type": "object", "properties": { "rotation_enabled": { "type": "boolean", "description": "If true, enables DKIM Auto-Rotation. If false, disables it" }, "rotation_interval": { "type": "string", "description": "The interval at which to rotate keys. Example, '5d' for five days" } }, "required": [ "rotation_enabled" ] }, "github.com-mailgun-tower-api-subaccounts-ListSubaccountDIPPsResponseItem": { "type": "object", "properties": { "pool_id": { "type": "string" }, "subaccount_id": { "type": "string" } }, "required": [ "pool_id", "subaccount_id" ] }, "github.com-mailgun-tower-api-subaccounts-ListSubaccountDIPPsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-subaccounts-ListSubaccountDIPPsResponseItem" } }, "total_count": { "type": "integer", "format": "int32" } }, "required": [ "items", "total_count" ] }, "github.com-mailgun-tower-api-StartSagaResponse": { "type": "object", "properties": { "message": { "type": "string" }, "reference_id": { "type": "string" } }, "required": [ "message", "reference_id" ] }, "github.com-mailgun-tower-api-account-list_ips-detailsDocResponse": { "type": "object", "properties": { "ip": { "type": "string", "description": "the IP address" }, "is_on_warmup": { "type": "boolean", "description": "whether the IP is on warmup" }, "dedicated": { "type": "boolean", "description": "whether the IP is dedicated" }, "enabled": { "type": "boolean", "description": "whether the IP is enabled" } }, "required": [ "ip", "is_on_warmup", "dedicated", "enabled" ] }, "github.com-mailgun-tower-api-account-list_ips-docResponse": { "type": "object", "properties": { "assignable_to_pools": { "type": "array", "items": { "type": "string" }, "description": "list of IPs that can be assigned to dedicated IP pools." }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-account-list_ips-detailsDocResponse" }, "description": "list of detailed information for each IP" }, "items": { "type": "array", "items": { "type": "string" }, "description": "list of IPs" }, "total_count": { "type": "integer", "format": "int32", "description": "total number of IPs for the given query" } }, "required": [ "details", "items", "total_count" ] }, "github.com-mailgun-tower-api-account-getDocResponse": { "type": "object", "properties": { "dedicated": { "type": "boolean", "description": "whether the IP is dedicated or shared" }, "ip": { "type": "string", "description": "IP address" }, "rdns": { "type": "string", "description": "reverse DNS of the IP address" } }, "required": [ "dedicated", "ip", "rdns" ] }, "github.com-mailgun-tower-api-account-Item": { "type": "object", "properties": { "ips": { "type": "array", "items": { "type": "string" }, "description": "list of IPs assigned to the domain" }, "domain": { "type": "string", "description": "domain name" } }, "required": [ "ips", "domain" ] }, "github.com-mailgun-tower-api-account-domainsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-account-Item" }, "description": "list of domains with the IP assigned, along with the IPs assigned to each domain" }, "total_count": { "type": "integer", "format": "int32", "description": "total number of domains with the IP assigned for the given query" } }, "required": [ "items", "total_count" ] }, "POST-v3-ips-addr-ip_band-multipart-form-data-RequestBody": { "type": "object", "properties": { "ip_band": { "type": "string", "description": "Dedicated IP band to place the IP address into" } }, "required": [ "ip_band" ] }, "github.com-mailgun-tower-api-account-list_ips-AccountIPDoc": { "type": "object", "properties": { "address": { "type": "string", "description": "the IP address" }, "parent_account_id": { "type": "string", "description": "the id of the parent account" }, "account_id": { "type": "string", "description": "the id of the account" }, "pool_ids": { "type": "array", "items": { "type": "string" }, "description": "list of pool ids" }, "dedicated": { "type": "boolean", "description": "whether the IP is dedicated" }, "created_at": { "type": "string", "format": "date-time", "description": "the time the IP was created" }, "pool_last_modified_at": { "type": "string", "format": "date-time", "description": "the last time the pool was modified" }, "domains_last_modified_at": { "type": "string", "format": "date-time", "description": "the last time the domains were modified" } }, "required": [ "address", "parent_account_id", "account_id", "pool_ids", "dedicated", "pool_last_modified_at", "domains_last_modified_at" ] }, "github.com-mailgun-tower-api-account-list_ips-DetailedIPsResponseDoc": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-account-list_ips-AccountIPDoc" }, "description": "list of IPs belonging to the account and subaccounts" }, "total_count": { "type": "integer", "format": "int64", "description": "total number of account IPs" } }, "required": [ "items", "total_count" ] }, "github.com-mailgun-scaffold-httpapi-Response": { "type": "object", "additionalProperties": { "type": "object" } }, "POST-v3-dynamic_pools-all-multipart-form-data-RequestBody": { "type": "object", "properties": { "good_reputation": { "type": "string", "description": "IP(s) to include in the good_reputation pool" }, "poor_reputation": { "type": "string", "description": "IP(s) to include in the poor_reputation pool" }, "new_senders": { "type": "string", "description": "IP(s) to include in the new_senders pool" } }, "required": [ "good_reputation", "poor_reputation", "new_senders" ] }, "PATCH-v3-dynamic_pools-pool_name-multipart-form-data-RequestBody": { "type": "object", "properties": { "add_ip": { "type": "string", "description": "IP(s) to add to the pool" }, "remove_ip": { "type": "string", "description": "IP(s) to remove from the pool" } }, "required": [ "add_ip", "remove_ip" ] }, "github.com-mailgun-tower-api-ip_pools-list-DIPPDetailsResponse": { "type": "object", "properties": { "description": { "type": "string", "description": "long description of the dedicated IP pool" }, "ips": { "type": "array", "items": { "type": "string" }, "description": "list of IPs in the dedicated IP pool" }, "is_inherited": { "type": "boolean", "description": "indicates if the IP pool is inherited" }, "is_linked": { "type": "boolean", "description": "indicates if the IP pool is linked to any domains" }, "name": { "type": "string", "description": "short name of the dedicated IP pool" }, "pool_id": { "type": "string", "description": "the id of the dedicated IP pool" } }, "required": [ "description", "ips", "is_inherited", "is_linked", "name", "pool_id" ] }, "github.com-mailgun-tower-api-ip_pools-list-successResponse": { "type": "object", "properties": { "ip_pools": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-tower-api-ip_pools-list-DIPPDetailsResponse" }, "description": "list of dedicated IP pools of the account" }, "message": { "type": "string", "description": "success if the request was successful, otherwise contains a description of the error" } }, "required": [ "ip_pools", "message" ] }, "POST-v3-ip_pools-multipart-form-data-RequestBody": { "type": "object", "properties": { "description": { "type": "string", "description": "Description of the DIPP" }, "ip": { "type": "string", "description": "IP address to add to the DIPP (may be specified multiple times)" }, "name": { "type": "string", "description": "Short name of the DIPP" } }, "required": [ "description", "name" ] }, "PATCH-v3-ip_pools-pool_id-multipart-form-data-RequestBody": { "type": "object", "properties": { "add_ip": { "type": "string", "description": "The IP to add to the DIPP (may be specified multiple times)" }, "description": { "type": "string", "description": "The new description for the DIPP" }, "link_domain": { "type": "string", "description": "The ID of the domain link to the DIPP (may be specified multiple times)" }, "name": { "type": "string", "description": "The new short for the DIPP" }, "remove_ip": { "type": "string", "description": "The IP to remove from the DIPP (may be specified multiple times)" }, "unlink_domain": { "type": "string", "description": "The ID of the domain to unlink from the DIPP (may be specified multiple times)" } } }, "github.com-mailgun-tower-api-ip_pools-add_ip-addMultipleIPsRequestBody": { "type": "object", "properties": { "ips": { "type": "array", "items": { "type": "string" }, "description": "IPs to add to the DIPP" } }, "required": [ "ips" ] }, "PUT-v3-ip_pools-pool_id-delegate-multipart-form-data-RequestBody": { "type": "object", "properties": { "subaccount_id": { "type": "string", "description": "The ID of the subaccount to delegate the pool to" } }, "required": [ "subaccount_id" ] }, "DELETE-v3-ip_pools-pool_id-delegate-multipart-form-data-RequestBody": { "type": "object", "properties": { "subaccount_id": { "type": "string", "description": "The ID of the subaccount to revoke the pool from" } }, "required": [ "subaccount_id" ] }, "github.com-mailgun-bandersnatch-model-Domain": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "account_name": { "type": "string" }, "name": { "type": "string" }, "registered_at": { "type": "string", "format": "date-time" }, "pool": { "type": "string" }, "override": { "type": "boolean" }, "bounce_rate": { "type": [ "number", "null" ], "format": "float" }, "complaint_rate": { "type": [ "number", "null" ], "format": "float" }, "processed_count": { "type": [ "integer", "null" ], "format": "int64" } }, "required": [ "id", "account_id", "account_name", "name", "registered_at", "pool", "override" ] }, "github.com-mailgun-scaffold-httpapi-paging-PagingURLs": { "type": "object", "properties": { "Next": { "type": "string" }, "Previous": { "type": "string" }, "First": { "type": "string" }, "Last": { "type": "string" } }, "required": [ "Next", "Previous", "First", "Last" ] }, "github.com-mailgun-bandersnatch-api-DomainListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-bandersnatch-model-Domain" } }, "total_items": { "type": "integer", "format": "int32" }, "paging": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingURLs" } }, "required": [ "items", "total_items", "paging" ] }, "github.com-mailgun-bandersnatch-model-HistoryRecord": { "type": "object", "properties": { "id": { "type": "string" }, "owning_account_id": { "type": "string" }, "account_id": { "type": "string" }, "account_name": { "type": "string" }, "domain_id": { "type": "string" }, "domain_name": { "type": "string" }, "new_band": { "type": "string" }, "prev_band": { "type": "string" }, "reason": { "type": "string" }, "bounce_rate": { "type": [ "number", "null" ], "format": "float" }, "complaint_rate": { "type": [ "number", "null" ], "format": "float" }, "processed_count": { "type": [ "integer", "null" ], "format": "int64" }, "initiated_by": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "id", "owning_account_id", "account_id", "account_name", "domain_id", "domain_name", "new_band", "prev_band", "reason", "bounce_rate", "timestamp" ] }, "PUT-v1-dynamic_pools-domains-name-override-multipart-form-data-RequestBody": { "type": "object", "properties": { "pool": { "type": "string", "description": "The name of the Dynamic IP pool to override the domain with. Must be a valid pool name (ex: dynamic_good, dynamic_new, etc.)" } }, "required": [ "pool" ] }, "github.com-mailgun-bandersnatch-api-ListHistoryResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-bandersnatch-model-HistoryRecord" } }, "total_items": { "type": "integer", "format": "int32" }, "paging": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingURLs" } }, "required": [ "items", "total_items", "paging" ] }, "github.com-mailgun-terminator-httpapi-StatusResponse": { "type": "object", "properties": { "status": { "type": "object", "description": "Status of certificate. Either 'expired' 'processing' 'active' or 'error'" }, "error": { "type": [ "string", "null" ], "description": "An error message if an error occurred. Null if there is no error." }, "certificate": { "type": "string", "description": "The x509 certificate in PEM format. Present only if the certificate status is 'active' 'error' or 'expired'" } }, "required": [ "status", "error" ] }, "github.com-mailgun-terminator-httpapi-GenerateResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "A message indicating the status of the request." }, "location": { "type": "string", "description": "The URL path to check the status of the certificate." } }, "required": [ "message", "location" ] }, "EventResponse": { "type": "object", "title": "EventResponse", "properties": { "method": { "type": "string" }, "id": { "type": "string", "description": "GUID identifying the individual event" }, "event": { "$ref": "#/components/schemas/EventType" }, "timestamp": { "type": "number", "description": "Unix epoch, in nanoseconds, when the event was first created" }, "log-level": { "type": "string", "description": "Logging categorization between", "enum": [ "info", "warn", "error" ], "x-enumDescriptions": { "info": "Info event", "warn": "Warn event", "error": "Error event" } }, "flags": { "type": "object", "properties": { "is-authenticated": { "type": "boolean", "description": "`true` if it’s an outgoing message. `false` if it’s incoming." }, "is-routed": { "type": "boolean", "description": "`true` if the message was sent as a result of a Route match" }, "is-amp": { "type": "boolean", "description": "Tells if the message has AMP component in" }, "is-encrypted": { "type": "boolean", "description": "Tells if the message has been encrypted before stored" }, "is-test-mode": { "type": "boolean", "description": "If `true`, the message has been marked as delivered but the actual send stop before sending to the ESP" } } }, "reject": { "type": "object", "properties": { "reason": { "type": "string" }, "description": { "type": "string" } } }, "message": { "$ref": "#/components/schemas/MessageObject" }, "tags": { "type": "array", "items": { "type": "string" } }, "user-variables": { "type": "object", "description": "Variables included in the email" }, "storage": { "type": "object", "properties": { "key": { "type": "string", "description": "Key ID for the stored MIME" }, "url": { "type": "string", "description": "URL for the stored MIME for retrieval, if required" }, "region": { "type": "string", "description": "The datacenter region the message is stored in" } } }, "geolocation": { "type": "object", "description": "Location data based on the client IP", "properties": { "country": { "type": "string" }, "region": { "type": "string" }, "city": { "type": "string" } } }, "client-info": { "type": "object", "properties": { "client-type": { "type": "string", "description": "Categorize client between: mobile browser, library, email client, robot, feed reader or other" }, "client-os": { "type": "string", "description": "The client Operating System" }, "device-type": { "type": "string", "description": "Could be: desktop, mobile, table or unknown" }, "client-name": { "type": "string", "description": "The client product identifier" }, "user-agent": { "type": "string" } } }, "ip": { "type": "string" }, "delivery-status": { "$ref": "#/components/schemas/DeliveryStatusObject" }, "batch": { "type": "object", "properties": { "id": { "type": "string" } } }, "severity": { "$ref": "#/components/schemas/EventSeverityType" }, "recipient-domain": { "type": "string", "description": "ESP domain" }, "recipient-provider": { "type": "string", "description": "Name of the Inbox Provider for the given recipient, if known" }, "template": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the template the message was rendered from, if given" }, "version": { "type": "string", "description": "The version of the template that was rendered" }, "is-text": { "type": "string", "description": "Tell if the template is considered as plain text (in opposition to ‘html’)" } } }, "envelope": { "$ref": "#/components/schemas/EnvelopeObject" } } }, "MessageObject": { "type": "object", "title": "MessageObject", "properties": { "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "The name of the file attached to the message" }, "content-type": { "type": "string", "description": "The type of the content attached to the message" }, "size": { "type": "integer", "description": "The attachment size in bytes" } }, "required": [ "filename", "content-type", "size" ] } }, "headers": { "type": "object", "properties": { "message-id": { "type": "string" }, "from": { "type": "string", "description": "Message FROM header" }, "to": { "type": "string", "description": "Message TO header" }, "subject": { "type": "string", "description": "Message Subject" } }, "required": [ "message-id", "from" ] }, "size": { "type": "integer", "description": "Total message size, in bytes" }, "scheduled-for": { "type": "string", "description": "Date/Time the message was scheduled for delivery on ingest" } }, "required": [ "headers", "attachments", "size" ] }, "DeliveryStatusObject": { "type": "object", "title": "DeliveryStatusObject", "properties": { "code": { "type": "integer", "description": "SMTP status code received as a result of the ESP session" }, "attempt-no": { "type": "integer", "description": "The current attempt number trying to deliver the message to the ESP" }, "message": { "type": "string" }, "description": { "type": "string" }, "enhanced-code": { "type": "string", "description": "A more specific SMTP error code from the ESP" }, "mxhost": { "type": "string", "description": "The mailing host connected to for the SMTP session" }, "certificate-verified": { "type": "boolean" }, "tls": { "type": "boolean", "description": "True if the SMTP session was performed over a TLS connection with the ESP" }, "utf8": { "type": "boolean", "description": "True if the SMTP session was able to use UTF-8 encoding" }, "first-delivery-attempt-seconds": { "type": "number", "description": "Time elapsed between when the message is accepted by us and the first delivery attempt to the email service provider (ESP)" }, "session-seconds": { "type": "number", "description": "The time, in seconds, the SMTP session for this message took" }, "retry-seconds": { "type": "integer", "description": "If the message failed for a reason that can be retried, the number of seconds between retry attempts. This value changes as the number of retries grows!" } } }, "EnvelopeObject": { "type": "object", "title": "EnvelopeObject", "properties": { "sender": { "type": "string", "description": "The sender address" }, "targets": { "type": "string", "description": "The recipient address" }, "transport": { "type": "string", "description": "The protocol used to make the send. Either http or smtp" }, "sending-ip": { "type": "string", "description": "The Mailgun IP the email has been sent from" } } }, "EventType": { "type": "string", "description": "The event name. See [Events](https://documentation.mailgun.com/docs/mailgun/user-manual/events/#introduction-to-events)", "enum": [ "accepted", "delivered", "failed", "rejected", "clicked", "opened", "unsubscribed", "stored", "complained", "email_validation", "list_member_uploaded", "list_member_upload_error", "list_uploaded" ], "x-enumDescriptions": { "accepted": "Mailgun accepted the request to send/forward the email and the message has been placed in queue", "delivered": "Mailgun sent the email, and it was accepted by the recipient email server", "failed": "Mailgun could not deliver the email to the recipient email server", "rejected": "Mailgun rejected the request to send/forward the email", "clicked": "The email recipient clicked on a link in the email. Click tracking must be enabled in the Mailgun control panel, and the CNAME record must be pointing to mailgun.org", "opened": "The email recipient opened the email and enabled image viewing. Open tracking must be enabled in the Mailgun control panel, and the CNAME record must be pointing to mailgun.org", "unsubscribed": "The email recipient clicked on the unsubscribe link. Unsubscribe tracking must be enabled in the Mailgun control panel", "stored": "Mail has stored an incoming message", "complained": "The email recipient clicked on the spam complaint button within their email client. Feedback loops enable the notification to be received by Mailgun.", "email_validation": "This event occurs onto email validation", "list_member_uploaded": "This event occurs after successfully adding a member to a mailing list", "list_member_upload_error": "This even occurs if an error occurs adding a member to a mailing list", "list_uploaded": "This event occurs after successfully uploading a large list of members to a mailing list." } }, "EventSeverityType": { "description": "Filter by event severity, if exists. Currently for failed events only. See [Tracking Failures](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/#tracking-failures)", "type": "string", "enum": [ "temporary", "permanent" ], "x-enumDescriptions": { "temporary": "Mailgun could not deliver the email to the recipient email server, but will retry", "permanent": "Mailgun could not deliver the email to the recipient email server, and will drop the message without retrying sending." } }, "github.com-mailgun-scout-model-tags-TagItem": { "type": "object", "properties": { "tag": { "type": "string" }, "description": { "type": "string" }, "first-seen": { "type": "string", "format": "date-time" }, "last-seen": { "type": "string", "format": "date-time" } }, "required": [ "tag", "description" ] }, "github.com-mailgun-scout-api-TagListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-tags-TagItem" } }, "paging": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse" } }, "required": [ "items", "paging" ] }, "github.com-mailgun-scout-api-TagAggregateResponse": { "type": "object", "properties": { "tag": { "type": "string" }, "provider": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } }, "country": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } }, "device": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } } } }, "github.com-mailgun-scout-model-types-StatType": { "type": "object", "properties": { "type": { "type": "string" }, "key": { "type": "string" } }, "required": [ "type", "key" ] }, "github.com-mailgun-scout-model-stats-Accepted": { "type": "object", "properties": { "incoming": { "type": "integer", "format": "int32" }, "outgoing": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int32" } }, "required": [ "incoming", "outgoing", "total" ] }, "github.com-mailgun-scout-model-stats-Delivered": { "type": "object", "properties": { "smtp": { "type": "integer", "format": "int32" }, "http": { "type": "integer", "format": "int32" }, "optimized": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int32" } }, "required": [ "smtp", "http", "optimized", "total" ] }, "github.com-mailgun-scout-model-stats-Failed": { "type": "object", "properties": { "temporary": { "type": "object", "properties": { "espblock": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int32" } }, "required": [ "espblock", "total" ] }, "permanent": { "type": "object", "properties": { "suppress-bounce": { "type": "integer", "format": "int32" }, "suppress-unsubscribe": { "type": "integer", "format": "int32" }, "suppress-complaint": { "type": "integer", "format": "int32" }, "bounce": { "type": "integer", "format": "int32" }, "delayed-bounce": { "type": "integer", "format": "int32" }, "webhook": { "type": "integer", "format": "int32" }, "optimized": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int32" } }, "required": [ "suppress-bounce", "suppress-unsubscribe", "suppress-complaint", "bounce", "delayed-bounce", "webhook", "optimized", "total" ] } }, "required": [ "temporary", "permanent" ] }, "github.com-mailgun-scout-model-stats-Stored": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-Opened": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" }, "unique": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-Clicked": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" }, "unique": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-Unsubscribed": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-Complained": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-Campaign": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-EmailValidation": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" }, "public": { "type": "integer", "format": "int32" }, "valid": { "type": "integer", "format": "int32" }, "single": { "type": "integer", "format": "int32" }, "bulk": { "type": "integer", "format": "int32" }, "list": { "type": "integer", "format": "int32" }, "mailgun": { "type": "integer", "format": "int32" }, "mailjet": { "type": "integer", "format": "int32" } }, "required": [ "total", "public", "valid", "single", "bulk", "list", "mailgun", "mailjet" ] }, "github.com-mailgun-scout-model-stats-SeedTest": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-BlocklistMonitoring": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-EmailPreview": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-EmailPreviewFailed": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-LinkValidation": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-LinkValidationFailed": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-scout-model-stats-StatsItem": { "type": "object", "properties": { "time": { "type": "string" }, "accepted": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-Accepted" }, "delivered": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-Delivered" }, "failed": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-Failed" }, "stored": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-Stored" }, "opened": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-Opened" }, "clicked": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-Clicked" }, "unsubscribed": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-Unsubscribed" }, "complained": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-Complained" }, "campaign": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-Campaign" }, "email_validation": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-EmailValidation" }, "seed_test": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-SeedTest" }, "ip_blocklist_monitoring": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-BlocklistMonitoring" }, "domain_blocklist_monitoring": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-BlocklistMonitoring" }, "email_preview": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-EmailPreview" }, "email_preview_failed": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-EmailPreviewFailed" }, "link_validation": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-LinkValidation" }, "link_validation_failed": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-LinkValidationFailed" } }, "required": [ "time" ] }, "github.com-mailgun-scout-api-StatsResponse": { "type": "object", "properties": { "tag": { "type": "string" }, "description": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "type": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-types-StatType" }, "resolution": { "type": "string" }, "stats": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-scout-model-stats-StatsItem" } } }, "required": [ "description", "start", "end", "resolution", "stats" ] }, "github.com-mailgun-scout-api-StatTypesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } } }, "required": [ "items" ] }, "github.com-mailgun-scout-model-types-TagLimitItem": { "type": "object", "properties": { "id": { "type": "string" }, "limit": { "type": "integer", "format": "int32" }, "count": { "type": "integer", "format": "int32" } }, "required": [ "limit", "count" ] }, "github.com-mailgun-scout-api-ProvidersAggregateResponse": { "type": "object", "properties": { "providers": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } } } }, "github.com-mailgun-scout-api-DevicesAggregateResponse": { "type": "object", "properties": { "devices": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } } } }, "github.com-mailgun-scout-api-CountriesAggregateResponse": { "type": "object", "properties": { "countries": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } } } }, "github.com-mailgun-analytics-client-golang-Pagination": { "type": "object", "properties": { "sort": { "type": "string", "description": "Colon-separated value indicating column name and sort direction e.g. 'domain:asc'." }, "skip": { "type": "integer", "format": "int64", "description": "The number of items to skip over when satisfying the request. To get the first page of data set skip to zero. Then increment the skip by the limit for subsequent calls." }, "limit": { "type": "integer", "format": "int64", "description": "The maximum number of items returned in the response." }, "total": { "type": "integer", "format": "int64", "description": "The total number of items in the query result set." } }, "required": [ "sort", "skip", "limit", "total" ] }, "github.com-mailgun-analytics-client-golang-Dimension": { "type": "object", "properties": { "dimension": { "type": "string", "description": "The dimension" }, "value": { "type": "string", "description": "The dimension value" }, "display_value": { "type": "string", "description": "The dimension value in displayable form" } }, "required": [ "dimension", "value", "display_value" ] }, "github.com-mailgun-analytics-internal-api-RegularMetrics": { "type": "object", "properties": { "accepted_incoming_count": { "type": [ "integer", "null" ], "format": "int64" }, "accepted_outgoing_count": { "type": [ "integer", "null" ], "format": "int64" }, "accepted_count": { "type": [ "integer", "null" ], "format": "int64" }, "delivered_smtp_count": { "type": [ "integer", "null" ], "format": "int64" }, "delivered_http_count": { "type": [ "integer", "null" ], "format": "int64" }, "delivered_optimized_count": { "type": [ "integer", "null" ], "format": "int64" }, "delivered_count": { "type": [ "integer", "null" ], "format": "int64" }, "stored_count": { "type": [ "integer", "null" ], "format": "int64" }, "processed_count": { "type": [ "integer", "null" ], "format": "int64" }, "sent_count": { "type": [ "integer", "null" ], "format": "int64" }, "opened_count": { "type": [ "integer", "null" ], "format": "int64" }, "clicked_count": { "type": [ "integer", "null" ], "format": "int64" }, "unique_opened_count": { "type": [ "integer", "null" ], "format": "int64" }, "unique_clicked_count": { "type": [ "integer", "null" ], "format": "int64" }, "unsubscribed_count": { "type": [ "integer", "null" ], "format": "int64" }, "complained_count": { "type": [ "integer", "null" ], "format": "int64" }, "failed_count": { "type": [ "integer", "null" ], "format": "int64" }, "temporary_failed_count": { "type": [ "integer", "null" ], "format": "int64" }, "permanent_failed_count": { "type": [ "integer", "null" ], "format": "int64" }, "temporary_failed_esp_block_count": { "type": [ "integer", "null" ], "format": "int64", "description": "Use instead of esp_block_count." }, "permanent_failed_esp_block_count": { "type": [ "integer", "null" ], "format": "int64" }, "rate_limit_count": { "type": [ "integer", "null" ], "format": "int64" }, "webhook_count": { "type": [ "integer", "null" ], "format": "int64" }, "permanent_failed_optimized_count": { "type": [ "integer", "null" ], "format": "int64" }, "permanent_failed_old_count": { "type": [ "integer", "null" ], "format": "int64" }, "bounced_count": { "type": [ "integer", "null" ], "format": "int64" }, "hard_bounces_count": { "type": [ "integer", "null" ], "format": "int64" }, "soft_bounces_count": { "type": [ "integer", "null" ], "format": "int64" }, "delayed_bounce_count": { "type": [ "integer", "null" ], "format": "int64" }, "suppressed_bounces_count": { "type": [ "integer", "null" ], "format": "int64" }, "suppressed_unsubscribed_count": { "type": [ "integer", "null" ], "format": "int64" }, "suppressed_complaints_count": { "type": [ "integer", "null" ], "format": "int64" }, "delivered_first_attempt_count": { "type": [ "integer", "null" ], "format": "int64" }, "delayed_first_attempt_count": { "type": [ "integer", "null" ], "format": "int64" }, "delivered_subsequent_count": { "type": [ "integer", "null" ], "format": "int64" }, "delivered_two_plus_attempts_count": { "type": [ "integer", "null" ], "format": "int64" }, "delivered_rate": { "type": "string" }, "opened_rate": { "type": "string" }, "clicked_rate": { "type": "string" }, "unique_opened_rate": { "type": "string" }, "unique_clicked_rate": { "type": "string" }, "unsubscribed_rate": { "type": "string" }, "complained_rate": { "type": "string" }, "bounce_rate": { "type": "string" }, "fail_rate": { "type": "string" }, "permanent_fail_rate": { "type": "string" }, "temporary_fail_rate": { "type": "string" }, "delayed_rate": { "type": "string" } } }, "github.com-mailgun-analytics-internal-api-RegularItem": { "type": "object", "properties": { "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-Dimension" } }, "metrics": { "$ref": "#/components/schemas/github.com-mailgun-analytics-internal-api-RegularMetrics" } } }, "github.com-mailgun-analytics-internal-api-RegularAggregates": { "type": "object", "properties": { "metrics": { "$ref": "#/components/schemas/github.com-mailgun-analytics-internal-api-RegularMetrics" } }, "required": [ "metrics" ] }, "github.com-mailgun-analytics-internal-api-RegularMetricsResponse": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "resolution": { "type": "string" }, "duration": { "type": "string" }, "dimensions": { "type": "array", "items": { "type": "string" } }, "pagination": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-Pagination" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-analytics-internal-api-RegularItem" } }, "aggregates": { "$ref": "#/components/schemas/github.com-mailgun-analytics-internal-api-RegularAggregates" } }, "required": [ "items" ] }, "github.com-mailgun-analytics-client-golang-DimensionName": { "type": "string", "enum": [ "bot", "country", "ip_pool", "recipient_domain", "recipient_provider", "ip", "domain", "tag", "device", "subaccount", "time" ], "description": "Dimension", "x-enumDescriptions": { "bot": "The automated system that engaged with the email, e.g. apple, gmail", "country": "Country from which the email was sent, e.g. US, FR, MX", "ip_pool": "IP pool used to send the email", "recipient_domain": "Recipient domain, e.g. gmail.com", "recipient_provider": "Email service provider of the recipient, e.g. Gmail, Outlook US, Apple", "ip": "IP address used to send the email", "domain": "Domain used to send the email, e.g. example.com", "tag": "Custom tag attached to the message", "device": "Type of device used to send the email, e.g. mobile, desktop", "subaccount": "Subaccount identifier", "time": "The time that your events occurred" } }, "github.com-mailgun-analytics-client-golang-Metric": { "type": "string", "enum": [ "accepted_incoming_count", "accepted_outgoing_count", "accepted_count", "delivered_smtp_count", "delivered_http_count", "delivered_optimized_count", "delivered_count", "processed_count", "sent_count", "opened_count", "clicked_count", "unique_opened_count", "unique_clicked_count", "unsubscribed_count", "complained_count", "failed_count", "temporary_failed_count", "permanent_failed_count", "temporary_failed_esp_block_count", "permanent_failed_esp_block_count", "webhook_count", "rate_limit_count", "permanent_failed_optimized_count", "permanent_failed_old_count", "bounced_count", "hard_bounces_count", "soft_bounces_count", "delayed_bounce_count", "suppressed_bounces_count", "suppressed_unsubscribed_count", "suppressed_complaints_count", "delivered_first_attempt_count", "delayed_first_attempt_count", "delivered_two_plus_attempts_count", "delivered_rate", "opened_rate", "clicked_rate", "unique_opened_rate", "unique_opened_rate", "unsubscribed_rate", "complained_rate", "bounce_rate", "permanent_fail_rate", "temporary_fail_rate", "delayed_rate", "delayed_first_attempt_rate" ], "description": "Metric", "x-enumDescriptions": { "accepted_incoming_count": "Mailgun accepted the API request to forward, and the message has been put in your queue. These accepted events only cover routes, forwards, and mailing lists. Mailing lists will record a single accepted incoming event, with emails sent to recipients recording their own accepted outgoing events.", "accepted_outgoing_count": "Mailgun accepted the API request to send, and the message was put in your queue. Batch sends will result in one additional accepted outgoing event to record the initial batch request. Accepted events are not associated to IP addresses. The “processed” metric can be used in place of accepted to view data by IP.", "accepted_count": "A sum of incoming and outgoing accepted events. This includes all accepted emails to be sent as well as routes, forwards, mailing lists, and batch events. To only view accepted events on emails sent to recipients, use the Accepted Outgoing metric. Accepted events are not associated to IP addresses. The “processed” metric can be used in place of accepted to view similar data by IP.", "delivered_smtp_count": "The count of delivered events for emails sent to recipient addresses.", "delivered_http_count": "The count of delivered events for routes and forwards.", "delivered_optimized_count": "Emails delivered with Send Time Optimization.", "delivered_count": "Mailgun sent the email and it was accepted by the recipient email server.", "processed_count": "Messages processed after being accepted. Processed messages are billed to your account at the end of the month.", "sent_count": "A count of all sent messages. This includes delivered and failed messages, but does not include suppressed messages.", "opened_count": "The email recipient opened the email and enabled image viewing. Tracking must be turned on.", "clicked_count": "The email recipient clicked on a link in the email. Click tracking must be turned on and the CNAME record must be pointing to mailgun.org.", "unique_opened_count": "A unique count of open events. Opens are deduplicated on a rolling seven days. If you’re viewing two weeks of data, it’s possible to see two unique open events for a single delivered event. Keep in mind date ranges when viewing unique opens, if your date filter doesn’t include the delivery event, you may see more unique opens than delivered events.", "unique_clicked_count": "A unique count of click events. Clicks are deduplicated on a rolling seven days. If you’re viewing two weeks of data, it’s possible to see two unique click events for a single delivered event. Keep in mind date ranges when viewing unique clicks, if your date filter doesn’t include the delivery event, you may see more unique clicks than delivered events.", "unsubscribed_count": "The email recipient clicked on the unsubscribe link. Unsubscribe tracking must be turned on.", "complained_count": "The email recipient clicked on the spam complaint button and the recipient's email server provides feedback loops to Mailgun for these complaints.", "failed_count": "A sum of all permanent and temporary failures.", "temporary_failed_count": "Mailgun could not deliver the email to the recipient email server, but will retry.", "permanent_failed_count": "Mailgun could not deliver the email to the recipient email server, and will drop the message without retrying sending.", "temporary_failed_esp_block_count": "Emails that were temporarily blocked by the ESP for policy errors and reputation rate limiting.", "permanent_failed_esp_block_count": "Emails that were permanently blocked by the ESP for policy errors and reputation rate limiting.", "webhook_count": "A count of failed webhook events.", "rate_limit_count": "A count of emails that were rate limited by Mailgun.", "permanent_failed_optimized_count": "Events that were sent with send time optimization, but received a permanent failure.", "permanent_failed_old_count": "Mailgun attempted to deliver the email for the maximum number of retry attempts, but received a temporary failure each time. Upon the last retry attempt, the message was classified as a ”Too Old” permanent failure.", "bounced_count": "A sum of all soft and hard bounces. Permanent failures fall into three categories, soft bounces, hard bounces, and suppressions. This field is equal to permanent failures minus suppressions.", "hard_bounces_count": "A hard bounce is a message that cannot be delivered to its intended recipient due to an invalid recipient address or non-existent mailbox. These addresses will be automatically added to your suppressions list when you receive a hard bounce to prevent subsequent hard bounces.", "soft_bounces_count": "A soft bounce is a message that cannot be delivered to its intended recipient due to a temporary delivery issue, often stemming from a server outage, full mailbox, oversize files/messages, blocklistings, or reputation issues. Mailgun treats soft bounces as permanent failures, meaning we will not automatically attempt to redeliver the message. The recipient address will not be added to the suppression list, and the next time you attempt to send a message to this recipient we will attempt to deliver.", "delayed_bounce_count": "Emails were initially marked as delivered, but later received a permanent failure from the mailbox provider.", "suppressed_bounces_count": "The email was suppressed due to a previous bounce with the recipient address. No delivery attempt was made.", "suppressed_unsubscribed_count": "The email was suppressed due to a previous unsubscribe from the recipient. No delivery attempt was made.", "suppressed_complaints_count": "The email was suppressed due to a previous complaint from the recipient. No delivery attempt was made.", "delivered_first_attempt_count": "Emails that were delivered on the first delivery attempt without being delayed or bounced.", "delayed_first_attempt_count": "Emails that were temporarily rejected on the first delivery attempt. These emails will have been retried until delivery or until a “too old” permanent failure is generated.", "delivered_two_plus_attempts_count": "Emails that were delivered after two or more delivery attempts. This indicates the emails received at least one temporary failure.", "delivered_rate": "The rate at which sent emails are delivered to recipient addresses. This calculation does not include suppressed emails.", "opened_rate": "The rate at which delivered emails are opened. This calculation uses total opens, not unique opens. Use the unique open rate if percentages exceed 100%.", "clicked_rate": "The rate at which delivered emails are clicked. This calculation uses total clicks, not unique clicks. Use the unique click rate if percentages exceed 100%.", "unique_opened_rate": "The percentage of delivered emails that resulted in a unique click event. This calculation will exceed 100% if your date filter excludes a large amount of delivery events.", "unsubscribed_rate": "The unsubscribe rate accounts for the total number of unsubscribes divided by the total number of emails delivered and multiplied by 100, expressed as a percentage.", "complained_rate": "Complaint rate measures the percentages of delivered emails reported as spam by recipients. This rate should be kept below 0.1%. Please note that Gmail does not provide complaints, to see Gmail complaint data, sign up for Google Postmaster Tools.", "bounce_rate": "Bounce rate measures the percentage of emails that bounce back, or the number of emails that couldn’t be delivered to users over the total number of emails sent.", "permanent_fail_rate": "The percentage of sent emails that resulted in a permanent failure. These emails could not be delivered and will not be retried.", "temporary_fail_rate": "The percentage of sent emails that resulted in a temporary failure.", "delayed_rate": "The percentage of emails that were delivered with two or more delivery attempts. This rate does not include delayed emails that could not be delivered.", "delayed_first_attempt_rate": "The percentage of emails that were delivered with two or more delivery attempts or failed to deliver after repeated attempts. The denominator is the processed_count" } }, "github.com-mailgun-analytics-client-golang-FilterAttribute": { "type": "string", "enum": [ "bot", "country", "ip_pool", "recipient_domain", "recipient_provider", "ip", "domain", "tag", "device", "subaccount" ], "description": "Filter attribute", "x-enumDescriptions": { "bot": "The automated system that engaged with the email, e.g. apple, gmail", "country": "Country from which the email was sent, e.g. US, FR, MX", "ip_pool": "IP pool used to send the email", "recipient_domain": "Recipient domain, e.g. gmail.com", "recipient_provider": "Email service provider of the recipient, e.g. Gmail, Outlook US, Apple", "ip": "IP address used to send the email", "domain": "Domain used to send the email, e.g. example.com", "tag": "Custom tag attached to the message", "device": "Type of device used to send the email, e.g. mobile, desktop", "subaccount": "Subaccount identifier" } }, "github.com-mailgun-analytics-client-golang-FilterComparator": { "type": "string", "enum": [ "=", "!=", "contains", "not contains" ], "description": "Filter comparator", "x-enumDescriptions": { "=": "Equals", "!=": "Not equals", "contains": "Contains", "not contains": "Does not contain" } }, "github.com-mailgun-analytics-client-golang-LabeledValue": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] }, "github.com-mailgun-analytics-client-golang-FilterPredicate": { "type": "object", "properties": { "attribute": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-FilterAttribute" }, "comparator": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-FilterComparator" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-LabeledValue" } } }, "required": [ "attribute", "comparator" ] }, "github.com-mailgun-analytics-client-golang-FilterPredicateGroup": { "type": "object", "properties": { "AND": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-FilterPredicate" } } }, "required": [ "AND" ] }, "github.com-mailgun-analytics-client-golang-Query": { "type": "object", "properties": { "start": { "type": "string", "description": "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": { "type": "string", "description": "An end date (default: current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14" }, "resolution": { "type": "string", "description": "A resolution in the format of 'day' 'hour' 'month'. Default is day." }, "duration": { "type": "string", "description": "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": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-DimensionName" }, "description": "Attributes of the metric data such as 'subaccount'. See [dimensions](https://documentation.mailgun.com/docs/mailgun/user-manual/reporting/dimensions)" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-Metric" }, "description": "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": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-FilterPredicateGroup" } ], "description": "Filters to apply to the query." }, "include_subaccounts": { "type": "boolean", "description": "Include stats from all subaccounts." }, "include_aggregates": { "type": "boolean", "description": "Include top-level aggregate metrics." } } }, "github.com-mailgun-analytics-internal-api-UsageMetrics": { "type": "object", "properties": { "processed_count": { "type": [ "integer", "null" ], "format": "int64" }, "email_validation_count": { "type": [ "integer", "null" ], "format": "int64" }, "email_validation_public_count": { "type": [ "integer", "null" ], "format": "int64" }, "email_validation_valid_count": { "type": [ "integer", "null" ], "format": "int64" }, "email_validation_single_count": { "type": [ "integer", "null" ], "format": "int64" }, "email_validation_bulk_count": { "type": [ "integer", "null" ], "format": "int64" }, "email_validation_list_count": { "type": [ "integer", "null" ], "format": "int64" }, "email_validation_mailgun_count": { "type": [ "integer", "null" ], "format": "int64" }, "email_validation_mailjet_count": { "type": [ "integer", "null" ], "format": "int64" }, "email_preview_count": { "type": [ "integer", "null" ], "format": "int64" }, "email_preview_failed_count": { "type": [ "integer", "null" ], "format": "int64" }, "link_validation_count": { "type": [ "integer", "null" ], "format": "int64" }, "link_validation_failed_count": { "type": [ "integer", "null" ], "format": "int64" }, "seed_test_count": { "type": [ "integer", "null" ], "format": "int64" }, "ip_blocklist_monitoring_count": { "type": [ "integer", "null" ], "format": "int64" }, "domain_blocklist_monitoring_count": { "type": [ "integer", "null" ], "format": "int64" } } }, "github.com-mailgun-analytics-internal-api-UsageItem": { "type": "object", "properties": { "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-Dimension" } }, "metrics": { "$ref": "#/components/schemas/github.com-mailgun-analytics-internal-api-UsageMetrics" } } }, "github.com-mailgun-analytics-internal-api-UsageAggregates": { "type": "object", "properties": { "metrics": { "$ref": "#/components/schemas/github.com-mailgun-analytics-internal-api-UsageMetrics" } }, "required": [ "metrics" ] }, "github.com-mailgun-analytics-internal-api-UsageMetricsResponse": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "resolution": { "type": "string" }, "duration": { "type": "string" }, "dimensions": { "type": "array", "items": { "type": "string" } }, "pagination": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-Pagination" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-analytics-internal-api-UsageItem" } }, "aggregates": { "$ref": "#/components/schemas/github.com-mailgun-analytics-internal-api-UsageAggregates" } }, "required": [ "items" ] }, "github.com-mailgun-analytics-client-golang-UsageDimensionName": { "type": "string", "enum": [ "subaccount", "time" ], "description": "Usage Dimension", "x-enumDescriptions": { "subaccount": "Subaccount identifier", "time": "The time that your events occurred" } }, "github.com-mailgun-analytics-client-golang-UsageMetric": { "type": "string", "enum": [ "email_validation_count", "email_validation_public_count", "email_validation_valid_count", "email_validation_single_count", "email_validation_bulk_count", "email_validation_list_count", "email_validation_mailgun_count", "email_validation_mailjet_count", "email_preview_count", "email_preview_failed_count", "link_validation_count", "link_validation_failed_count", "seed_test_count", "ip_blocklist_monitoring_count", "domain_blocklist_monitoring_count", "accessibility_count", "accessibility_failed_count", "image_validation_count", "image_validation_failed_count", "archived_count", "processed_count" ], "description": "Usage Metric", "x-enumDescriptions": { "email_validation_count": "Total number of email validations performed", "email_validation_public_count": "Number of email validations performed using the public API", "email_validation_valid_count": "Number of email validations that returned a valid result", "email_validation_single_count": "Number of single email validations performed", "email_validation_bulk_count": "Number of bulk email validations performed", "email_validation_list_count": "Number of email list validations performed", "email_validation_mailgun_count": "Number of email validations performed using Mailgun's validation service", "email_validation_mailjet_count": "Number of email validations performed using Mailjet's validation service", "email_preview_count": "Total number of email previews generated", "email_preview_failed_count": "Number of failed email preview generation attempts", "link_validation_count": "Total number of link validations performed", "link_validation_failed_count": "Number of link validations that failed", "seed_test_count": "Number of seed tests conducted", "ip_blocklist_monitoring_count": "Number of IP blocklist monitoring checks performed", "domain_blocklist_monitoring_count": "Number of domain blocklist monitoring checks performed", "accessibility_count": "Total number of accessibility checks performed", "accessibility_failed_count": "Number of accessibility checks that failed", "image_validation_count": "Total number of image validations performed", "image_validation_failed_count": "Number of image validations that failed", "archived_count": "Number of items archived", "processed_count": "Messages processed after being accepted. Processed messages are billed to your account at the end of the month." } }, "github.com-mailgun-analytics-client-golang-UsageQuery": { "type": "object", "properties": { "start": { "type": "string", "description": "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": { "type": "string", "description": "An end date (default: current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14" }, "resolution": { "type": "string", "description": "A resolution in the format of 'day' 'hour' 'month'. Default is day." }, "duration": { "type": "string", "description": "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": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-UsageDimensionName" }, "description": "Attributes of the metric data such as 'subaccount'. See [dimensions](https://documentation.mailgun.com/docs/mailgun/user-manual/reporting/dimensions)" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-UsageMetric" }, "description": "Name of the metrics to receive the stats for such as 'processed_count'." }, "filter": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-FilterPredicateGroup" } ], "description": "Filters to apply to the query." }, "include_subaccounts": { "type": "boolean", "description": "Include stats from all subaccounts." }, "include_aggregates": { "type": "boolean", "description": "Include top-level aggregate metrics." } } }, "github.com-mailgun-logs-api-pkg-api-model-Account": { "type": "object", "properties": { "parent-id": { "type": "string" }, "id": { "type": "string" } } }, "github.com-mailgun-logs-api-pkg-api-model-Campaign": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "github.com-mailgun-logs-api-pkg-api-model-DeliveryStatus": { "type": "object", "properties": { "message": { "type": "string" }, "attempt-no": { "type": "integer", "format": "int32" }, "code": { "type": "integer", "format": "int32" }, "bounce-type": { "type": "string" }, "description": { "type": "string" }, "session-seconds": { "type": "number", "format": "float" }, "retry-seconds": { "type": "integer", "format": "int32" }, "enhanced-code": { "type": "string" }, "mx-host": { "type": "string" }, "certificate-verified": { "type": "boolean" }, "tls": { "type": "boolean" }, "utf8": { "type": "boolean" }, "first-delivery-attempt-seconds": { "type": "number", "format": "float" }, "last-code": { "type": "integer", "format": "int32" }, "last-message": { "type": "string" } } }, "github.com-mailgun-logs-api-pkg-api-model-Domain": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "github.com-mailgun-logs-api-pkg-api-model-Envelope": { "type": "object", "properties": { "sender": { "type": "string" }, "transport": { "type": "string" }, "sending-ip": { "type": "string" }, "targets": { "type": "string" }, "i-ip-pool-id": { "type": "string" } } }, "github.com-mailgun-logs-api-pkg-api-model-Storage": { "type": "object", "properties": { "region": { "type": "string" }, "env": { "type": "string" }, "key": { "type": "string" }, "url": { "type": "array", "items": { "type": "string" } } } }, "github.com-mailgun-logs-api-pkg-api-model-Template": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "is-text": { "type": "boolean" } } }, "github.com-mailgun-logs-api-pkg-api-model-MessageHeaders": { "type": "object", "properties": { "to": { "type": "string" }, "message-id": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" } } }, "github.com-mailgun-logs-api-pkg-api-model-Attachment": { "type": "object", "properties": { "filename": { "type": "string" }, "content-type": { "type": "string" }, "size": { "type": "integer", "format": "int32" } } }, "github.com-mailgun-logs-api-pkg-api-model-Message": { "type": "object", "properties": { "headers": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-MessageHeaders" }, { "type": "null" } ] }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Attachment" } }, "recipients": { "type": "array", "items": { "type": "string" } }, "size": { "type": "integer", "format": "int32" }, "scheduled-for": { "type": "integer", "format": "int64" } } }, "github.com-mailgun-logs-api-pkg-api-model-Flags": { "type": "object", "properties": { "is-authenticated": { "type": "boolean" }, "is-system-test": { "type": "boolean" }, "is-routed": { "type": "boolean" }, "is-amp": { "type": "boolean" }, "is-test-mode": { "type": "boolean" }, "is-delayed-bounce": { "type": "boolean" }, "is-callback": { "type": "boolean" }, "is-encrypted": { "type": "boolean" }, "is-webhook": { "type": "boolean" } }, "required": [ "is-authenticated", "is-system-test", "is-routed", "is-test-mode", "is-delayed-bounce", "is-callback", "is-webhook" ] }, "github.com-mailgun-logs-api-pkg-api-model-GeoLocation": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "region": { "type": "string" }, "timezone": { "type": "string" } } }, "github.com-mailgun-logs-api-pkg-api-model-ClientInfo": { "type": "object", "properties": { "client-name": { "type": "string" }, "client-os": { "type": "string" }, "client-type": { "type": "string" }, "device-type": { "type": "string" }, "user-agent": { "type": "string" }, "ip": { "type": "string" }, "bot": { "type": "string" } } }, "github.com-mailgun-logs-api-pkg-api-model-RoutesMatch": { "type": "object", "properties": { "recipient": { "type": "string" } } }, "github.com-mailgun-logs-api-pkg-api-model-Routes": { "type": "object", "properties": { "actions": { "type": "string" }, "description": { "type": "string" }, "expression": { "type": "string" }, "id": { "type": "string" }, "priority": { "type": "integer", "format": "int32" }, "match": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-RoutesMatch" }, { "type": "null" } ] } } }, "github.com-mailgun-logs-api-pkg-api-model-MailingList": { "type": "object", "properties": { "address": { "type": "string" }, "list-id": { "type": "string" }, "sid": { "type": "string" } } }, "github.com-mailgun-logs-api-pkg-api-model-LogEvent": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "@timestamp": { "type": "string" }, "account": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Account" }, { "type": "null" } ] }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Campaign" } }, "tags": { "type": "array", "items": { "type": "string" } }, "method": { "type": "string" }, "originating-ip": { "type": "string" }, "api-key-id": { "type": "string" }, "delivered-at": { "type": "string" }, "delivery-status": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-DeliveryStatus" }, { "type": "null" } ] }, "i-delivery-optimizer": { "type": "string" }, "domain": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Domain" }, { "type": "null" } ] }, "recipient": { "type": "string" }, "recipient-domain": { "type": "string" }, "recipient-provider": { "type": "string" }, "envelope": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Envelope" }, { "type": "null" } ] }, "storage": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Storage" }, { "type": "null" } ] }, "template": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Template" }, { "type": "null" } ] }, "log-level": { "type": "string" }, "user-variables": { "type": "string" }, "message": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Message" }, { "type": "null" } ] }, "flags": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Flags" }, { "type": "null" } ] }, "primary-dkim": { "type": "string" }, "ip": { "type": "string" }, "geolocation": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-GeoLocation" }, { "type": "null" } ] }, "client-info": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-ClientInfo" }, { "type": "null" } ] }, "severity": { "type": "string" }, "reason": { "type": "string" }, "routes": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Routes" }, { "type": "null" } ] }, "mailing-list": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-MailingList" }, { "type": "null" } ] }, "url": { "type": "string" } }, "required": [ "id", "event", "@timestamp", "domain" ] }, "github.com-mailgun-logs-api-pkg-api-model-PagingResponse": { "type": "object", "properties": { "previous": { "type": "string", "description": "Token to previous page" }, "next": { "type": "string", "description": "Token to next page" }, "first": { "type": "string", "description": "Token to first page" }, "last": { "type": "string", "description": "Token to last page" }, "total": { "type": "integer", "format": "int64", "description": "Total number of items" } } }, "github.com-mailgun-logs-api-pkg-api-model-Aggregates": { "type": "object", "properties": { "all": { "type": "integer", "format": "int64" }, "metrics": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" } } } }, "github.com-mailgun-logs-api-pkg-api-model-LogsResponse": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-LogEvent" } }, "pagination": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-PagingResponse" }, "aggregates": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Aggregates" } }, "required": [ "start", "end", "items", "pagination" ] }, "github.com-mailgun-logs-api-pkg-api-model-Event": { "type": "string", "enum": [ "accepted", "delivered", "failed", "opened", "unique_opened", "clicked", "unique_clicked", "unsubscribed", "complained", "rejected", "stored", "email_validation", "list_uploaded", "list_member_uploaded", "list_member_upload_error", "trapped" ], "description": "Events", "x-enumDescriptions": { "accepted": "logs with event=accepted", "delivered": "logs with event=delivered", "failed": "logs with event=failed", "opened": "logs with event=opened", "unique_opened": "logs with event=opened unique per message-id, recipient combination", "clicked": "logs with event=clicked", "unique_clicked": "logs with event=clicked unique per message-id, recipient combination", "unsubscribed": "logs with event=unsubscribed", "complained": "logs with event=complained", "rejected": "logs with event=rejected", "stored": "logs with event=stored", "email_validation": "logs with event=email_validation", "list_uploaded": "logs with event=list_uploaded", "list_member_uploaded": "logs with event=list_member_uploaded", "list_member_upload_error": "logs with event=list_member_upload_error", "trapped": "logs with event=trapped" } }, "github.com-mailgun-logs-api-pkg-api-model-MetricEvent": { "type": "string", "enum": [ "accepted_incoming", "accepted_outgoing", "accepted", "delivered_smtp", "delivered_http", "delivered_optimized", "delivered", "stored", "opened", "clicked", "unique_opened", "unique_clicked", "complained", "unsubscribed", "failed", "processed", "sent", "temporary_failed", "permanent_failed", "esp_block", "temporary_failed_esp_block", "permanent_failed_esp_block", "webhook_failure", "permanent_failed_optimized", "permanent_failed_old", "bounced", "hard_bounces", "soft_bounces", "delayed_bounce", "suppressed_bounces", "suppressed_unsubscribed", "suppressed_complaints", "delivered_first_attempt", "delivered_subsequent", "delivered_two_plus_attempts", "delayed_first_attempt" ], "description": "Metric Events", "x-enumDescriptions": { "accepted_incoming": "accepted events where flags.is_authenticated is false", "accepted_outgoing": "accepted events where flags.is_authenticated is true", "accepted": "all accepted events", "delivered_smtp": "delivered events where envelope.transport is smtp", "delivered_http": "delivered events where envelope.transport is http", "delivered_optimized": "delivered events where i-delivery-optimizer is set", "delivered": "all delivered events", "stored": "all stored events", "opened": "all opened events", "clicked": "all clicked events", "unique_opened": "opened events that are unique for the message id and recipient", "unique_clicked": "clicked events that are unique for the message id and recipient", "complained": "all complained events", "unsubscribed": "all unsubscribed events", "failed": "all failed events. Does not include internal failures or failures associated with webhooks only delivery failures", "processed": "all processed events (delivered or failed events)", "sent": "all sent events (deliverd or failed events not including suppressions or webhooks)", "temporary_failed": "failure events where the severity is temporary", "permanent_failed": "failure events where the severity is permanent", "esp_block": "failure events where the failure reason is espblock", "temporary_failed_esp_block": "failure events where the failure reason is espblock and the severity is temporary", "permanent_failed_esp_block": "failure events where the failure reason is espblock and the severity is permanent", "webhook_failure": "failed webhook events", "permanent_failed_optimized": "failed events where the severity is permanent and the ", "permanent_failed_old": "failed events where the severity is permanent", "bounced": "all permanent failed events other than suppresions or webhook failures", "hard_bounces": "failed events where delivery-status.bounce-type is hard", "soft_bounces": "failed events where delivery-status.bounce-type is soft", "delayed_bounce": "permanent failed events where flags.is-delayed-bounce is true", "suppressed_bounces": "permanent failed events where reason is suppress-bounce", "suppressed_unsubscribed": "permanent failed events where reason is suppress-unsubscribe", "suppressed_complaints": "permanent failed events where reason is suppress-complaint", "delivered_first_attempt": "delivered events that succeeded on the first attempt", "delivered_subsequent": "delivered events that failed on the first attempt but were eventually successful", "delivered_two_plus_attempts": "delivered events that required two or more delivery attempts", "delayed_first_attempt": "delivered events that failed the first attempt or failed events where reason is old" } }, "github.com-mailgun-logs-api-pkg-api-model-FilterAttribute": { "type": "string", "enum": [ "id", "domain", "ip", "ip_pool", "recipient_domain", "recipient_provider", "country", "bot", "device", "subaccount", "event", "attachment_filename", "from", "message_id", "subject", "mailing_list_address", "to", "size", "recipient", "tag", "severity", "user_variables", "delivered_at", "delivery_status_code", "delivery_status_bounce_type", "delivery_status_message", "is_routed", "i_classification_rule_id", "i_classification_group_id", "recipients" ], "description": "Filter Attribute", "x-enumDescriptions": { "id": "Filter on a specific id of a log message. Mostly used to retrieve a specific log found in Kibana", "domain": "Filter on a given sender domain used for delivery", "ip": "Filter on the ip address used for delivery", "ip_pool": "Filter on the name of the ip pool used for delivery", "recipient_domain": "Filter on the domain of the email recipient", "recipient_provider": "Filter on the email provider of the recipient", "country": "For open and click events, filter on the country of the email recipient", "bot": "For open and click events, filter on the client-info.bot field which tracks if an actual person triggered the event, or an email client program", "device": "For open and click events, filter on the device the email recipient was using when openning or clicking on the email.", "subaccount": "Filter to events generated for a subaccount", "event": "Filter for a specific event by name. Since `metric_events` can be comprised of multiple events, this can be used to drill into a specific event.", "attachment_filename": "Filter delivered events for those containing an attachment with a given filename", "from": "Filter for events with a given from address", "message_id": "Filter for events with a given message-id header. A message ID ties together the accepted, delivered, and any failed events over the lifecycle of the email", "subject": "Filter for emails with a given subject", "mailing_list_address": "Filter for emails with a given mailing list address", "to": "Filter for emails with a given to field. This can contain a mailing list and can also contain the display name of the email recipient such as John Doe", "size": "Filter emails based on size in bytes. This field must use < or > as the comparator", "recipient": "Filter for emails with a given recipient, which is an email address", "tag": "Filter for emails with a given tag (or tags if using the contains comparator)", "severity": "Filter failure events based on their severity. Possible values are either temporary or permanent", "user_variables": "Filter on user defined variables associated with the email. User variables are stored as a flat JSON string and filters search against keys or values", "delivered_at": "Filter for deliveries that occured before or after a given time, given as RFC1123Z. Comparator must be < or >", "delivery_status_code": "Filter for failure or delivery events with a specific delivery code", "delivery_status_bounce_type": "Filter for a given bounce type. Either soft or hard", "delivery_status_message": "Filter for a status message. Like `delivery_status_code` but checks against a status message string", "is_routed": "Filter on the flags.is_routed boolean flag", "i_classification_rule_id": "Filter on the i-classification.rule-id associated with a bounce classification rule", "i_classification_group_id": "Filter on the i-classification.group-id associated with a bounce classification group", "recipients": "Filter on the list of email message recipients. Must use the \"contains\" or \"not contains\" comparators" } }, "github.com-mailgun-logs-api-pkg-api-model-LabeledValue": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] }, "github.com-mailgun-logs-api-pkg-api-model-FilterPredicate": { "type": "object", "properties": { "attribute": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-FilterAttribute" }, "comparator": { "type": "string" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-LabeledValue" } } }, "required": [ "attribute", "comparator", "values" ] }, "github.com-mailgun-logs-api-pkg-api-model-FilterPredicateGroup": { "type": "object", "properties": { "AND": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-FilterPredicate" } } }, "required": [ "AND" ] }, "github.com-mailgun-logs-api-pkg-api-model-Pagination": { "type": "object", "properties": { "sort": { "type": "string", "description": "Colon-separated value indicating column name and sort direction e.g. 'timestamp:desc'." }, "token": { "type": "string", "description": "A token to the requested page." }, "limit": { "type": "integer", "format": "int32", "description": "The maximum number of items returned (100 max)." } } }, "github.com-mailgun-logs-api-pkg-api-model-LogsRequest": { "type": "object", "properties": { "start": { "type": "string", "description": "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": { "type": "string", "description": "The end date (default: current time). Must be in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14" }, "duration": { "type": "string", "description": "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": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Event" }, "description": "The set of events to include." }, "metric_events": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-MetricEvent" }, "description": "Optional set of analytics metric events. Will be converted into corresponding events." }, "filter": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-FilterPredicateGroup" } ], "description": "Filters to apply to the query." }, "include_subaccounts": { "type": "boolean", "description": "Include logs from all subaccounts." }, "include_totals": { "type": "boolean", "description": "Include total number of log entries." }, "pagination": { "$ref": "#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Pagination" } }, "required": [ "duration" ] }, "github.com-mailgun-tags-api-pkg-api-model-CustomTime": { "type": "object" }, "github.com-mailgun-analytics-client-golang-Metrics": { "type": "object", "properties": { "accepted_incoming_count": { "type": "integer", "format": "int64" }, "accepted_outgoing_count": { "type": "integer", "format": "int64" }, "accepted_count": { "type": "integer", "format": "int64" }, "delivered_smtp_count": { "type": "integer", "format": "int64" }, "delivered_http_count": { "type": "integer", "format": "int64" }, "delivered_optimized_count": { "type": "integer", "format": "int64" }, "delivered_count": { "type": "integer", "format": "int64" }, "stored_count": { "type": "integer", "format": "int64" }, "sent_count": { "type": "integer", "format": "int64" }, "opened_count": { "type": "integer", "format": "int64" }, "clicked_count": { "type": "integer", "format": "int64" }, "unique_opened_count": { "type": "integer", "format": "int64" }, "unique_clicked_count": { "type": "integer", "format": "int64" }, "unsubscribed_count": { "type": "integer", "format": "int64" }, "complained_count": { "type": "integer", "format": "int64" }, "failed_count": { "type": "integer", "format": "int64" }, "temporary_failed_count": { "type": "integer", "format": "int64" }, "permanent_failed_count": { "type": "integer", "format": "int64" }, "esp_block_count": { "type": "integer", "format": "int64" }, "temporary_failed_esp_block_count": { "type": "integer", "format": "int64" }, "permanent_failed_esp_block_count": { "type": "integer", "format": "int64" }, "rate_limit_count": { "type": "integer", "format": "int64" }, "webhook_count": { "type": "integer", "format": "int64" }, "permanent_failed_optimized_count": { "type": "integer", "format": "int64" }, "permanent_failed_old_count": { "type": "integer", "format": "int64" }, "bounced_count": { "type": "integer", "format": "int64" }, "hard_bounces_count": { "type": "integer", "format": "int64" }, "soft_bounces_count": { "type": "integer", "format": "int64" }, "delayed_bounce_count": { "type": "integer", "format": "int64" }, "suppressed_bounces_count": { "type": "integer", "format": "int64" }, "suppressed_unsubscribed_count": { "type": "integer", "format": "int64" }, "suppressed_complaints_count": { "type": "integer", "format": "int64" }, "delivered_first_attempt_count": { "type": "integer", "format": "int64" }, "delayed_first_attempt_count": { "type": "integer", "format": "int64" }, "delivered_subsequent_count": { "type": "integer", "format": "int64" }, "delivered_two_plus_attempts_count": { "type": "integer", "format": "int64" }, "processed_count": { "type": "integer", "format": "int64" }, "delivered_rate": { "type": "string" }, "opened_rate": { "type": "string" }, "clicked_rate": { "type": "string" }, "unique_opened_rate": { "type": "string" }, "unique_clicked_rate": { "type": "string" }, "unsubscribed_rate": { "type": "string" }, "complained_rate": { "type": "string" }, "bounce_rate": { "type": "string" }, "hard_bounce_rate": { "type": "string" }, "soft_bounce_rate": { "type": "string" }, "fail_rate": { "type": "string" }, "permanent_fail_rate": { "type": "string" }, "temporary_fail_rate": { "type": "string" }, "delayed_rate": { "type": "string" }, "email_validation_count": { "type": "integer", "format": "int64" }, "email_validation_public_count": { "type": "integer", "format": "int64" }, "email_validation_valid_count": { "type": "integer", "format": "int64" }, "email_validation_single_count": { "type": "integer", "format": "int64" }, "email_validation_bulk_count": { "type": "integer", "format": "int64" }, "email_validation_list_count": { "type": "integer", "format": "int64" }, "email_validation_mailgun_count": { "type": "integer", "format": "int64" }, "email_validation_mailjet_count": { "type": "integer", "format": "int64" }, "email_preview_count": { "type": "integer", "format": "int64" }, "email_preview_failed_count": { "type": "integer", "format": "int64" }, "link_validation_count": { "type": "integer", "format": "int64" }, "link_validation_failed_count": { "type": "integer", "format": "int64" }, "seed_test_count": { "type": "integer", "format": "int64" }, "accessibility_count": { "type": "integer", "format": "int64" }, "accessibility_failed_count": { "type": "integer", "format": "int64" }, "image_validation_count": { "type": "integer", "format": "int64" }, "image_validation_failed_count": { "type": "integer", "format": "int64" } } }, "github.com-mailgun-tags-api-pkg-api-model-Tag": { "type": "object", "properties": { "account_id": { "type": "string" }, "parent_account_id": { "type": "string" }, "tag": { "type": "string" }, "description": { "type": "string" }, "first_seen": { "$ref": "#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-CustomTime" }, "last_seen": { "$ref": "#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-CustomTime" }, "metrics": { "$ref": "#/components/schemas/github.com-mailgun-analytics-client-golang-Metrics" }, "account_name": { "type": "string" } }, "required": [ "account_id", "parent_account_id", "tag", "description", "account_name" ] }, "github.com-mailgun-tags-api-pkg-api-model-Pagination": { "type": "object", "properties": { "sort": { "type": "string", "description": "Colon-separated value indicating column name and sort direction e.g. 'lastseen:desc'." }, "skip": { "type": "integer", "format": "int64", "description": "The number of items to skip over when satisfying the request. To get the first page of data set skip to zero. Then increment the skip by the limit for subsequent calls." }, "limit": { "type": "integer", "format": "int64", "description": "The maximum number of items returned in the response. Default 10 max 1000." }, "total": { "type": "integer", "format": "int64", "description": "The total number of tags matching the search criteria." }, "include_total": { "type": "boolean", "description": "Boolean indicating whether or not to include total number of items. Default false." } } }, "github.com-mailgun-tags-api-pkg-api-model-TagsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-Tag" } }, "pagination": { "$ref": "#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-Pagination" } }, "required": [ "items" ] }, "github.com-mailgun-tags-api-pkg-api-model-ListTagsRequest": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-Pagination" }, "include_subaccounts": { "type": "boolean", "description": "Boolean indicating whether or not to include data from all subaccounts. Default false." }, "include_metrics": { "type": "boolean", "description": "Boolean indicating whether or not to include metrics for tags. Default false. When true max limit is 20." }, "tag": { "type": "string", "description": "The tag or tag prefix." } } }, "github.com-mailgun-tags-api-pkg-api-model-UpdateTagRequest": { "type": "object", "properties": { "tag": { "type": "string", "description": "The tag to update." }, "description": { "type": "string", "description": "The updated tag description." } } }, "github.com-mailgun-tags-api-pkg-api-model-DeleteTagRequest": { "type": "object", "properties": { "tag": { "type": "string", "description": "The tag to delete." } } }, "github.com-mailgun-tags-api-pkg-api-model-TagLimitCountResponse": { "type": "object", "properties": { "limit": { "type": "integer", "format": "int32" }, "count": { "type": "integer", "format": "int64" }, "limit_reached": { "type": "boolean" } }, "required": [ "limit", "count", "limit_reached" ] }, "github.com-mailgun-thresholds-api-AlertChannel": { "type": "string", "enum": [ "email", "slack", "webhook" ], "description": "Alert Channel", "x-enumDescriptions": { "email": "Email", "slack": "Slack", "webhook": "Webhook" } }, "github.com-mailgun-thresholds-api-Dimension": { "type": "string", "enum": [ "domain", "ip", "ip_pool", "recipient_provider", "subaccount" ], "description": "Dimension", "x-enumDescriptions": { "domain": "Sender domain name, e.g. example.com", "ip": "Sending IP address", "ip_pool": "IP Pool ID", "recipient_provider": "Recipient Provider, e.g. Gmail, Other US, etc.", "subaccount": "Subaccount name" } }, "github.com-mailgun-thresholds-api-FilterComparator": { "type": "string", "enum": [ "=", "!=", "contains", "not contains", "<", "<=", ">", ">=" ], "description": "Filter Comparator", "x-enumDescriptions": { "=": "Equal", "!=": "Not equal", "contains": "Contains", "not contains": "Does not contain", "<": "Less than", "<=": "Less than or equal", ">": "Greater than", ">=": "Greater than or equal" } }, "github.com-mailgun-thresholds-api-Filter": { "type": "object", "properties": { "dimension": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Dimension" } ], "description": "The dimension to filter by." }, "comparator": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-FilterComparator" } ], "description": "The comparison operator." }, "values": { "type": "array", "items": { "type": "string" }, "description": "The dimension values to apply to filter." } }, "required": [ "dimension", "comparator", "values" ] }, "github.com-mailgun-thresholds-api-Metric": { "type": "string", "enum": [ "hard_bounce_rate", "temporary_fail_rate", "delivered_rate", "complained_rate" ], "description": "Metric", "x-enumDescriptions": { "hard_bounce_rate": "Hard bounce rate", "temporary_fail_rate": "Temporary fail rate", "delivered_rate": "Delivery rate", "complained_rate": "Complaint rate" } }, "github.com-mailgun-thresholds-api-MetricComparator": { "type": "string", "enum": [ "=", "!=", "<", "<=", ">", ">=" ], "description": "Metric Comparator", "x-enumDescriptions": { "=": "Equal", "!=": "Not equal", "<": "Less than", "<=": "Less than or equal", ">": "Greater than", ">=": "Greater than or equal" } }, "github.com-mailgun-thresholds-api-SendAlertItem": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the alert." }, "parent_account_id": { "type": "string", "description": "The parent account ID." }, "subaccount_id": { "type": "string", "description": "The subaccount ID this alert belongs to." }, "account_group": { "type": "string", "description": "The group this account belongs to." }, "name": { "type": "string", "description": "A user-friendly name for the alert." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the alert was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the alert was last updated." }, "last_checked": { "type": "string", "format": "date-time", "description": "Timestamp of the alert was last checked." }, "description": { "type": "string", "description": "A description of what the alert does." }, "alert_channels": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-AlertChannel" }, "description": "A list of alert channels to notify." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Filter" }, "description": "A list of filters to apply to the alert." }, "metric": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Metric" } ], "description": "The metric being monitored." }, "comparator": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-MetricComparator" } ], "description": "The comparison operator." }, "limit": { "type": "string", "description": "The threshold limit for the alert." }, "dimension": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Dimension" } ], "description": "The dimension to apply to the metric." }, "period": { "type": "string", "description": "The time period for the metric aggregation in the format of '1h' '1d'." } }, "required": [ "name", "created_at", "metric", "comparator", "limit", "dimension" ] }, "github.com-mailgun-thresholds-api-SendAlertRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "A user-friendly name for the alert." }, "metric": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Metric" } ], "description": "The metric being monitored." }, "comparator": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-MetricComparator" } ], "description": "The comparison operator." }, "limit": { "type": "string", "description": "The threshold limit for the alert." }, "dimension": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Dimension" } ], "description": "The dimension to apply to the metric." }, "alert_channels": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-AlertChannel" }, "description": "A list of alert channels to notify." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Filter" }, "description": "A list of filters to apply to the alert." }, "period": { "type": "string", "description": "The time period for the metric aggregation in the format of '1h' '1d'." }, "description": { "type": "string", "description": "A description of what the alert does." } }, "required": [ "name", "metric", "comparator", "limit", "dimension" ] }, "github.com-mailgun-thresholds-api-SendAlertListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-SendAlertItem" }, "description": "List of send alerts." }, "total": { "type": "integer", "format": "int64", "description": "Total number of send alerts." } }, "required": [ "items", "total" ] }, "github.com-mailgun-thresholds-api-LimitMetric": { "type": "string", "enum": [ "email_preview_success_count", "seed_test_count" ], "description": "Limit Metric", "x-enumDescriptions": { "email_preview_success_count": "The number of successful email previews", "seed_test_count": "The number of inbox placement tests" } }, "github.com-mailgun-thresholds-api-ThresholdLimitItem": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the limit." }, "parent_account_id": { "type": "string", "description": "The parent account ID." }, "subaccount_id": { "type": "string", "description": "The subaccount ID this limit belongs to." }, "account_group": { "type": "string", "description": "The group this account belongs to." }, "name": { "type": "string", "description": "A user-friendly name for the limit." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the limit was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the limit was last updated." }, "last_checked": { "type": "string", "format": "date-time", "description": "Timestamp of when the limit was last checked." }, "description": { "type": "string", "description": "A description of what the limit does." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Filter" }, "description": "A list of filters to apply to the limit." }, "metric": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-LimitMetric" } ], "description": "The metric being monitored." }, "comparator": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-MetricComparator" } ], "description": "The comparison operator." }, "limit": { "type": "string", "description": "The value of the limit." }, "dimension": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Dimension" } ], "description": "The dimension to apply to the metric." }, "period": { "type": "string", "description": "The time period for the metric aggregation in the format of '1h' '1d'." } }, "required": [ "name", "created_at", "metric", "comparator", "limit", "dimension" ] }, "github.com-mailgun-thresholds-api-LimitRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "A user-friendly name for the limit." }, "metric": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-LimitMetric" } ], "description": "The metric being monitored." }, "comparator": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-MetricComparator" } ], "description": "The comparison operator." }, "limit": { "type": "string", "description": "The threshold limit." }, "dimension": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Dimension" } ], "description": "The dimension to apply to the metric." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Filter" }, "description": "A list of filters to apply to the limit." }, "period": { "type": "string", "description": "The time period for the metric aggregation in the format of '1h' '1d'." }, "description": { "type": "string", "description": "A description of what the limit does." } }, "required": [ "name", "metric", "comparator", "limit", "dimension" ] }, "github.com-mailgun-thresholds-api-ThresholdLimitListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-ThresholdLimitItem" }, "description": "List of threshold limits." }, "total": { "type": "integer", "format": "int64", "description": "Total number of threshold limits." } }, "required": [ "items", "total" ] }, "github.com-mailgun-thresholds-api-HitListItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "triggered": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time" }, "latest_value": { "type": "string" }, "metric": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Metric" }, "comparator": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-MetricComparator" }, "limit": { "type": "string" }, "parent_account_id": { "type": "string" }, "subaccount_id": { "type": "string" }, "dimension": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-Dimension" }, "dimension_value": { "type": "string" } }, "required": [ "id", "name", "created_at", "updated_at", "triggered", "expires_at", "latest_value", "metric", "comparator", "limit" ] }, "github.com-mailgun-thresholds-api-HitListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-thresholds-api-HitListItem" } }, "total": { "type": "integer", "format": "int64" } }, "required": [ "items", "total" ] }, "github.com-mailgun-alerts-internal-api-ListAlertsEventsResp": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "events" ] }, "github.com-mailgun-alerts-channels-Channel": { "type": "string", "enum": [ "email", "webhook", "slack" ], "description": "Alert channel type.", "x-enumDescriptions": { "email": "email", "webhook": "webhook", "slack": "Slack" } }, "github.com-mailgun-alerts-internal-settings-DisabledChannel": { "type": "object", "properties": { "disabled_at": { "type": "string", "format": "date-time", "description": "When the channel was disabled." }, "reason": { "type": "string", "description": "Why the channel was disabled." } }, "required": [ "disabled_at", "reason" ] }, "github.com-mailgun-alerts-internal-settings-ChannelSettings": { "type": "object", "properties": { "url": { "type": "string", "description": "For webhook channel." }, "emails": { "type": "array", "items": { "type": "string" }, "description": "For email channel" }, "channel_ids": { "type": "array", "items": { "type": "string" }, "description": "For slack channel" }, "disabled_channel_ids": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-settings-DisabledChannel" }, "description": "List of disabled Slack channels." } } }, "github.com-mailgun-alerts-internal-settings-EventSettings": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the alert settings record." }, "event_type": { "type": "string", "description": "The event type that is alerted on. Check GET /v1/alerts/events for possible values." }, "channel": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-alerts-channels-Channel" } ], "description": "The delivery channel for the alert." }, "settings": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-settings-ChannelSettings" } ], "description": "This object contains channel-specific settings." }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When present, the timestamp indicating when a webhook endpoint was disabled." } }, "required": [ "event_type", "channel", "settings" ] }, "github.com-mailgun-alerts-internal-api-mutateEventSettingReq": { "type": "object", "properties": { "event_type": { "type": "string", "description": "The type of event for which you would like to receive alerts." }, "channel": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-alerts-channels-Channel" } ], "description": "The delivery method for the alert." }, "settings": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-settings-ChannelSettings" } ], "description": "The details pertaining to the specified channel. Please note that the contents of this object differ per channel type." } }, "required": [ "event_type", "channel", "settings" ] }, "github.com-mailgun-alerts-internal-settings-Webhooks": { "type": "object", "properties": { "signing_key": { "type": "string" } }, "required": [ "signing_key" ] }, "github.com-mailgun-alerts-internal-settings-Slack": { "type": "object", "properties": { "token": { "type": "string" }, "team_id": { "type": [ "string", "null" ] }, "team_name": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] } }, "required": [ "token", "team_id", "team_name", "scope" ] }, "github.com-mailgun-alerts-internal-api-SettingsResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-settings-EventSettings" } }, "webhooks": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-settings-Webhooks" }, "slack": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-settings-Slack" } }, "required": [ "events", "webhooks", "slack" ] }, "github.com-mailgun-alerts-internal-api-ResetWebhooksSigningKeyResp": { "type": "object", "properties": { "signing_key": { "type": "string" } }, "required": [ "signing_key" ] }, "github.com-mailgun-alerts-internal-api-TestWebhookRequest": { "type": "object", "properties": { "event_type": { "type": "string" }, "url": { "type": "string" } }, "required": [ "event_type", "url" ] }, "github.com-mailgun-alerts-internal-api-TestEmailRequest": { "type": "object", "properties": { "event_type": { "type": "string" }, "emails": { "type": "array", "items": { "type": "string" } } }, "required": [ "event_type", "emails" ] }, "github.com-mailgun-alerts-internal-api-TestSlackRequest": { "type": "object", "properties": { "event_type": { "type": "string" }, "channel_ids": { "type": "array", "items": { "type": "string" }, "description": "If omitted would be taken from the event settings" } }, "required": [ "event_type" ] }, "github.com-mailgun-alerts-internal-api-SlackChannel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_archived": { "type": "boolean" } }, "required": [ "id", "name", "is_archived" ] }, "github.com-mailgun-alerts-internal-api-ListSlackChannelsResp": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-alerts-internal-api-SlackChannel" } }, "paging": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse" } }, "required": [ "items", "paging" ] }, "POST-v3-domainID-unsubscribes-import-multipart-form-data-RequestBody": { "type": "object", "properties": { "file": { "type": "string", "description": "CSV file" } }, "required": [ "file" ] }, "POST-v3-domainID-bounces-import-multipart-form-data-RequestBody": { "type": "object", "properties": { "file": { "type": "string", "description": "CSV file" } }, "required": [ "file" ] }, "POST-v3-domainID-complaints-import-multipart-form-data-RequestBody": { "type": "object", "properties": { "file": { "type": "string", "description": "CSV file" } }, "required": [ "file" ] }, "POST-v3-domainID-whitelists-import-multipart-form-data-RequestBody": { "type": "object", "properties": { "file": { "type": "string", "description": "CSV file" } }, "required": [ "file" ] }, "github.com-mailgun-mime-RFC822Time": { "type": "object" }, "github.com-mailgun-blackbook-model-Bounce": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address for the original recipient" }, "code": { "type": "string", "description": "SMTP error code" }, "error": { "type": "string", "description": "SMTP error message" }, "created_at": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-mime-RFC822Time" } ], "description": "Timestamp for when the Bounce event was received in RFC822 format" } }, "required": [ "address", "code", "error", "created_at" ] }, "github.com-mailgun-blackbook-api-getBouncesPaginationResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Bounce" } }, "paging": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse" } }, "required": [ "items", "paging" ] }, "github.com-mailgun-blackbook-api-BouncesList": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Bounce" } }, "POST-v3-domainID-bounces-application-form-data-RequestBody": { "type": "object", "properties": { "address": { "type": "string", "description": "Valid email address" }, "code": { "type": "string", "description": "Error code (optional, default: 550)" }, "error": { "type": "string", "description": "Error description (optional, default: empty string)" }, "created_at": { "type": "string", "description": "Timestamp of a bounce event in RFC2822 format (optional, default: current time)" } }, "required": [ "address" ] }, "github.com-mailgun-blackbook-api-suppressionResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "address": { "type": "string", "description": "Email address" } }, "required": [ "message", "address" ] }, "github.com-mailgun-blackbook-model-Unsubscribe": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address for the original recipient" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Any tags present on the message the user clicked Unsubscribe on" }, "created_at": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-mime-RFC822Time" } ], "description": "Timestamp for when the unsubscribe request was received in RFC822 format" } }, "required": [ "address", "tags", "created_at" ] }, "github.com-mailgun-blackbook-api-getUnsubscribesPaginationResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Unsubscribe" } }, "paging": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse" } }, "required": [ "items", "paging" ] }, "github.com-mailgun-blackbook-api-UnsubscribesList": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Unsubscribe" } }, "POST-v3-domainID-unsubscribes-application-form-data-RequestBody": { "type": "object", "properties": { "address": { "type": "string", "description": "Valid email address" }, "tags": { "type": "string", "description": "Tag to unsubscribe from, use * to unsubscribe an address from all domain’s correspondence (optional, default: *)" }, "created_at": { "type": "string", "description": "Timestamp of an unsubscribe event in RFC2822 format (optional, default: current time)" } }, "required": [ "address" ] }, "github.com-mailgun-blackbook-model-Complaint": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address for the original recipient" }, "created_at": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-mime-RFC822Time" } ], "description": "Timestamp for when the Complaint event was received in RFC822 format" } }, "required": [ "address", "created_at" ] }, "github.com-mailgun-blackbook-api-getComplaintsPaginationResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Complaint" } }, "paging": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse" } }, "required": [ "items", "paging" ] }, "github.com-mailgun-blackbook-api-ComplaintsList": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Complaint" } }, "POST-v3-domainID-complaints-application-form-data-RequestBody": { "type": "object", "properties": { "address": { "type": "string", "description": "Valid email address" }, "created_at": { "type": "string", "description": "Timestamp of a complaint event in RFC2822 format (optional, default: current time)" } }, "required": [ "address" ] }, "github.com-mailgun-blackbook-model-Whitelist": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of allowlist" }, "value": { "type": "string", "description": "Domain or address allowlisted" }, "createdAt": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-mime-RFC822Time" } ], "description": "Timestamp for when the entry was created in RFC822 format" }, "reason": { "type": "string", "description": "User-provided reason for allowlisting" } }, "required": [ "type", "value", "createdAt", "reason" ] }, "github.com-mailgun-blackbook-api-getWhitelistPaginationResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-blackbook-model-Whitelist" } }, "paging": { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse" } }, "required": [ "items", "paging" ] }, "github.com-mailgun-blackbook-api-insertWhitelistRecordResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "type": { "type": "string", "description": "Type of allowlist" }, "value": { "type": "string", "description": "Domain or address" } }, "required": [ "message", "type", "value" ] }, "POST-v3-domainID-whitelists-application-form-data-RequestBody": { "type": "object", "properties": { "address": { "type": "string", "description": "Valid email address if you would like to allowlist email address (prior over 'domain' parameter)" }, "domain": { "type": "string", "description": "Valid domain name if you would like allowlist entire domain name" } }, "required": [ "address" ] }, "github.com-mailgun-blackbook-api-deleteWhitelistRecordResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "value": { "type": "string", "description": "Domain or address" } }, "required": [ "message", "value" ] }, "RouteResponse": { "type": "object", "title": "RouteResponse", "properties": { "id": { "type": "string", "description": "Unique identifier of the route" }, "priority": { "type": "integer", "description": "Smaller number indicates higher priority. Higher priority routes are handled first." }, "description": { "type": "string", "description": "An arbitrary string." }, "expression": { "type": "string", "description": "The filtering rule." }, "actions": { "type": "array", "items": { "type": "string" }, "description": "These actions are executed when the expression evaluates to True." }, "created_at": { "type": "string", "description": "Timestamp indicating when the route was created in RFC1123 format" } }, "examples": [ { "id": "4f3bad2335335426750048c6", "priority": 0, "description": "Sample route", "expression": "match_recipient(\".*@samples.mailgun.org\")", "actions": [ "forward(\"http://myhost.com/messages/\")", "stop()" ], "created_at": "Wed, 15 Feb 2012 13:03:31 GMT" } ] }, "ListMemberRequest": { "type": "object", "title": "Mailing list member", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "subscribed": { "type": "boolean" }, "vars": { "type": "object" } }, "examples": [ { "address": "dev@mailgun.net", "name": "Super Developer", "subscribed": true, "vars": { "department": "Support", "rank": "Monarch", "memo": "Give them a raise" } } ] }, "MailingListResponse": { "type": "object", "title": "The mailing list response", "properties": { "address": { "type": "string", "description": "The email address of the mailing list" }, "name": { "type": "string", "description": "The name of the mailing list" }, "description": { "type": "string", "description": "A description of the mailing list" }, "access_level": { "type": "string", "description": "List access level, one of: readonly, members, everyone" }, "reply_preference": { "type": "string", "description": "Set where replies should go: list or sender" }, "created_at": { "type": "string", "description": "Timestamp indicating the mailing list creation time in RFC 5322 format" }, "members_count": { "type": "integer", "description": "The number of members on the mailing list" } }, "examples": [ { "address": "developers@mailgun.net", "name": "Developers", "description": "Describe the mailing list", "access_level": "readonly", "reply_preference": "list", "created_at": "Tue, 09 Aug 2011 20:50:27 -0000", "members_count": 2 } ] }, "ListMemberResponse": { "type": "object", "title": "ListMemberResponse", "properties": { "address": { "type": "string", "description": "The email address of the mailing list" }, "name": { "type": "string", "description": "The name of the mailing list" }, "vars": { "type": "object", "description": "A JSON-encoded dictionary string with arbitrary parameters, e.g. {\"gender\":\"female\",\"age\":27}" }, "subscribed": { "type": "boolean", "description": "Whether the member is subscribed or not" } }, "examples": [ { "address": "alice@example.com", "name": "Alice", "vars": { "gender": "female", "age": 27 }, "subscribed": true } ] }, "PaginateMailingListResponse": { "type": "object", "title": "PaginateMailingListResponse", "properties": { "paging": { "type": "object", "properties": { "first": { "type": "string", "description": "URL to the first page" }, "next": { "type": "string", "description": "URL to the next page" }, "previous": { "type": "string", "description": "URL to the previous page" }, "last": { "type": "string", "description": "URL to the last page" } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MailingListResponse" } } }, "examples": [ { "paging": { "first": "https://url_to_next_page", "last": "https://url_to_last_page", "next": "https://url_to_next_page", "previous": "https://url_to_previous_page" }, "items": [ { "access_level": "everyone", "address": "dev@samples.mailgun.org", "created_at": "Tue, 06 Mar 2012 05:44:45 GMT", "description": "Mailgun developers list", "members_count": 1, "name": "" }, { "access_level": "readonly", "address": "bar@example.com", "created_at": "Wed, 06 Mar 2013 11:39:51 GMT", "description": "", "members_count": 2, "name": "" } ] } ] }, "PaginateListMemberResponse": { "type": "object", "title": "PaginateListMemberResponse", "properties": { "paging": { "type": "object", "properties": { "first": { "type": "string" }, "next": { "type": "string" }, "last": { "type": "string" }, "previous": { "type": "string" } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ListMemberResponse" } } }, "examples": [ { "items": [ { "vars": { "age": 26 }, "name": "Foo Bar", "subscribed": false, "address": "bar@example.com" } ], "paging": { "first": "https://url_to_first_page", "last": "https://url_to_last_page", "next": "http://url_to_next_page", "previous": "http://url_to_previous_page" } } ] }, "github.com-mailgun-temple-model-Version": { "type": "object", "properties": { "tag": { "type": "string", "description": "Tag of the version. Must be unique to the template" }, "template": { "type": "string", "description": "Template content" }, "engine": { "type": "string", "description": "Rendering engine" }, "mjml": { "type": "string", "description": "Template source" }, "createdAt": { "type": "string", "description": "Creation date in RFC822 format", "readOnly": true }, "comment": { "type": "string", "description": "Comment related to the version" }, "active": { "type": "boolean", "description": "If this flag is true" }, "id": { "type": "string", "description": "Template ID", "readOnly": true }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "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`" } }, "required": [ "tag", "engine", "mjml", "createdAt", "comment", "active", "id" ] }, "github.com-mailgun-temple-model-Template": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the template" }, "description": { "type": "string", "description": "Description of the template" }, "createdAt": { "type": "string", "description": "Creation date in RFC822 format", "readOnly": true }, "createdBy": { "type": "string", "description": "Indicate who created the template" }, "id": { "type": "string", "description": "Template ID", "readOnly": true }, "domain": { "type": "string", "description": "Domain of the template" }, "version": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-temple-model-Version" }, { "type": "null" } ], "description": "Active version information", "readOnly": true }, "versions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/github.com-mailgun-temple-model-Version" }, "description": "List of template's versions", "readOnly": true } }, "required": [ "name" ] }, "github.com-mailgun-temple-httpapi-createTemplateOrVersionResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "template": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-temple-model-Template" }, { "type": "null" } ], "description": "Template details" } }, "required": [ "message", "template" ] }, "POST-v3-domain_name-templates-multipart-form-data-RequestBody": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the template being stored. Supports utf-8 characters and name will be down cased." }, "description": { "type": "string", "description": "Description of the template being stored" }, "createdBy": { "type": "string", "description": "Optional metadata field api user can indicate who created the template." }, "template": { "type": "string", "description": "Content of the template." }, "tag": { "type": "string", "description": "Initial tag of the created version. If the template parameter is provided and the tag is missing, the default value `initial` is used." }, "comment": { "type": "string", "description": "Version comment. This is valid only if a new version is being created. (template parameter is provided.)" }, "headers": { "type": "string", "description": "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. \n\nHeaders set at the message level will override headers set on the template. e.g. Setting the From header at the time of sending will override the From header saved on the template. Additionally, headers generated by templates are not reflected on the accepted event as they are not prepended to the message until the message is prepped for delivery. if a From header is not provided either in the message or template, we will default to `postmaster@your-sending-domain.tld`" } }, "required": [ "name" ] }, "POST-v3-domain_name-templates-template_name-versions-multipart-form-data-RequestBody": { "type": "object", "properties": { "template": { "type": "string", "description": "Content of the template." }, "tag": { "type": "string", "description": "Tag of the version that is being created. Must be unique to the template." }, "comment": { "type": "string", "description": "Comment related to the version that is being created." }, "active": { "type": "string", "description": "If this flag is set to yes, this version becomes active" }, "headers": { "type": "string", "description": "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. \n\nHeaders set at the message level will override headers set on the template. e.g. Setting the From header at the time of sending will override the From header saved on the template. Additionally, headers generated by templates are not reflected on the accepted event as they are not prepended to the message until the message is prepped for delivery. if a From header is not provided either in the message or template, we will default to `postmaster@your-sending-domain.tld`" } }, "required": [ "template", "tag" ] }, "github.com-mailgun-temple-httpapi-getTemplateOrVersionResponse": { "type": "object", "properties": { "template": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-temple-model-Template" }, { "type": "null" } ], "description": "Template details" } }, "required": [ "template" ] }, "github.com-mailgun-temple-httpapi-getVersionsPageResponse": { "type": "object", "properties": { "template": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-temple-model-Template" }, { "type": "null" } ], "description": "Template details" }, "paging": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse" } ], "description": "Pagination details" } }, "required": [ "template", "paging" ] }, "github.com-mailgun-temple-httpapi-getPageResponse": { "type": "object", "properties": { "items": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/github.com-mailgun-temple-model-Template" }, "description": "List of items" }, "paging": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse" } ], "description": "Pagination details" } }, "required": [ "items", "paging" ] }, "github.com-mailgun-temple-httpapi-TemplateCopyRequest": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Target account ID to copy the template to" }, "name": { "type": "string", "description": "Name of the new template in the target account" }, "domain": { "type": "string", "description": "Domain of the new template in the target account" } }, "required": [ "account_id", "name" ] }, "github.com-mailgun-temple-httpapi-TemplateCopyResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "failed_copies": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-TemplateCopyRequest" }, "description": "Failed copy requests" }, "error": { "type": "string", "description": "A error that occurred during copying" } }, "required": [ "message", "failed_copies" ] }, "github.com-mailgun-scaffold-httpapi-ResponseWithStatus": { "type": "object", "properties": { "Response": { "type": "object" }, "Status": { "type": "integer", "format": "int32" } }, "required": [ "Response", "Status" ] }, "github.com-mailgun-temple-httpapi-TemplateCopyParams": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-TemplateCopyRequest" }, "description": "List of copy requests" }, "source_versions": { "type": "array", "items": { "type": "string" }, "description": "Versions to copy or all versions if empty." } }, "required": [ "requests" ] }, "github.com-mailgun-temple-httpapi-versionCopyResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "version": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-temple-model-Version" }, { "type": "null" } ], "description": "Created version details" }, "template": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-temple-model-Version" }, { "type": "null" } ], "description": "Deprecated: Use 'version' field", "deprecated": true } }, "required": [ "message", "version", "template" ] }, "github.com-mailgun-temple-httpapi-versionUpdate": { "type": "object", "properties": { "tag": { "type": "string", "description": "Tag of the version. Must be unique to the template" } }, "required": [ "tag" ] }, "github.com-mailgun-temple-httpapi-templateUpdate": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the template" }, "version": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-versionUpdate" }, { "type": "null" } ], "description": "Template version details" } }, "required": [ "name" ] }, "github.com-mailgun-temple-httpapi-updateOrDeleteTemplateOrVersionResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "template": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-temple-httpapi-templateUpdate" } ], "description": "Template change details" } }, "required": [ "message", "template" ] }, "PUT-v3-domain_name-templates-template_name-versions-version_name-multipart-form-data-RequestBody": { "type": "object", "properties": { "template": { "type": "string", "description": "Content of the template." }, "comment": { "type": "string", "description": "Comment related to the version that is being created." }, "active": { "type": "string", "description": "If this flag is set to yes, this version becomes active" }, "headers": { "type": "string", "description": "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." } } }, "PUT-v3-domain_name-templates-template_name-multipart-form-data-RequestBody": { "type": "object", "properties": { "description": { "type": "string", "description": "Update description of the template being updated." } }, "required": [ "description" ] }, "POST-v4-templates-multipart-form-data-RequestBody": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the template being stored. Supports utf-8 characters and name will be down cased." }, "description": { "type": "string", "description": "Description of the template being stored" }, "createdBy": { "type": "string", "description": "Optional metadata field api user can indicate who created the template." }, "template": { "type": "string", "description": "Content of the template." }, "tag": { "type": "string", "description": "Initial tag of the created version. If the template parameter is provided and the tag is missing, the default value `initial` is used." }, "comment": { "type": "string", "description": "Version comment. This is valid only if a new version is being created. (template parameter is provided.)" }, "headers": { "type": "string", "description": "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." } }, "required": [ "name" ] }, "POST-v4-templates-template_name-versions-multipart-form-data-RequestBody": { "type": "object", "properties": { "template": { "type": "string", "description": "Content of the template." }, "tag": { "type": "string", "description": "Tag of the version that is being created. Must be unique to the template." }, "comment": { "type": "string", "description": "Comment related to the version that is being created." }, "active": { "type": "string", "description": "If this flag is set to yes, this version becomes active" }, "headers": { "type": "string", "description": "Key value JSON object of headers to be stored with the template." } }, "required": [ "template", "tag" ] }, "PUT-v4-templates-template_name-versions-version_name-multipart-form-data-RequestBody": { "type": "object", "properties": { "template": { "type": "string", "description": "Content of the template." }, "comment": { "type": "string", "description": "Comment related to the version." }, "active": { "type": "string", "description": "If this flag is set to yes, this version becomes active" }, "headers": { "type": "string", "description": "Key value JSON object of headers to be stored with the template." } } }, "PUT-v4-templates-template_name-multipart-form-data-RequestBody": { "type": "object", "properties": { "description": { "type": "string", "description": "Update description of the template being updated." } }, "required": [ "description" ] }, "github.com-mailgun-accounts-api-CustomMessageLimitResponse": { "type": "object", "properties": { "limit": { "type": "number", "description": "The custom limit set for the account" }, "current": { "type": "number", "description": "The number of messages already sent" }, "period": { "type": "string", "description": "The timeframe for which the limit applies - m for months, d for days, h for hours" } } }, "github.com-mailgun-accounts-api-SubaccountStatus": { "type": "string", "enum": [ "disabled", "open", "closed" ], "description": "The status of the subaccount", "x-enumDescriptions": { "disabled": "Account is disabled", "open": "Account is open", "closed": "Account is closed" } }, "github.com-mailgun-accounts-api-Subaccount": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the subaccount" }, "name": { "type": "string", "description": "The name of the subaccount" }, "created_at": { "type": "string", "description": "The date when the account was created serialized as RFC 1123 (HTTP-date) string in GMT (UTC)", "example": "Wed, 28 May 2025 20:03:05 GMT", "pattern": "^[A-Z][a-z]{2}, [0-9]{2} [A-Z][a-z]{2} [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$" }, "updated_at": { "type": "string", "description": "The date when the account was last updated serialized as RFC 1123 (HTTP-date) string in GMT (UTC)", "example": "Wed, 28 May 2025 20:03:05 GMT", "pattern": "^[A-Z][a-z]{2}, [0-9]{2} [A-Z][a-z]{2} [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$" }, "status": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-SubaccountStatus" }, "features": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-FeaturesResponse" } } }, "github.com-mailgun-accounts-api-SubaccountResponse": { "type": "object", "properties": { "subaccount": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-Subaccount" } } }, "github.com-mailgun-accounts-api-SubaccountListResponse": { "type": "object", "properties": { "subaccounts": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-accounts-api-Subaccount" } }, "total": { "type": "integer", "description": "The total number of subaccounts" } } }, "github.com-mailgun-accounts-api-HTTPSigningKey": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "http_signing_key": { "type": "string", "description": "Decoded webhook signing key" } } }, "github.com-mailgun-accounts-api-RecipientResponse": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of sandbox domain recipient" }, "activated": { "type": "boolean", "description": "Activated/verified status of the recipient" } } }, "github.com-mailgun-accounts-api-FeaturesResponse": { "type": "object", "additionalProperties": true }, "github.com-mailgun-accounts-api-FeatureOverrideEnabledParam": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "The enabled status of the feature" } }, "required": [ "enabled" ] }, "github.com-mailgun-accounts-api-GenericSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates success of request" } } }, "github.com-mailgun-accounts-api-GenericMessage": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" } } }, "github.com-mailgun-cerberus-keys-Kind": { "type": "string", "enum": [ "domain", "user", "web" ], "description": "Kind", "x-enumDescriptions": { "domain": "Domain-specific API key for keys with 'sending' role", "user": "API key tied to a user role for RBAC limitations", "web": "Web session API key generated for user login sessions" } }, "github.com-mailgun-cerberus-keys-Role": { "type": "string", "enum": [ "admin", "basic", "sending", "developer" ], "description": "Role", "x-enumDescriptions": { "admin": "Provides admin-level permissions on an API key", "basic": "Provides basic aka analyst-level permissions on an API key", "sending": "Provides domain-scoped permissions on an API key for use only with 'domain' kind key", "developer": "Provides developer-level permissions on an API key" } }, "github.com-mailgun-cerberus-keys-KeyInfoResp": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID for the key" }, "description": { "type": "string", "description": "The description provided for the key upon its creation" }, "kind": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-cerberus-keys-Kind" } ], "description": "The type of the key which determines how it can be used" }, "role": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-cerberus-keys-Role" } ], "description": "The role of the key which determines its scope in CRUD operations that have role-based access control" }, "created_at": { "type": "string", "description": "When the key was created in ISO 8601 date-time format without timezone offset (UTC time)", "example": "2026-01-23T10:16:00", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "updated_at": { "type": "string", "description": "When the key was last updated in ISO 8601 date-time format without timezone offset (UTC time)", "example": "2026-01-23T10:16:00", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "expires_at": { "type": "string", "description": "When the key will expire in ISO 8601 date-time format without timezone offset (UTC time)", "example": "2026-01-23T10:16:00", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "disabled_reason": { "type": "string", "description": "The reason for the key's disablement if applicable" }, "is_disabled": { "type": "boolean", "description": "Whether or not the key is disabled from use" }, "domain_name": { "oneOf": [ { "type": "string", "description": "The sending domain associated with the key required for 'domain' kind keys" }, { "type": "null", "description": "No sending domain associated with the key" } ] }, "requestor": { "oneOf": [ { "type": "string", "description": "An email address associated with the key" }, { "type": "null", "description": "No email address associated with the key" } ] }, "user_name": { "oneOf": [ { "type": "string", "description": "The API key user's name" }, { "type": "null", "description": "No API key user name associated with the key" } ] } }, "required": [ "id", "description", "kind", "role", "created_at", "updated_at", "is_disabled", "domain_name", "requestor", "user_name" ] }, "github.com-mailgun-cerberus-keys-KeysResp": { "type": "object", "properties": { "total_count": { "type": "integer", "format": "int32", "description": "The number of keys returned in 'items'" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-keys-KeyInfoResp" } } }, "required": [ "total_count", "items" ] }, "github.com-mailgun-cerberus-keys-KeyInfoSecretResp": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID for the key" }, "description": { "type": "string", "description": "The description provided for the key upon its creation" }, "kind": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-cerberus-keys-Kind" } ], "description": "The type of the key which determines how it can be used" }, "role": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-cerberus-keys-Role" } ], "description": "The role of the key which determines its scope in CRUD operations that have role-based access control" }, "created_at": { "type": "string", "description": "When the key was created in ISO 8601 date-time format without timezone offset (UTC time)", "example": "2026-01-23T10:16:00", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "updated_at": { "type": "string", "description": "When the key was last updated in ISO 8601 date-time format without timezone offset (UTC time)", "example": "2026-01-23T10:16:00", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "expires_at": { "type": "string", "description": "When the key will expire in ISO 8601 date-time format without timezone offset (UTC time)", "example": "2026-01-23T10:16:00", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "disabled_reason": { "type": "string", "description": "The reason for the key's disablement if applicable" }, "is_disabled": { "type": "boolean", "description": "Whether or not the key is disabled from use" }, "domain_name": { "oneOf": [ { "type": "string", "description": "The sending domain associated with the key required for 'domain' kind keys" }, { "type": "null", "description": "No sending domain associated with the key" } ] }, "requestor": { "oneOf": [ { "type": "string", "description": "An email address associated with the key" }, { "type": "null", "description": "No email address associated with the key" } ] }, "user_name": { "oneOf": [ { "type": "string", "description": "The API key user's name" }, { "type": "null", "description": "No API key user name associated with the key" } ] }, "secret": { "type": "string", "description": "The full API key secret in plain text returned only once upon key creation", "format": "password" } }, "required": [ "id", "description", "kind", "role", "created_at", "updated_at", "is_disabled", "domain_name", "requestor", "user_name", "secret" ] }, "github.com-mailgun-cerberus-keys-CreateKeyResp": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "key": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-keys-KeyInfoSecretResp" } }, "required": [ "message", "key" ] }, "POST-v1-keys-multipart-form-data-RequestBody": { "type": "object", "properties": { "domain_name": { "type": "string", "description": "Web domain to associate with the key, for keys of 'domain' kind" }, "kind": { "type": "string", "enum": [ "domain", "user", "web" ], "description": "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.", "x-enumDescriptions": { "domain": "Create API key of type 'domain'", "user": "Create API key of type 'user'", "web": "Create API key of type 'web'" } }, "description": { "type": "string", "description": "Key description" }, "expiration": { "type": "integer", "description": "Key lifetime in seconds, must be greater than 0 if set" }, "role": { "type": "string", "enum": [ "admin", "basic", "sending", "developer" ], "description": "Key role ('admin', 'basic' [use in place of analyst], 'sending' [use with keys of domain kind], or 'developer')", "x-enumDescriptions": { "admin": "Provides admin-level permissions on an API key", "basic": "Provides basic aka analyst-level permissions on an API key", "sending": "Provides domain-scoped permissions on an API key for use only with 'domain' kind key", "developer": "Provides developer-level permissions on an API key" } }, "user_id": { "type": "string", "description": "API Key user's string user ID; should be provided for all keys of 'web' kind" }, "user_name": { "type": "string", "description": "API Key user's name" }, "email": { "type": "string", "description": "API Key user's email address; should be provided for all keys of 'web' kind" } }, "required": [ "role" ] }, "github.com-mailgun-cerberus-keys-PublicKeyResp": { "type": "object", "properties": { "key": { "type": "string", "description": "The account public key" }, "message": { "type": "string", "description": "Response message" } }, "required": [ "key", "message" ] }, "github.com-mailgun-cerberus-credentials-CredentialMetadata": { "type": "object", "properties": { "mailbox": { "type": "string", "description": "The email address-style username associated with this credential" }, "login": { "type": "string", "description": "The email address-style username associated with this credential" }, "created_at": { "type": "string", "description": "When the credential was created in RFC 2822 format with numeric timezone offset (UTC time)", "example": "Fri, 23 Jan 2026 10:16:00 +0000", "pattern": "^[A-Z][a-z]{2}, [0-9]{2} [A-Z][a-z]{2} [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} [+-][0-9]{4}$" }, "size_bytes": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "mailbox", "login", "created_at", "size_bytes" ] }, "github.com-mailgun-cerberus-credentials-ListCredsResp": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-credentials-CredentialMetadata" } }, "total_count": { "type": "integer", "format": "int32", "description": "The number of credentials described in 'items'" } }, "required": [ "items", "total_count" ] }, "github.com-mailgun-cerberus-credentials-CreateCredsResp": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "note": { "type": "string", "description": "Note to store password (when generated by Mailgun)" }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Credential username/password values (when generated by Mailgun)" } }, "required": [ "message" ] }, "POST-v3-domains-domain_name-credentials-multipart-form-data-RequestBody": { "type": "object", "properties": { "login": { "type": "string", "description": "Email address of SMTP credential user; accepts multiple values" }, "mailbox": { "type": "string", "description": "Email address of SMTP credential user, may be used in place of 'login'; accepts multiple values" }, "system": { "type": "boolean", "description": "Identify if these are system account credentials, defaults to false" }, "password": { "type": "string", "description": "Supply desired password(s) for the new credentials if preferred over generated ones; accepts multiple values" } }, "required": [ "login" ] }, "PUT-v3-domains-domain_name-credentials-spec-multipart-form-data-RequestBody": { "type": "object", "properties": { "password": { "type": "string", "description": "Supply desired password for the credentials to update if preferred over a generated one" } } }, "github.com-mailgun-cerberus-credentials-DeleteDomainCredsResp": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "count": { "type": "integer", "format": "int32", "description": "The number of credentials deleted" } }, "required": [ "message", "count" ] }, "github.com-mailgun-cerberus-credentials-DeleteCredsResp": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" }, "spec": { "type": "string", "description": "The mailbox username associated with the deleted credentials" } }, "required": [ "message", "spec" ] }, "github.com-mailgun-cerberus-whitelist-WhitelistRespEntry": { "type": "object", "properties": { "ip_address": { "type": "string", "description": "Allowlisted IP address" }, "description": { "type": "string", "description": "Description of the allowlisted IP address" } }, "required": [ "ip_address", "description" ] }, "github.com-mailgun-cerberus-whitelist-V2WhitelistResp": { "type": "object", "properties": { "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-cerberus-whitelist-WhitelistRespEntry" }, "description": "Allowlisted IP address entries on the account" } }, "required": [ "addresses" ] }, "POST-v2-ip_whitelist-multipart-form-data-RequestBody": { "type": "object", "properties": { "address": { "type": "string", "description": "Address to be added to the allowlist" }, "description": { "type": "string", "description": "Description of the address to be added to the allowlist, defaults to empty string" } }, "required": [ "address" ] }, "PUT-v2-ip_whitelist-multipart-form-data-RequestBody": { "type": "object", "properties": { "address": { "type": "string", "description": "Address to be updated in the allowlist" }, "description": { "type": "string", "description": "Description of the address to be updated in the allowlist, defaults to empty string" } }, "required": [ "address" ] }, "github.com-mailgun-bounce-classification-entities-Subaccount": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "github.com-mailgun-bounce-classification-entities-Domain": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "github.com-mailgun-bounce-classification-entities-BouncedStat": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32" } }, "required": [ "total" ] }, "github.com-mailgun-bounce-classification-entities-Stat": { "type": "object", "properties": { "subaccount": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-Subaccount" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-Domain" }, { "type": "null" } ] }, "rule-id": { "type": "string" }, "entity-id": { "type": "string" }, "short-explanation": { "type": "string" }, "bounced": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-BouncedStat" } }, "required": [ "bounced" ] }, "github.com-mailgun-bounce-classification-internal-api-ListStatsResp": { "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-Stat" }, { "type": "null" } ] } }, "_duration": { "type": "string" } }, "required": [ "items", "_duration" ] }, "github.com-mailgun-bounce-classification-entities-AccountStat": { "type": "object", "properties": { "domain": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-Domain" }, "bounced": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-BouncedStat" } }, "required": [ "domain", "bounced" ] }, "github.com-mailgun-bounce-classification-internal-api-ListAccountStatsResp": { "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-AccountStat" }, { "type": "null" } ] } }, "total": { "type": [ "integer", "null" ], "format": "int32" }, "req": { "type": "object" } }, "required": [ "items" ] }, "github.com-mailgun-bounce-classification-entities-DomainStat": { "type": "object", "properties": { "entity-id": { "type": "string" }, "entity-name": { "type": "string" }, "bounced": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-BouncedStat" } }, "required": [ "entity-id", "entity-name", "bounced" ] }, "github.com-mailgun-bounce-classification-internal-api-ListDomainStatsResp": { "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-DomainStat" }, { "type": "null" } ] } } }, "required": [ "items" ] }, "github.com-mailgun-bounce-classification-entities-EntityStat": { "type": "object", "properties": { "rule-id": { "type": "string" }, "category": { "type": "string" }, "severity": { "type": "string" }, "sample-text": { "type": "string" }, "explanation": { "type": "string" }, "bounced": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-BouncedStat" } }, "required": [ "rule-id", "category", "severity", "sample-text", "explanation", "bounced" ] }, "github.com-mailgun-bounce-classification-internal-api-ListEntityStatsResp": { "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-EntityStat" }, { "type": "null" } ] } } }, "required": [ "items" ] }, "github.com-mailgun-bounce-classification-internal-config-Entity": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "github.com-mailgun-bounce-classification-internal-config-Entities": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-config-Entity" } }, "github.com-mailgun-bounce-classification-internal-config-Rule": { "type": "object", "properties": { "entity_id": { "type": "string" }, "class": { "type": "string" }, "sample-text": { "type": "string" }, "explanation": { "type": "string" }, "short-explanation": { "type": "string" } } }, "github.com-mailgun-bounce-classification-internal-config-Rules": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-config-Rule" } }, "github.com-mailgun-bounce-classification-entities-Resolution": { "type": "string", "enum": [ "day", "hour" ], "description": "Resolution of the metrics.", "x-enumDescriptions": { "day": "Day", "hour": "Hour" } }, "github.com-mailgun-bounce-classification-internal-api-Dimension": { "type": "string", "enum": [ "entity-name", "domain.name", "envelope.sending-ip", "account.name", "envelope.i-ip-pool-name", "tags", "tag", "recipient-domain", "group-id", "criticality", "severity", "category", "timestamp" ], "description": "Dimension", "x-enumDescriptions": { "entity-name": "Recipient Provider/Spam Filter, e.g. Gmail, Other US, Spamcop, etc.", "domain.name": "Sender domain name, e.g. example.com", "envelope.sending-ip": "Sending IP address", "account.name": "Subaccount name", "envelope.i-ip-pool-name": "IP Pool name", "tags": "Tags. Not compatible with `tag` dimension.", "tag": "Tag. Not compatible with `tags` dimension.", "recipient-domain": "Recipient domain, e.g. gmail.com", "group-id": "Group ID", "criticality": "Criticality, e.g. CRITICAL or NON-CRITICAL", "severity": "Severity, e.g. PERMANENT or TEMPORARY", "category": "Category, e.g. BOUNCE, GENERIC, GREYLISTED, ESPBLOCK, etc.", "timestamp": "BoD or BoH timestamp (depends on resolution)" } }, "github.com-mailgun-bounce-classification-internal-api-PaginationResp": { "type": "object", "properties": { "sort": { "type": "string", "description": "'sort' from the request" }, "skip": { "type": "integer", "format": "int64", "description": "'skip' from the request" }, "limit": { "type": "integer", "format": "int64", "description": "'limit' from the request" }, "total": { "type": "integer", "format": "int64", "description": "The total number of items in the query result set." } }, "required": [ "sort", "skip", "limit", "total" ] }, "github.com-mailgun-bounce-classification-entities-MetricsCountsAndRates": { "type": "object", "properties": { "critical_bounce_count": { "type": "integer", "format": "int64" }, "non_critical_bounce_count": { "type": "integer", "format": "int64" }, "critical_delay_count": { "type": "integer", "format": "int64" }, "non_critical_delay_count": { "type": "integer", "format": "int64" }, "classified_failures_count": { "type": "integer", "format": "int64", "description": "Total bounces and delays" }, "delivered_smtp_count": { "type": [ "integer", "null" ], "format": "int64", "description": "null for Spam Filters" }, "critical_bounce_rate": { "type": [ "integer", "null" ], "format": "int64", "description": "Percentages; null for Spam Filters" }, "non_critical_bounce_rate": { "type": [ "integer", "null" ], "format": "int64", "description": "Percentages; null for Spam Filters" }, "critical_delay_rate": { "type": [ "integer", "null" ], "format": "int64", "description": "Percentages; null for Spam Filters" }, "non_critical_delay_rate": { "type": [ "integer", "null" ], "format": "int64", "description": "Percentages; null for Spam Filters" } }, "required": [ "critical_bounce_count", "non_critical_bounce_count", "critical_delay_count", "non_critical_delay_count", "classified_failures_count", "delivered_smtp_count", "critical_bounce_rate", "non_critical_bounce_rate", "critical_delay_rate", "non_critical_delay_rate" ] }, "github.com-mailgun-bounce-classification-entities-MetricsItem": { "type": "object", "properties": { "account.id": { "type": [ "string", "null" ] }, "account.name": { "type": [ "string", "null" ] }, "entity-name": { "type": [ "string", "null" ] }, "recipient-provider": { "type": [ "string", "null" ] }, "recipient-domain": { "type": [ "string", "null" ] }, "domain.name": { "type": [ "string", "null" ] }, "envelope.i-ip-pool-id": { "type": [ "string", "null" ] }, "envelope.i-ip-pool-name": { "type": [ "string", "null" ] }, "envelope.sending-ip": { "type": [ "string", "null" ] }, "timestamp": { "type": [ "string", "null" ] }, "tags": { "type": [ "string", "null" ], "description": "Concatenated tags" }, "tag": { "type": [ "string", "null" ] }, "criticality": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "group-id": { "type": [ "string", "null" ] }, "sample-text": { "type": [ "string", "null" ] }, "explanation": { "type": [ "string", "null" ] }, "metrics": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-MetricsCountsAndRates" } ], "description": "Counts and rates" } }, "required": [ "metrics" ] }, "github.com-mailgun-bounce-classification-internal-api-MetricsResponse": { "type": "object", "properties": { "start": { "type": "string", "description": "A start timestamp in RFC 2822 format: https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview#date-format" }, "end": { "type": "string", "description": "An end timestamp in RFC 2822 format: https://documentation.mailgun.com/docs/mailgun/api-reference/api-overview#date-format" }, "resolution": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-Resolution" } ], "description": "'resolution' from the request" }, "duration": { "type": "string", "description": "'duration' from the request" }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-Dimension" }, "description": "'dimensions' from the request" }, "pagination": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-PaginationResp" }, "items": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-MetricsItem" }, { "type": "null" } ] } } }, "required": [ "start", "end", "resolution", "pagination", "items" ] }, "github.com-mailgun-holster-v4-clock-RFC822Time": { "type": "object" }, "github.com-mailgun-bounce-classification-internal-api-FilterAttribute": { "type": "string", "enum": [ "entity-name", "domain.name", "envelope.sending-ip", "account.name", "envelope.i-ip-pool-name", "tags", "tag", "recipient-domain", "group-id", "criticality", "severity", "category" ], "description": "Filter attribute", "x-enumDescriptions": { "entity-name": "Recipient Provider/Spam Filter, e.g. Gmail, Other US, Spamcop, etc.", "domain.name": "Sender domain name, e.g. example.com", "envelope.sending-ip": "Sending IP address", "account.name": "Subaccount name", "envelope.i-ip-pool-name": "IP Pool name", "tags": "Tags. Not compatible with `tag` dimension.", "tag": "Tag. Not compatible with `tags` dimension.", "recipient-domain": "Recipient domain, e.g. gmail.com", "group-id": "Group ID", "criticality": "Criticality, e.g. CRITICAL or NON-CRITICAL", "severity": "Severity, e.g. PERMANENT or TEMPORARY", "category": "Category, e.g. BOUNCE, GENERIC, GREYLISTED, ESPBLOCK, etc." } }, "github.com-mailgun-bounce-classification-internal-api-LabeledValue": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] }, "github.com-mailgun-bounce-classification-internal-api-FilterPredicate": { "type": "object", "properties": { "attribute": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-FilterAttribute" }, "comparator": { "type": "string" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-LabeledValue" } } }, "required": [ "attribute", "comparator" ] }, "github.com-mailgun-bounce-classification-internal-api-FilterPredicateGroup": { "type": "object", "properties": { "AND": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-FilterPredicate" } } }, "required": [ "AND" ] }, "github.com-mailgun-bounce-classification-internal-api-PaginationReq": { "type": "object", "properties": { "sort": { "type": "string", "description": "Colon-separated value indicating column name and sort direction e.g. 'entity-name:asc'." }, "skip": { "type": "integer", "format": "int64", "description": "The number of items to skip over when satisfying the request. To get the first page of data set skip to zero. Then increment the skip by the limit for subsequent calls." }, "limit": { "type": "integer", "maximum": 50, "format": "int64", "description": "The maximum number of items returned in the response.", "default": 10 } } }, "github.com-mailgun-bounce-classification-internal-api-MetricsRequest": { "type": "object", "properties": { "start": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-holster-v4-clock-RFC822Time" } ], "description": "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": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-holster-v4-clock-RFC822Time" } ], "description": "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": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-entities-Resolution" } ] }, "duration": { "type": "string", "description": "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": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-Dimension" }, "description": "Dimensions." }, "metrics": { "type": "array", "items": { "type": "string" }, "description": "Metrics to return. See example." }, "filter": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-FilterPredicateGroup" } ], "description": "Filters to apply to the query." }, "include_subaccounts": { "type": "boolean", "description": "Include stats from all subaccounts." }, "pagination": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/github.com-mailgun-bounce-classification-internal-api-PaginationReq" } ], "description": "Attributes used for pagination and sorting." } } }, "github.com-mailgun-users-api-UserListResponse": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/github.com-mailgun-users-api-UserResponse" } }, "total": { "type": "integer", "description": "total number of users on the account or the total number of users that match the query" } } }, "github.com-mailgun-users-api-UserResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "the user ID" }, "activated": { "type": "boolean", "description": "user activation status" }, "name": { "type": "string", "description": "full name of user" }, "is_disabled": { "type": "boolean", "description": "disablement status of user" }, "email": { "type": "string", "description": "user email address" }, "email_details": { "type": "object", "properties": { "address": { "type": "string", "description": "the full email address" }, "is_valid": { "type": "boolean", "description": "whether the email address is valid" }, "reason": { "type": "string", "description": "reason why user email is not valid, if applicable" }, "parts": { "type": "object", "properties": { "domain": { "type": "string", "description": "email domain" }, "local_part": { "type": "string", "description": "user email identifier" }, "display_name": { "type": "string", "description": "email display name, if applicable" } } } } }, "role": { "type": "string", "description": "role of user on the account" }, "account_id": { "type": "string", "description": "account ID" }, "opened_ip": { "type": "string", "description": "IP address from which the user opened the account, if applicable" }, "is_master": { "type": "boolean", "description": "whether the user is the account owner" }, "metadata": { "type": "object", "description": "any optional metadata for the user" }, "tfa_enabled": { "type": "boolean", "description": "whether 2-factor auth has been enabled for the user" }, "tfa_active": { "type": "boolean", "description": "whether 2-factor auth has been activated for the user" }, "tfa_created_at": { "example": "2022-12-20T16:52:01.892000", "oneOf": [ { "type": "string", "description": "the date and time at which 2-factor auth was activated in ISO 8601 date-time format without timezone offset (UTC time) and with microseconds", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{6}$" }, { "type": "null", "description": "2FA is not enabled" } ] }, "password_updated_at": { "example": "2022-12-20T16:52:01.892000", "oneOf": [ { "type": "string", "description": "the date and time at which the user password was last updated in ISO 8601 date-time format without timezone offset (UTC time) and with microseconds", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{6}$" }, { "type": "null", "description": "password has not been updated" } ] }, "preferences": { "type": "object", "properties": { "time_zone": { "type": "string", "description": "time zone for the user" }, "time_format": { "type": "string", "description": "preferred timestamp format for the user's in-app experience" }, "programming_language": { "type": "string", "description": "preferred programming language" } } }, "auth": { "type": "object", "$ref": "#/components/schemas/github.com-mailgun-users-api-UserAuthResponse" }, "github_user_id": { "oneOf": [ { "type": "string", "description": "Github ID, if part of Github Student Developer Pack account" }, { "type": "null" } ] }, "salesforce_user_id": { "oneOf": [ { "type": "string", "description": "Salesforce ID, if part of Salesforce platform account" }, { "type": "null" } ] }, "migration_status": { "type": "string", "description": "status of migration to Sinch ID for user authentication, if applicable" } } }, "github.com-mailgun-users-api-UserAuthResponse": { "type": "object", "properties": { "method": { "type": "string", "description": "The user-level auth method" }, "prior_method": { "type": "string", "description": "The previous auth method for the user, if applicable" }, "prior_details": { "type": "object", "description": "Details that may be needed for an auth method" } }, "required": [ "method" ] }, "github.com-mailgun-users-api-GenericResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Status message" } }, "required": [ "message" ] } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic auth using api:YOUR_API_KEY. See [documentation](https://documentation.mailgun.com/docs/mailgun/api-reference/authentication/)" } } }, "x-tagGroups": [ { "name": "Messages", "tags": [ "Messages" ] }, { "name": "Domains", "tags": [ "Domains", "Domain Connection", "Domain Keys", "Domain Tracking", "DKIM Security" ] }, { "name": "Webhooks", "tags": [ "Account Webhooks", "Domain Webhooks" ] }, { "name": "Reporting", "tags": [ "Metrics", "Logs", "Bounce Classification", "Tags New", "Stats", "Tags", "Events" ] }, { "name": "Send Alerts", "tags": [ "Send Alerts", "Alerts" ] }, { "name": "Threshold Limits", "tags": [ "Limits" ] }, { "name": "Suppressions", "tags": [ "Unsubscribe", "Complaints", "Bounces", "Allowlist" ] }, { "name": "Routes", "tags": [ "Routes" ] }, { "name": "Mailing Lists", "tags": [ "Mailing Lists" ] }, { "name": "Templates", "tags": [ "Account Templates", "Domain Templates" ] }, { "name": "IP Pools", "tags": [ "IP Pools", "Dynamic IP Pools" ] }, { "name": "IPs", "tags": [ "IPs", "IP Address Warmup" ] }, { "name": "Subaccounts", "tags": [ "Subaccounts" ] }, { "name": "Custom Message Limit", "tags": [ "Custom Message Limit" ] }, { "name": "Account Management", "tags": [ "Account Management" ] }, { "name": "Keys", "tags": [ "Keys" ] }, { "name": "Credentials", "tags": [ "Credentials" ] }, { "name": "IP Allowlist", "tags": [ "IP Allowlist" ] }, { "name": "Users", "tags": [ "Users" ] } ] }