openapi: 3.1.0 info: title: Mailgun API description: Mailgun API defined by OpenAPI Specification (OAS) 3.1.0 version: 0.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: 1. Send emails using MIME format using a MIME building library 2. Submit the individual parts (Text, html, attachments, etc.) Reminder: 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 Connection description: >- A Domain Connection makes it easy for a user to configure DNS for a domain running at a DNS provider to work with a Service running at an independent Service Provider. x-displayName: Domain Connection - 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: Webhooks description: >- Webhooks API manages domain's webhooks. You can create, access and delete webhooks programmatically. x-displayName: 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: openapi-tower-new_other x-displayName: other - name: Events description: >- Mailgun keeps track of every inbound and outbound message event and stores this data for at least 3 days. 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. 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/openapi-final/tag/Metrics/) API. x-displayName: Stats - name: openapi-scout-new_other x-displayName: other - name: Metrics description: >- Mailgun collects many different events and generates event metrics which are available in your Control Panel. This data is also available via our analytics metrics API endpoint. x-displayName: Metrics - 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: >- Emaill 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: Whitelist description: >- The whitelist API provides the ability to whitelist specific addresses from being added to bounce list. You can whitelist 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 whitelisted. This API is very useful if you test against your private services and don’t want to constantly clean up bounce lists. x-displayName: Whitelist - 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: Templates description: >- This API allows you to store predefined templates and use them to send messages using the Sending API. x-displayName: Templates - 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: Keys description: The Keys API lets you view and manage api keys. x-displayName: Keys - 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: 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 and text parts, attachments, etc. Mailgun will build a MIME representation of the message and send it. Note: In order to send you must provide one of the following parameters: 'text', 'html', 'amp-html' or 'template' 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 16 kB 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 for your programming language and submit it to Mailgun. 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 16 kB 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 emails associated events 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: text/html; charset=ascii From: foo.bar@my-domain.com Message-Id: Mime-Version: '1.0' Subject: '"Mailgun is awesome"' To: cool.barr@cool.com, bar.baz@gmail.com X-Mailgun-Tag: Earth sender: foo.bar@my-domain.com recipients: cool.barr@cool.com, bar.baz@gmail.com from: foo.bar@my-domain.com subject: '"Mailgun is awesome"' 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 examples: Example: value: message: Invalid storage key '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: [] /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: >- To only get 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: >- To only get 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 responses: '200': description: A 200 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-ListDomainResponse examples: Example: value: total_count: 1 items: - created_at: RFC1123 formatted date id: '1' name: example.com 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 receiving_dns_records: - cached: [] name: example.com priority: '10' record_type: MX valid: unknown sending_dns_records: - cached: - list - of - cached - mx - records 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 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 - name: h:extended in: query description: >- Default to false. If set to true, domain payload will include dkim_host, mailfrom_host and pod schema: type: boolean - name: h:with_dns in: query description: >- Default to true, domain payload will include sending and receiving dns records payload schema: type: boolean 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 '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 a domain description: >- Update domains 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: - list - of - cached - mx - records 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: RFC1123 formatted date 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: - list - of - cached - mx - records name: example.com priority: '10' record_type: the record type like CNAME, MX, DKIM, ... valid: either valid or unknown value: value from cache or name server receiving_dns_records: - cached: - list - of - cached - mx - records name: example.com priority: '10' record_type: the record type like CNAME, MX, DKIM, ... valid: either valid or unknown value: value from cache or name server '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/{name}/connection: get: tags: - Domain Connection summary: Get connection's details description: Returns domain's delivery connection settings. operationId: GET-v3-domains--name--connection 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-GetDomainConnectionResp examples: Example: value: require_tls: true skip_verification: 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: [] put: tags: - Domain Connection summary: Update domain connection settings description: Update a domain's TLS connection settings. operationId: PUT-v3-domains--name--connection 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-connection-multipart-form-data-RequestBody required: true responses: '200': description: A 200 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-UpdateDomainConnectionResp examples: Example: value: message: >- Domain connection settings have been updated, may take 10 minutes to fully propagate '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: - Webhooks summary: Get all webhooks description: Listing urls of every webhooks under the domain. operationId: GET-v3-domains--domain--webhooks parameters: - name: domain in: path description: The name of the domain you want to get webhook from 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: clicked: urls: - https://foo.com opened: 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: [] post: tags: - Webhooks summary: Create a webhook description: >- Create a list of one or more urls provided by the `url` query params. Targeted webhook name is defined through the `id` param. operationId: POST-v3-domains--domain--webhooks parameters: - name: domain in: path description: The name of the domain you want to get webhook from 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 '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: - Webhooks summary: Get 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: The domain you want to get webhook for required: true schema: type: string - name: webhook_name in: path description: >- The webhook type you wish to retrieve. Valid types are accepted, clicked, opened, unsubscribed, delivered, permanent_fail, temporary_fail, complained required: true schema: type: string 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: - Webhooks summary: Update a 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 name of the webhook to update. required: true schema: type: string 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: - Webhooks summary: Remove all webhooks by webhook type description: >- Empty the list of urls attached to a webhook name. It returns the list that have been removed. operationId: DELETE-v3-domains--domain-name--webhooks--webhook-name- parameters: - name: domain_name in: path description: The name of the domain you want to delete the webhook from required: true schema: type: string - name: webhook_name in: path description: >- The name of the webhook to delete. Supported webhook names are accepted, clicked, opened, unsubscribed, delivered, permanent_fail, temporary_fail, and complained. required: true schema: type: string 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: [] /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: |

unsubscribe

text_footer: |+ To unsubscribe click: <%unsubscribe_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: [] /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. The page & limit data is only required when paging through the data. 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: https://.... first: https://.... next: https://.... last: https://.... '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-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 '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: Domain DKIM authority 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: [] /v3/domains/{name}/message_ttl: put: tags: - Domains summary: Update the message TTL (time to live) description: >- Deprecated: please use PUT /v4/domains/{name} instead.Set both incoming and outgoing message retrieval TTL. The max TTL depends on your plan operationId: PUT-v3-domains--name--message-ttl 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-message_ttl-multipart-form-data-RequestBody required: true responses: '200': description: A 200 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-GetDomainSendingQueuesResp examples: Example: value: message: Domain message TTL settings updated. '400': description: A 400 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError examples: Example: value: Reason: >- provided message_ttl of 300000 is too large. max message_ttl for this account is 259200 seconds '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 deprecated: true security: - basicAuth: [] /v3/domains/{name}/mailfrom_host: put: tags: - Domains summary: Update the mailfrom hostname description: >- Deprecated: please use PUT /v4/domains/{name} instead.Update the MAILFROM hostname used by default for emails sent using the domain. operationId: PUT-v3-domains--name--mailfrom-host 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-mailfrom_host-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 '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 deprecated: true security: - basicAuth: [] /v3/domains/{name}/web_prefix: put: tags: - Domains summary: Update domains web prefix description: >- Deprecated: please use PUT /v4/domains/{name} instead.This updates the web prefix used for a domain's tracking features. This impacts click, open, and unsubscribe tracking features. 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. operationId: PUT-v3-domains--name--web-prefix 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-web_prefix-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: Domain web prefix updated '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 deprecated: true 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: api.(*DomainsAPIController).UpdateDKIMRotation-fm-8 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/DomainResponse' examples: Example: value: domain: state: enabled records: - comment: Customer DKIM CNAME Record identifier: DKIM name: pdk1._domainkey.example.com type: CNAME value: pdk1._domainkey.1234567.service.mailgun.com - comment: Customer DKIM CNAME Record identifier: DKIM name: pdk2._domainkey.example.com type: CNAME value: pdk2._domainkey.1234567.service.mailgun.com account_id: '000000000000000000000001' active_selector: pdk1 id: '000000000000000000000002' sid: '789' name: example.com rotation_enabled: 'true' rotation_interval: 24h '400': description: A 400 response content: application/json: schema: $ref: '#/components/schemas/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/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: api.(*DomainsAPIController).Rotate-fm-10 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/GenericResponse' examples: Example: value: message: ok '400': description: A 400 response content: application/json: schema: $ref: '#/components/schemas/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/NotFoundError' examples: Example: value: Description: domain not found security: - basicAuth: [] /v5/accounts/subaccounts/ip_pools: get: summary: List DIPPs delegated to subaccounts description: >- #### Description Lists all subaccounts of the parent account to which the parent account has delegated DIPPs. operationId: subaccounts.RegisterAPIs.Endpoint.func1-123 responses: '200': description: A 200 response content: application/json: schema: $ref: '#/components/schemas/ListSubaccountDIPPsResponse' examples: Example: value: items: - pool_id: 673508e5969b78b176ed49bb subaccount_id: 673508e5969b78b176ed49bd - pool_id: 673508e5969b78b176ed49bc subaccount_id: 673508e5969b78b176ed49be total_count: 2 '404': description: A 404 response content: application/json: schema: $ref: '#/components/schemas/GenericResponse' examples: Example: value: message: account not found tags: - openapi-tower-new_other security: - basicAuth: [] /v5/accounts/subaccounts/{subaccountId}/ip_pool: put: summary: Delegate a DIPP to a subaccount description: >- #### Description Initiates the process to delegate a DIPP to a subaccount. If the subaccount already has a DIPP delegated to it, that DIPP will be replaced. The success of this API call only indicates that the process has been started; it can still fail midway for various reasons. #### Request Schema Request parameters are encoded as form data. Name | Description | Required | Type --- | --- | --- | --- pool_id | Id of the DIPP to delegate | true | string operationId: subaccounts.RegisterAPIs.Endpoint.func3-127 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/StartSagaResponse' examples: Example: value: reference_id: 673508e5969b78b176ed49c0 message: started '400': description: A 400 response content: application/json: schema: $ref: '#/components/schemas/GenericResponse' examples: Example: value: message: invalid request parameters '404': description: A 404 response content: application/json: schema: $ref: '#/components/schemas/GenericResponse' examples: Example: value: message: account not found tags: - openapi-tower-new_other security: - basicAuth: [] delete: summary: Revoke a DIPP delegated to a subaccount description: >- #### Description Initiates the process to revoke a DIPP delegated to a subaccount. All domains linked to the DIPP will be unlinked. operationId: subaccounts.RegisterAPIs.Endpoint.func2-125 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/StartSagaResponse' examples: Example: value: message: started reference_id: 673508e5969b78b176ed49bf '400': description: A 400 response content: application/json: schema: $ref: '#/components/schemas/GenericResponse' examples: Example: value: message: invalid request parameters '404': description: A 404 response content: application/json: schema: $ref: '#/components/schemas/GenericResponse' examples: Example: value: message: account not found tags: - openapi-tower-new_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 one of the following: * a valid IP address: this IP address will be removed from the domain pool. * string `all`: the entire domain pool will be removed. As long as Tower is concerned, such domain will no longer exist. * string `ip_pool`: the DIPP which is currently linked to the domain will be unlinked. ### Removing An IP Note that it's impossible to alter domain IPs if a DIPP is linked to the domain. If the account is not eligible for shared IPs, additional rules apply: * removing the last IP from the domain is not allowed; * if all of the remaining dedicated IPs are on warmup, an extra IP might be added to the domain pool. ### Unlinking The DIPP The account must have 'DIPPs' feature enabled. Either `ip` or `pool_id` query parameter must be specified, but not both. If the special value `shared` is used for the replacement IP, the account must be eligible for shared IPs. In this case the system will assign a shared IP as the replacement. operationId: domain.(*domainAPIController).remove-fm-7 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: X-Mailgun-Account-Id in: header description: Account ID required: true schema: type: string - name: X-Mailgun-Requestor in: header description: Email address of the user making the request. required: true schema: type: string - name: X-Mailgun-Requestor-Client in: header description: Identifier of the client application making the request. 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/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 one of the following: * a valid IP address: this IP address will be removed from the domain pool. * string `all`: the entire domain pool will be removed. As long as Tower is concerned, such domain will no longer exist. * string `ip_pool`: the DIPP which is currently linked to the domain will be unlinked. ### Removing An IP Note that it's impossible to alter domain IPs if a DIPP is linked to the domain. If the account is not eligible for shared IPs, additional rules apply: * removing the last IP from the domain is not allowed; * if all of the remaining dedicated IPs are on warmup, an extra IP might be added to the domain pool. ### Unlinking The DIPP The account must have 'DIPPs' feature enabled. Either `ip` or `pool_id` query parameter must be specified, but not both. If the special value `shared` is used for the replacement IP, the account must be eligible for shared IPs. In this case the system will assign a shared IP as the replacement. operationId: domain.(*domainAPIController).remove-fm-11 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: X-Mailgun-Account-Id in: header description: Account ID required: true schema: type: string - name: X-Mailgun-Requestor in: header description: Email address of the user making the request. required: true schema: type: string - name: X-Mailgun-Requestor-Client in: header description: Identifier of the client application making the request. 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/GenericResponse' examples: Example: value: message: success 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 field is present only if the account has 'DIPPs' feature enabled. `total_count` contains the number of items returned in `items` (this depends on the filters applied). operationId: list_ips.(*Controller).Process-fm-81 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/string' examples: Example: value: assignable_to_pools: - 5.6.7.8 items: - 1.2.3.4 - 5.6.7.8 total_count: 2 details: - ip: 1.2.3.4 is_on_warmup: true - ip: 5.6.7.8 security: - basicAuth: [] /v3/ips/{ip}: get: tags: - IPs summary: Get details about account IP operationId: account.(*AccountAPIController).Get-fm-83 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/string' examples: Example: value: dedicated: true ip: 1.2.3.4 rdns: ip1-2-3-4.mailgun.net 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. Matching domains are ordered by increasing id, then the `limit` and `skip` parameters are applied. If the `search` parameter is present, it is used to limit the results to domains whose names match the search query. The search query is split into words by whitespace and punctuation, then the logical OR is applied. operationId: account.(*AccountAPIController).domains-fm-85 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/domainsResponse' examples: Example: value: items: - domain: one.example.com ips: - 1.2.3.4 - 5.6.7.8 - domain: two.example.com ips: - 1.2.3.4 total_count: 2 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. The IP must be a dedicated one belonging to the account. operationId: account.registerPublicAPIs.Endpoint.func1-87 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/string' examples: Example: value: message: success 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. Field `shared` in the response is deprecated and should not be used. operationId: account.(*AccountAPIController).allowedForRequest-fm-89 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: account.(*AccountAPIController).requestIP-fm-91 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 Lists all dedicated IP pools of the account. For each pool returns its basic properties (name, description, the list of IPs) and indicates whether the pool is linked to any domains and whether it's an inherited one. Only one pool can be inherited from the parent account. operationId: list.(*Controller).Process-fm-106 responses: '200': description: A 200 response content: application/json: schema: $ref: '#/components/schemas/string' 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 security: - basicAuth: [] post: tags: - IP Pools summary: Add a new DIPP to the account description: |- The account must have 'DIPPs' feature enabled. Returns the id of the newly created DIPP. operationId: create.(*Controller).Process-fm-108 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 domains. If it's `true`, `linked_domain` lists those domains. operationId: ip_pools.RegisterAPIs.Endpoint.func2-112 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: message: success details: name: DIPP's short name pool_id: 658041ae44842b99ee2eaa1b 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 security: - basicAuth: [] delete: tags: - IP Pools summary: Delete the DIPP description: >- The `DIPPs` feature must be enabled for the account. It is not allowed to delete a DIPP inherited from the parent account. If the DIPP is delegated to subaccounts, those will also be updated. If the replacement DIPP is specified, all domains linked to the deleted DIPP will be relinked to the replacement DIPP. The latter must contain at least one IP. If the replacement IP is specified, all domains linked to the deleted DIPP will be unlinked, and the replacement IP will be assigned to them. It is not allowed to delete a DIPP inherited from the parent account and replace it with an IP (subaccounts do not explicitly manage their IPs). The replacement IP must be a dedicated one; it can't belong to another DIPP. If a special value `shared` is used, appropriate shared IPs will be used (the account must be eligible for shared IPs in this case). Omitting both replacement DIPP and replacement IP is allowed only if the DIPP being deleted contains no IPs. The processing of affected domains and subaccounts happens asynchronously after the endpoint returns a response. operationId: ip_pools.RegisterAPIs.Endpoint.func1-110 parameters: - name: pool_id in: path description: Id of the DIPP to delete required: true schema: type: string - name: X-Mailgun-Account-Id in: header description: Account ID required: true schema: type: string - name: X-Mailgun-Requestor in: header description: Email address of the user making the request. required: true schema: type: string - name: X-Mailgun-Requestor-Client in: header description: Identifier of the client application making the request. 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: shared: 2 dedicated: 1 security: - basicAuth: [] patch: tags: - IP Pools summary: Edit DIPP description: >- The account must have 'DIPPs' feature enabled. It's not allowed to edit a DIPP inherited from the parent account. IPs being added to the DIPP must be dedicated ones and belong to the account. If IPs of the DIPP end up modified, and the DIPP is linked to domains, the domains will be updated asynchronously (after this endpoint returns response). Returns an error if the passed parameters won't result in any changes. operationId: update.(*Controller).Process-fm-114 parameters: - name: pool_id in: path description: Id of the DIPP to edit required: true schema: type: string - name: X-Mailgun-Account-Id in: header description: Account ID required: true schema: type: string - name: X-Mailgun-Requestor in: header description: Email address of the user making the request. required: true schema: type: string - name: X-Mailgun-Requestor-Client in: header description: Identifier of the client application making the request. 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}/ips/{ip}: put: tags: - IP Pools summary: Add an IP to a DIPP description: >- The account must have 'DIPPs' feature enabled. It is not allowed to modify a DIPP inherited from the parent account. The IP must be a dedicated one, belong to the account and not belong to any other DIPP. All domains linked to the DIPP will be updated so that their IPs include the newly added address. If the DIPP is delegated to subaccounts, those will also be updated. The processing of affected domains and subaccounts happens asynchronously after the endpoint returns a response. operationId: add_ip.(*Controller).AddSingleIP-fm-120 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 - name: X-Mailgun-Account-Id in: header description: Account ID required: true schema: type: string - name: X-Mailgun-Requestor in: header description: Email address of the user making the request. required: true schema: type: string - name: X-Mailgun-Requestor-Client in: header description: Identifier of the client application making the request. 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. It's not allowed to edit a DIPP inherited from the parent account. If the DIPP is linked to domains, the domains will be updated asynchronously (after this endpoint returns response). operationId: ip_pools.RegisterAPIs.Endpoint.func3-116 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 - name: X-Mailgun-Account-Id in: header description: Account ID required: true schema: type: string - name: X-Mailgun-Requestor in: header description: Email address of the user making the request. required: true schema: type: string - name: X-Mailgun-Requestor-Client in: header description: Identifier of the client application making the request. 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. It is not allowed to modify a DIPP inherited from the parent account. All IPs must be dedicated ones, belong to the account and not belong to any other DIPP. All domains linked to the DIPP will be updated so that their IPs include the newly added addresses. If the DIPP is delegated to subaccounts, those will also be updated. The processing of affected domains and subaccounts happens asynchronously after the endpoint returns a response. operationId: ip_pools.RegisterAPIs.Endpoint.func4-118 parameters: - name: pool_id in: path description: Id of the DIPP to update required: true schema: type: string - name: X-Mailgun-Account-Id in: header description: Account ID required: true schema: type: string - name: X-Mailgun-Requestor in: header description: Email address of the user making the request. required: true schema: type: string - name: X-Mailgun-Requestor-Client in: header description: Identifier of the client application making the request. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/addMultipleIPsRequestBody' examples: Example: value: ips: - 1.2.3.4 - 5.6.7.8 required: false responses: '200': description: A 200 response content: application/json: schema: $ref: '#/components/schemas/string' examples: Example: value: message: started 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 storage API host and in the domain's region. e.g. https://storage-us-east4.api.mailgun.net/v3/example.com/envelopes The storage hosts are `storage-us-east4.api.mailgun.net`, `storage-us-west1.api.mailgun.net`, and `storage-europe-west1.api.mailgun.net`. operationId: httpapi.(*Handler).handlePurgeDomainJobs-fm-3 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/GenericResponse' examples: Example: value: message: done '401': description: A 401 response content: application/json: schema: $ref: '#/components/schemas/GenericResponse' examples: Example: value: message: Invalid private key '404': description: A 404 response content: application/json: schema: $ref: '#/components/schemas/GenericResponse' examples: Example: value: message: domain not found security: - basicAuth: [] /v2/x509/{domain}/status: get: tags: - Domain Tracking summary: Status of x509 TLS certificate description: Get x509 TLS certificate and status operationId: httpapi.(*HttpAPI).getStatusV2-fm-8 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: '200': description: A 200 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-terminator-httpapi-StatusResponse examples: Expired: value: status: expired error: x509 certificate has expired certificate: '{CERT}' Active: value: certificate: '{CERT}' status: active Processing: value: status: processing error: Waiting for TLS x509 key pair generation 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: Initiate regeneration of an expired x509 TLS 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: httpapi.(*HttpAPI).regenerateExternal-fm-13 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: Initiate generation of an x509 TLS certificate 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: httpapi.(*HttpAPI).generate-fm-9 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. See [Filter expression](https://documentation.mailgun.com/docs/mailgun/user-manual/events/#filter-expression) for details about filtering expressions 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: api.InitTagsAPIController.checkErr.func3-6 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: paging: 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= previous: >- https://api.mailgun.net/v3/example.com/tags?limit=1000&page=prev&tag= items: - 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-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 '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: [] /v3/{domain}/tag: get: tags: - Tags summary: Get a tag description: Get a tag associated with a domain operationId: api.InitTagsAPIController.checkErr.func4-7 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 security: - basicAuth: [] put: tags: - Tags summary: 'Update tag ' description: Update a tag associated with a domain operationId: api.(*TagsAPIController).Update-fm-11 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 security: - basicAuth: [] delete: tags: - Tags summary: Delete tag description: Delete a tag associated with a domain operationId: api.(*TagsAPIController).Delete-fm-12 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 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: api.InitTagsAPIController.checkErr.func6-9 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: provider: aol.com: opened: 1 unique_clicked: 1 unsubscribed: 0 accepted: 0 clicked: 1 gmail.com: unsubscribed: 0 accepted: 0 clicked: 2 opened: 1 unique_clicked: 1 tag: tag1 '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: [] /v3/{domain}/tag/stats: get: tags: - Tags summary: Get stats by tag description: Retrieve stats by tag operationId: api.InitTagsAPIController.checkErr.func7-10 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: resolution: month stats: - accepted: incoming: 2 outgoing: 1 total: 3 clicked: total: 1 unique: 1 delivered: http: 10 optimized: 5 smtp: 15 total: 20 opened: total: 20 unique: 1 time: Fri, 01 Apr 2012 00:00:00 UTC tag: tag1 start: Tue, 14 Feb 2012 00:00:00 UTC description: Optional Description end: Fri, 01 Apr 2012 00:00:00 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 security: - basicAuth: [] /v3/domains/{domain}/tag/devices: get: summary: List of supported devices description: Gets a list of devices scout currently supports operationId: api.(*StatTypesAPI).GetDevicesTypes-fm-14 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 tags: - openapi-scout-new_other security: - basicAuth: [] /v3/domains/{domain}/tag/providers: get: summary: List of supported providers description: Gets a list of providers scout currently supports operationId: api.(*StatTypesAPI).GetProviderTypes-fm-15 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 tags: - openapi-scout-new_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: api.(*StatTypesAPI).GetCountryList-fm-16 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 tags: - openapi-scout-new_other security: - basicAuth: [] /v3/stats/total: get: tags: - Stats summary: Totals for entire account description: Gets stat totals for an entire account operationId: api.InitTotalsAPIController.dataRetention.func6-19 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: stats: - accepted: incoming: 2 outgoing: 1 total: 3 clicked: total: 1 unique: 1 delivered: http: 10 optimized: 5 smtp: 15 total: 20 opened: total: 20 unique: 1 time: Fri, 01 Apr 2012 00:00:00 UTC start: Tue, 14 Feb 2012 00:00:00 UTC description: Optional Description end: Fri, 01 Apr 2012 00:00:00 UTC resolution: month '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: [] /v3/{domain}/stats/total: get: tags: - Stats summary: Totals for entire domain description: Gets stat totals for an entire domain operationId: api.InitTotalsAPIController.dataRetention.func8-20 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: stats: - accepted: incoming: 2 outgoing: 1 total: 3 clicked: total: 1 unique: 1 delivered: http: 10 optimized: 5 smtp: 15 total: 20 opened: total: 20 unique: 1 time: Fri, 01 Apr 2012 00:00:00 UTC start: Tue, 14 Feb 2012 00:00:00 UTC end: Fri, 01 Apr 2012 00:00:00 UTC description: Optional Description resolution: month '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: [] /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: api.InitTotalsAPIController.dataRetention.func10-21 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: end: Fri, 01 Apr 2012 00:00:00 UTC description: Optional Description start: Tue, 14 Feb 2012 00:00:00 UTC stats: - accepted: incoming: 2 outgoing: 1 total: 3 clicked: total: 1 unique: 1 delivered: http: 10 optimized: 5 smtp: 15 total: 20 opened: total: 20 unique: 1 time: Fri, 01 Apr 2012 00:00:00 UTC resolution: month '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: [] /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: api.InitTotalsAPIController.dataRetention.func12-22 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: end: Fri, 01 Apr 2012 00:00:00 UTC resolution: month start: Tue, 14 Feb 2012 00:00:00 UTC stats: - accepted: incoming: 2 outgoing: 1 total: 3 clicked: total: 1 unique: 1 delivered: http: 10 optimized: 5 smtp: 15 total: 20 opened: total: 20 unique: 1 time: Fri, 01 Apr 2012 00:00:00 UTC description: Optional Description '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: [] /v3/domains/{domain}/limits/tag: get: tags: - Tags summary: Get tag limits description: Get tag limits by domain operationId: api.(*LimitsAPI).Get-fm-36 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 security: - basicAuth: [] /v3/{domain}/aggregates/providers: get: tags: - Stats summary: Aggregate counts by ESP description: Gets aggregate counts by email service provider operationId: api.(*DomainAggregatesAPIController).GetDomainProviders-fm-38 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: opened: 1 unique_clicked: 1 unsubscribed: 0 accepted: 0 clicked: 1 gmail.com: opened: 1 unique_clicked: 1 unsubscribed: 0 accepted: 0 clicked: 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: [] /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: api.(*DomainAggregatesAPIController).GetDomainDevices-fm-39 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: tablet: unsubscribed: 0 accepted: 0 clicked: 2 opened: 1 unique_clicked: 1 unknown: accepted: 0 clicked: 2 opened: 1 unique_clicked: 1 unsubscribed: 0 desktop: accepted: 0 clicked: 1 opened: 1 unique_clicked: 1 unsubscribed: 0 mobile: 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 security: - basicAuth: [] /v3/{domain}/aggregates/countries: get: tags: - Stats summary: Aggregate counts by country description: Gets aggregate counts by country (USA, RUS, etc…) operationId: api.(*DomainAggregatesAPIController).GetDomainCountries-fm-40 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: us: accepted: 0 clicked: 1 opened: 1 unique_clicked: 1 unsubscribed: 0 ru: unsubscribed: 0 accepted: 0 clicked: 2 opened: 1 unique_clicked: 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 security: - basicAuth: [] /v1/analytics/metrics: post: tags: - Metrics summary: Post query to get account metrics description: Gets filtered metrics for an account operationId: api.(*MetricsAPI).PostMetricQuery-fm-3 requestBody: content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-analytics-client-golang-Query examples: Example: value: resolution: month metrics: - accepted_count - delivered_count - clicked_rate - opened_rate include_aggregates: true start: Mon, 13 Nov 2023 20:56:50 -0600 duration: 1m filter: AND: - attribute: domain comparator: '=' values: - label: example.com value: example.com dimensions: - time end: Wed, 20 Dec 2023 20:56:50 -0600 include_subaccounts: true 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: items: - dimensions: - dimension: time display_value: Wed, 01 Nov 2023 00:00:00 +0000 value: Wed, 01 Nov 2023 00:00:00 +0000 metrics: accepted_count: 40 accepted_incoming_count: 10 accepted_outgoing_count: 30 clicked_count: 50 clicked_rate: '0.8300' delivered_count: 60 delivered_http_count: 20 delivered_optimized_count: 0 delivered_smtp_count: 40 opened_count: 55 - dimensions: - dimension: time display_value: Fri, 01 Dec 2023 00:00:00 +0000 value: Fri, 01 Dec 2023 00:00:00 +0000 metrics: accepted_count: 40 accepted_incoming_count: 10 accepted_outgoing_count: 30 clicked_count: 50 clicked_rate: '0.8300' delivered_count: 60 delivered_http_count: 20 delivered_optimized_count: 0 delivered_smtp_count: 40 opened_count: 55 duration: 1m end: Wed, 20 Dec 2023 20:56:50 -0600 start: Mon, 13 Nov 2023 20:56:50 -0600 resolution: month '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: Post query to get account usage metrics description: Gets filtered usage metrics for an account operationId: api.(*MetricsAPI).PostUsageMetricQuery-fm-4 requestBody: content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-analytics-client-golang-Query examples: Example: value: metrics: - 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 - link_validation_count - link_validation_failed_count - processed_count - seed_test_count duration: 1m dimensions: - time end: Wed, 20 Dec 2023 20:56:50 -0600 include_aggregates: true resolution: month filter: AND: - attribute: subaccount comparator: '=' values: - label: '12345' value: '12345' include_subaccounts: true start: Mon, 13 Nov 2023 20:56:50 -0600 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: end: Wed, 20 Dec 2023 20:56:50 -0600 resolution: month start: Mon, 13 Nov 2023 20:56:50 -0600 duration: 1m items: - dimensions: - dimension: time display_value: Wed, 01 Nov 2023 00:00:00 +0000 value: Wed, 01 Nov 2023 00:00:00 +0000 metrics: email_preview_count: 60 email_preview_failed_count: 16 email_validation_bulk_count: 40 email_validation_count: 50 email_validation_list_count: 20 email_validation_mailgun_count: 40 email_validation_mailjet_count: 5 email_validation_public_count: 55 email_validation_single_count: 30 email_validation_valid_count: 10 link_validation_count: 5 link_validation_failed_count: 7 processed_count: 3 seed_test_count: 9 - dimensions: - dimension: time display_value: Fri, 01 Dec 2023 00:00:00 +0000 value: Fri, 01 Dec 2023 00:00:00 +0000 metrics: email_preview_count: 60 email_preview_failed_count: 16 email_validation_bulk_count: 40 email_validation_count: 50 email_validation_list_count: 20 email_validation_mailgun_count: 40 email_validation_mailjet_count: 5 email_validation_public_count: 55 email_validation_single_count: 30 email_validation_valid_count: 10 link_validation_count: 5 link_validation_failed_count: 7 processed_count: 3 seed_test_count: 9 '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: [] /v3/{domainID}/whitelists/{value}: get: tags: - Whitelist summary: View a single whitelist records description: >- Fetch a single whitelist record to check if a given address or domain is present. operationId: api.(*WhitelistController).Get-fm-13 parameters: - name: domainID in: path description: The id of the domain you want the whitelist record for required: true schema: type: string - name: value in: path description: The address to search for required: true schema: type: string pattern: .+ responses: '200': description: A 200 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-blackbook-model-Whitelist examples: Example: value: type: domain reason: why the record was created value: alice@example.com createdAt: Fri, 18 Oct 2024 18:28:14 UTC '404': description: A 404 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError examples: Example: value: Description: Address/Domain not found in whitelists table security: - basicAuth: [] delete: tags: - Whitelist summary: Remove a record from whitelist description: Remove a record from whitelist operationId: api.(*WhitelistController).Delete-fm-16 parameters: - name: domainID in: path description: The id of the domain you want to delete a whitelisted record 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: Whitelist 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-NotFoundError examples: Example: value: Description: Address/Domain not found in whitelists table security: - basicAuth: [] /v3/{domainID}/whitelists: get: tags: - Whitelist summary: View all whitelist records for a domain description: Paginate over all whitelist records for a domain. operationId: api.(*WhitelistController).GetPage-fm-14 parameters: - name: domainID in: path description: The name of the domain you want to get whitelist 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: - createdAt: Fri, 18 Oct 2024 18:28:14 UTC reason: why the record was created type: domain value: alice@example.com paging: previous: first: next: last: '400': description: A 400 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError security: - basicAuth: [] post: tags: - Whitelist summary: Add a single whitelist record description: Add an address or domain to the whitelist table operationId: api.(*WhitelistController).Insert-fm-15 parameters: - name: domainID in: path description: The id of the domain you want to whitelist from 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 whitelists table type: domain value: example.com '400': description: A 400 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-MissingFieldError examples: Example: value: Field: address/domain security: - basicAuth: [] delete: tags: - Whitelist summary: 'Clear domains whitelist ' description: Delete an entire whitelist for a domain operationId: api.(*WhitelistController).DeleteAll-fm-17 parameters: - name: domainID in: path description: The id of the domain you want to delete whitelist table 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: >- Whitelist 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-GenericAPIError security: - basicAuth: [] /v3/{domainID}/unsubscribes/import: post: tags: - Unsubscribe summary: Import list of unsubscribes 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 must contain the following column headers: address, tags, created_at. operationId: api.(*ImportController).importCSV-fm-18 parameters: - name: domainID in: path description: The id of the domain you want to update 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 '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/{domainID}/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 operationId: api.(*ImportController).importCSV-fm-19 parameters: - name: domainID in: path description: The ID of the domain you want to update 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 '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/{domainID}/complaints/import: post: tags: - Complaints summary: Import list of complaints description: >- Import CSV file containing a list of addresses to add to the complaint list.The CSV file must be 25MB or under and must contain the following column headers: address, created_at operationId: api.(*ImportController).importCSV-fm-20 parameters: - name: domainID in: path description: The id of the domain you want to update 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: file uploaded successfully '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/{domainID}/whitelists/import: post: tags: - Whitelist summary: Import list of whitelisted addresses/domains description: >- Import a CSV file containing a list of addresses and/or domains to add to the whitelist. The CSV file must be 25MB or under and must contain the following column headers: address, domain. operationId: api.(*ImportController).importCSV-fm-21 parameters: - name: domainID in: path description: The id of the domain you want to update 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 '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/{domainID}/bounces/{address}: get: tags: - Bounces summary: 'View single bounce event ' description: Fetch a single bounce event by a given email address. operationId: api.(*BounceController).Get-fm-22 parameters: - name: domainID in: path description: The id of the domain you want to get bounce from required: true schema: type: string - name: address in: path description: The address to search for required: true schema: type: string pattern: .+ 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 created_at: Fri, 18 Oct 2024 18:28:14 UTC code: '550' error: No such mailbox '404': description: A 404 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError examples: Example: value: Description: Address not found in bounces table security: - basicAuth: [] delete: tags: - Bounces summary: Clear a single bounce description: >- The delivery to the deleted email address resumes until it bounces again. operationId: api.(*BounceController).Delete-fm-27 parameters: - name: domainID in: path description: The id of the domain you want to delete a bounce from required: true schema: type: string - name: address in: path description: The address to remove required: true schema: type: string pattern: .+ 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-GenericAPIError '404': description: A 404 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError examples: Example: value: Description: Address not found in bounces table security: - basicAuth: [] /v3/{domainID}/bounces: get: tags: - Bounces summary: View all bounces description: Paginate over a list of bounces for a domain. operationId: api.(*BounceController).GetPage-fm-23 parameters: - name: domainID in: path description: The name of the domain you want to get 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' created_at: Fri, 18 Oct 2024 18:28:14 UTC error: No such mailbox paging: next: last: previous: first: '400': description: A 400 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError security: - basicAuth: [] post: tags: - Bounces summary: Insert bounce records to the bounces list 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: api.(*BounceController).InsertJSON-fm-24 parameters: - name: domainID in: path description: The id of the domain you want to insert bounces 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/form-data: schema: $ref: >- #/components/schemas/POST-v3-domainID-bounces-application-form-data-RequestBody application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-blackbook-api-BouncesList examples: Example: value: - address: alice@example.com code: '550' createdat: {} error: Bounced messagehash: '' - address: bob@example.com code: '550' createdat: {} error: Bounced messagehash: '' - address: carol@example.com code: '550' createdat: {} error: '' messagehash: '' - address: dan@example.com code: '' createdat: {} error: '' messagehash: '' 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-GenericAPIError examples: Example: value: Reason: Batch size should be less than 1000 security: - basicAuth: [] delete: tags: - Bounces summary: Delete entire bounce list description: >- Clears all email addresses with bounces from the domain. Delivery to the deleted email addresses will longer be suppressed. operationId: api.(*BounceController).DeleteAll-fm-28 parameters: - name: domainID in: path description: The id of the domain you want 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-GenericAPIError '404': description: A 404 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError security: - basicAuth: [] /v3/{domainID}/unsubscribes/{address}: get: tags: - Unsubscribe summary: View a single unsubscribe description: >- Fetch a single unsubscribe record to check if a given address is present in a list of unsubscribed users. operationId: api.(*UnsubscribeController).Get-fm-29 parameters: - name: domainID in: path description: The id of the domain you want to fetch an unsubscribe from required: true schema: type: string - name: address in: path description: The address to search for required: true schema: type: string pattern: .+ responses: '200': description: A 200 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-blackbook-model-Unsubscribe examples: Example: value: tags: - some tag created_at: Fri, 18 Oct 2024 18:28:14 UTC address: alice@example.com '404': description: A 404 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError examples: Example: value: Description: Address not found in unsubscribers table security: - basicAuth: [] delete: tags: - Unsubscribe summary: Clear a given unsubscribe event description: >- The delivery to the deleted email address resumes until it unsubscribes again. operationId: api.(*UnsubscribeController).Delete-fm-33 parameters: - name: domainID in: path description: The id of the domain you want to delete a unsubscribe from required: true schema: type: string - name: address in: path description: The address to remove required: true schema: type: string pattern: .+ 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-GenericAPIError '404': description: A 404 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError examples: Example: value: Description: Unsubscribe event for this tag does not exist security: - basicAuth: [] /v3/{domainID}/unsubscribes: get: tags: - Unsubscribe summary: View all unsubscribes description: Paginate over a list of unsubscribes for a domain. operationId: api.(*UnsubscribeController).GetPage-fm-30 parameters: - name: domainID in: path description: The name of the domain you want to get 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 created_at: Fri, 18 Oct 2024 18:28:14 UTC tags: - some tag paging: previous: first: next: last: '400': description: A 400 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError security: - basicAuth: [] post: tags: - Unsubscribe summary: Insert unsubscribe records to the unsubscribe list 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: api.(*UnsubscribeController).InsertJSON-fm-31 parameters: - name: domainID in: path description: The id of the domain you want to insert unsubscribes 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/form-data: schema: $ref: >- #/components/schemas/POST-v3-domainID-unsubscribes-application-form-data-RequestBody application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-blackbook-api-UnsubscribesList examples: Example: value: - address: alice@example.com createdat: {} tags: - some tag - address: bob@example.com createdat: {} tags: - '*' - address: carol@example.com createdat: {} tags: [] 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-GenericAPIError examples: Example: value: Reason: Batch size should be less than 1000 security: - basicAuth: [] delete: tags: - Unsubscribe summary: Delete entire unsubscribe list description: >- Clear all unsubscribe email addresses for the domain. Delivery to the deleted email addresses will no longer be suppressed. operationId: api.(*UnsubscribeController).DeleteAll-fm-34 parameters: - name: domainID in: path description: The id of the domain you want 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-GenericAPIError '404': description: A 404 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError security: - basicAuth: [] /v3/{domainID}/complaints/{address}: get: tags: - Complaints summary: View a single complaint record description: >- Fetch a single complaint records to check if a given address is present in the list of complaints. operationId: api.(*ComplaintController).Get-fm-36 parameters: - name: domainID in: path description: The id of the domain you want to fetch a complaint from required: true schema: type: string - name: address in: path description: The address to search for required: true schema: type: string pattern: .+ 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: Fri, 18 Oct 2024 18:28:14 UTC '404': description: A 404 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-NotFoundError examples: Example: value: Description: No spam complaints found for this address security: - basicAuth: [] delete: tags: - Complaints summary: Clear a single complaint event description: >- The delivery to the deleted email address resumes until there is another complaint. operationId: api.(*ComplaintController).Delete-fm-40 parameters: - name: domainID in: path description: The id of the domain you want to delete a complaint from required: true schema: type: string - name: address in: path description: The address to remove required: true schema: type: string pattern: .+ 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-NotFoundError examples: Example: value: Description: No spam complaints found for this address security: - basicAuth: [] /v3/{domainID}/complaints: get: tags: - Complaints summary: View all complaints description: Paginate a list of complaints for the domain. operationId: api.(*ComplaintController).GetPage-fm-37 parameters: - name: domainID in: path description: The name of the domain you want to get 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: Fri, 18 Oct 2024 18:28:14 UTC paging: last: previous: first: next: '400': description: A 400 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericAPIError security: - basicAuth: [] post: tags: - Complaints summary: Insert complaint records to the complaints list 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: api.(*ComplaintController).InsertJSON-fm-38 parameters: - name: domainID in: path description: The id of the domain you want to insert complaints 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/form-data: schema: $ref: >- #/components/schemas/POST-v3-domainID-complaints-application-form-data-RequestBody application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-blackbook-api-ComplaintsList examples: Example: value: - address: alice@example.com createdat: {} - address: bob@example.com createdat: {} 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-GenericAPIError examples: Example: value: Reason: Batch size should be less than 1000 security: - basicAuth: [] delete: tags: - Complaints summary: Delete entire complaints list description: >- Clears all email addresses with complaints from the domain. Delivery to the deleted email addresses will longer be suppressed. operationId: api.(*ComplaintController).DeleteAll-fm-41 parameters: - name: domainID in: path description: The id of the domain you want 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-GenericAPIError 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: multipart/form-data: 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 route: $ref: '#/components/schemas/RouteResponse' 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 items: type: array items: $ref: '#/components/schemas/RouteResponse' 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 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 examples: Example: value: '': 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: multipart/form-data: 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: id: 4f3bad2335335426750048c6 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 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 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 id: type: string 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 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 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 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' 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 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 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 security: - basicAuth: [] post: tags: - Mailing Lists summary: Create a mailing list member description: Adds a new member to the mailing list. 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 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 examples: Example: value: message: Address already exists 'alice@example.com' 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. If the request includes more than 100 entries, the mailing list will be updated asynchronously. 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 message: type: string 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 examples: Example: value: message: Mailing list 'devs@mg.net' not found 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 message: type: string 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 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 examples: Example: value: message: Mailing list 'devs@mg.net' not found 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 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 examples: Example: value: member: address: alice@example.com name: Alice vars: gender: female age: 27 subscribed: true message: Mailing list member has been updated 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 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 examples: Example: value: message: >- Member dev@example.com of mailing list alice@example.com not found 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 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 examples: Example: value: message: Mailing list developers@mailgun.net not found security: - basicAuth: [] delete: tags: - Mailing Lists summary: Delete 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 message: type: string 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 examples: Example: value: message: Mailing list developers@mailgun.net not found 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 examples: Example: value: message: Mailing list developers@mailgun.net not found 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_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: '' 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_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: '' security: - basicAuth: [] /v3/{domainId}/templates: get: tags: - Templates summary: Get templates description: Returns a list of templates for the domain. operationId: httpapi.(*TemplateAPIControler).GetPage-fm-9 parameters: - name: domainId 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`. required: true schema: type: string - name: limit in: query description: Number of templates to retrieve. Default and max limit is 100. required: true schema: type: integer - name: p in: query description: Pivot used to retrieve the next page of templates. required: true 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: - createdAt: Sat, 12 Nov 1955 06:38:00 UTC createdBy: '' description: template description id: 48d63154-8c8f-4104-ab14-687d01dbf296 name: template.0 version: null versions: null - createdAt: Sat, 12 Nov 1955 06:38:00 UTC createdBy: '' description: template description id: 8d9c0f0d-7bf7-43a4-92a9-791a854d12a4 name: template.1 version: null versions: null paging: 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 previous: >- https://api.mailgun.net/v3/{domain}/templates?page=prev&p=template.0&limit=10 first: https://api.mailgun.net/v3/{domain}/templates?limit=10 security: - basicAuth: [] post: tags: - 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: httpapi.(*TemplateAPIControler).Post-fm-4 parameters: - name: domainId 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-domainId-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 version: tag: tag template: template content engine: handlebars 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 security: - basicAuth: [] delete: tags: - Templates summary: Delete all templates description: Delete all templates and their versions for the domain. operationId: httpapi.(*TemplateAPIControler).DeleteAll-fm-15 parameters: - name: domainId 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 security: - basicAuth: [] /v3/{domainId}/templates/{templateId}/versions: get: tags: - Templates summary: Get all template versions description: Returns a paginated list of template versions. operationId: httpapi.(*TemplateAPIControler).GetVersionsPage-fm-8 parameters: - name: domainId in: path description: Domain name to fetch the templates for. required: true schema: type: string - name: templateId 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`. required: true schema: type: string - name: limit in: query description: Number of templates to retrieve. Default and max limit is 100. required: true schema: type: integer - name: p in: query description: Pivot used to retrieve the next page of templates. required: true 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: paging: previous: >- https://api.mailgun.net/v3/{domain}/templates/z4ujt7CiEeik0RJbspqxaQ/versions?page=prev&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 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 versions: - active: false comment: version comment createdAt: Sat, 12 Nov 1955 06:38:00 UTC engine: handlebars headers: {} id: 71bd07b8-fe81-4199-8fcf-67c956ccdc34 mjml: '' tag: v0 template: '' - active: true comment: version comment createdAt: Sat, 12 Nov 1955 06:38:00 UTC engine: handlebars headers: {} id: d4a36e91-1b5f-44e0-bf5a-3542ea712b62 mjml: '' tag: v1 template: '' - active: true comment: version comment createdAt: Sat, 12 Nov 1955 06:38:00 UTC engine: handlebars headers: {} id: d4a36e91-1b5f-44e0-bf5a-3542ea712b62 mjml: '' tag: v2 template: '' security: - basicAuth: [] post: tags: - 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: httpapi.(*TemplateAPIControler).PostVersion-fm-5 parameters: - name: domainId in: path description: Domain name the template is associated with. required: true schema: type: string - name: templateId 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-domainId-templates-templateId-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 version: active: true id: 3efd2b85-0f41-4a1d-9898-05d7e7459c4a headers: From: from@header.tld Reply-To: reply-to@header.tld Subject: Subject Value tag: tag template: template content engine: handlebars createdAt: Sat, 12 Nov 1955 06:38:00 UTC comment: Version comment security: - basicAuth: [] /v3/{domainId}/templates/{templateId}: get: tags: - 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. operationId: httpapi.(*TemplateAPIControler).Get-fm-6 parameters: - name: domainId in: path description: Domain name the template is stored under. required: true schema: type: string - name: templateId 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: createdAt: Sat, 12 Nov 1955 06:38:00 UTC createdBy: user-supplied-value id: 46565d87-68b6-4edb-8b3c-34554af4bb77 version: comment: Version comment active: true id: 3efd2b85-0f41-4a1d-9898-05d7e7459c4a headers: Subject: Subject Value From: from@header.tld Reply-To: reply-to@header.tld tag: tag template: template content engine: handlebars createdAt: Sat, 12 Nov 1955 06:38:00 UTC name: template_name description: This is the description of the template security: - basicAuth: [] put: tags: - Templates summary: Update template description: Update the description of a template. operationId: httpapi.(*TemplateAPIControler).Put-fm-12 parameters: - name: domainId in: path description: Domain name the template is associated with. required: true schema: type: string - name: templateId in: path description: The template name. required: true schema: type: string requestBody: content: multipart/form-data: schema: $ref: >- #/components/schemas/PUT-v3-domainId-templates-templateId-multipart-form-data-RequestBody required: true responses: '200': description: A 200 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTempateOrVersionResponse examples: Example: value: message: template has been updated template: name: template_name security: - basicAuth: [] delete: tags: - Templates summary: Delete a template description: >- Delete the template specified in the url. NOTE: This method deletes all versions of the specified template. operationId: httpapi.(*TemplateAPIControler).Delete-fm-13 parameters: - name: domainId in: path description: Domain name the template is associated with. required: true schema: type: string - name: templateId 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-updateOrDeleteTempateOrVersionResponse examples: Example: value: template: name: template_name message: template has been deleted security: - basicAuth: [] /v3/{domainId}/templates/{templateId}/versions/{versionId}: get: tags: - Templates summary: Get a version description: >- Retrieve the information and content of the specified version of a template. operationId: httpapi.(*TemplateAPIControler).GetVersion-fm-7 parameters: - name: domainId in: path description: Domain name the template is stored under. required: true schema: type: string - name: templateId in: path description: template name the version is for. required: true schema: type: string - name: versionId 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: id: 46565d87-68b6-4edb-8b3c-34554af4bb77 version: headers: From: from@header.tld Reply-To: reply-to@header.tld Subject: Subject Value tag: tag template: template content engine: handlebars createdAt: Sat, 12 Nov 1955 06:38:00 UTC comment: Version comment active: true id: 3efd2b85-0f41-4a1d-9898-05d7e7459c4a name: template_name description: This is the description of the template createdAt: Sat, 12 Nov 1955 06:38:00 UTC createdBy: user-supplied-value security: - basicAuth: [] put: tags: - 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: httpapi.(*TemplateAPIControler).PutVersion-fm-11 parameters: - name: domainId in: path description: Domain name the template is associated with. required: true schema: type: string - name: templateId in: path description: template name the version is stored under. required: true schema: type: string - name: versionId 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-domainId-templates-templateId-versions-versionId-multipart-form-data-RequestBody required: true responses: '200': description: A 200 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTempateOrVersionResponse examples: Example: value: template: name: template_name version: tag: tag message: version has been updated security: - basicAuth: [] delete: tags: - Templates summary: Delete a version description: Delete a specific template version. operationId: httpapi.(*TemplateAPIControler).DeleteVersion-fm-14 parameters: - name: domainId in: path description: Domain name the template is associated with. required: true schema: type: string - name: templateId in: path description: template name the version is stored under. required: true schema: type: string - name: versionId 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-updateOrDeleteTempateOrVersionResponse examples: Example: value: message: version has been deleted template: name: template_name version: tag: tag security: - basicAuth: [] /v3/{domainId}/templates/{templateId}/versions/{versionId}/copy/{versionIdTo}: put: tags: - Templates summary: Copy a version description: Copies an existing version into a new version of a different tag name. operationId: httpapi.(*TemplateAPIControler).VersionCopy-fm-10 parameters: - name: domainId in: path description: Domain name the template is associated with. required: true schema: type: string - name: templateId in: path description: template name the version is stored under. required: true schema: type: string - name: versionId in: path description: Tag of the version to copy. required: true schema: type: string - name: versionIdTo in: path description: Version tag to copy version to. Version cannot already exist. required: true schema: type: string - name: comment in: query description: Comment to be used for the new version. required: true schema: type: string responses: '200': description: A 200 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTempateOrVersionResponse examples: Example: value: message: version has been deleted template: name: template_name version: tag: tag 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 status: open '404': description: A 404 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError 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 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 only enabled or disabled subaccounts 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 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 status: open '400': description: Error response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError 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-SubAccountsGenericSuccess examples: Example: value: message: Subaccount successfully deleted '400': description: Bad request content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError examples: Example: value: message: Bad request '403': description: Forbidden content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError 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 status: disabled '400': description: Subaccount is already disabled content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError examples: Example: value: message: subaccount is already disabled '404': description: Not found content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError 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 status: open '400': description: Cannot enable due to limit reached content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError 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-GenericError examples: Example: value: message: Not Found 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-GenericError 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-CustomMessageLimitGenericSuccess examples: Example: value: success: true '400': description: Error response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError 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-CustomMessageLimitGenericSuccess examples: Example: value: success: true '400': description: Error response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError 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-CustomMessageLimitGenericSuccess examples: Example: value: success: true '400': description: Error response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError 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 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 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-GenericError examples: Example: value: message: No valid updates provided '404': description: Not found content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-accounts-api-GenericError examples: Example: value: message: Not Found security: - basicAuth: [] /v1/keys: get: tags: - Keys summary: List Mailgun API keys description: List Mailgun API keys operationId: api.(*KeysAPI).ListKeys-fm-6 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 responses: '200': description: A 200 response content: application/json: schema: $ref: '#/components/schemas/github.com-mailgun-cerberus-keys-KeysResp' examples: Example: value: items: - created_at: '2006-01-02T15:04:05' description: api key id: e2153fd0-e0277777 kind: user requestor: janedoe@example.com role: admin updated_at: '2006-01-02T15:04:05' user_name: Jane Doe domain_name: 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: >- 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: api.(*KeysAPI).CreateKey-fm-7 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: key: description: api key kind: domain role: sending created_at: '2006-01-02T15:04:05' updated_at: '2006-01-02T15:04:05' domain_name: example.com id: f2153fd0-f1277777 user_name: null requestor: null message: great success '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: api.(*KeysAPI).DeleteKey-fm-8 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: api.(*KeysAPI).RegeneratePublicKey-fm-9 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: api.(*CredsAPI).ListCreds-fm-12 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: - created_at: Wed, 08 Mar 2023 23:34:57 +0000 login: someone@example.com mailbox: someone@example.com 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: api.(*CredsAPI).CreateCreds-fm-13 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: api.(*CredsAPI).DeleteDomainCreds-fm-16 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: api.(*CredsAPI).UpdateCreds-fm-14 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: api.(*CredsAPI).DeleteCreds-fm-17 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: [] /v3/{domain_name}/mailboxes/{spec}: put: tags: - Credentials summary: Update Mailgun SMTP credentials description: Update Mailgun SMTP credentials for a given domain and SMTP user operationId: api.(*CredsAPI).UpdateCreds-fm-15 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-domain_name-mailboxes-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: [] /v2/ip_whitelist: get: tags: - IP Allowlist summary: List Mailgun account IP allowlist entries description: List Mailgun account IP allowlist entries operationId: api.(*WhitelistAPI).ListWhitelistV2-fm-21 responses: '200': description: A 200 response content: application/json: schema: $ref: >- #/components/schemas/github.com-mailgun-cerberus-whitelist-V2WhitelistResp examples: Example: value: addresses: - description: OnPrem Server ip_address: 10.11.11.111 '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: api.(*WhitelistAPI).UpdateWhitelistV2-fm-23 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: - description: OnPrem Server 1 ip_address: 10.11.11.111 '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: api.(*WhitelistAPI).AddWhitelistV2-fm-22 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: - description: OnPrem Server ip_address: 10.11.11.111 '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: api.(*WhitelistAPI).DeleteWhitelistV2-fm-24 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: [] /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 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' 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 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' 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 api key of 'user' 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' 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 message: type: string required: - id - message github.com-mailgun-influx-httpapi-GetMessageResponseNotFound: type: object properties: message: type: string required: - message string: type: string POST-v3-domain_name-messages-multipart-form-data-RequestBody: type: object properties: from: type: string description: Email address for `From` header to: type: array items: type: string description: >- Email address of the recipient(s). Example: `"Bob "`. You can use commas to separate multiple recipients cc: type: array items: type: string description: Same as `To` but for `Cc` bcc: type: array items: type: string description: Same as `To` but for `Bcc` subject: type: string description: Message subject 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 template API to use to render the email body. See **Templates** for more information t:version: type: string description: >- Render a specific version of the given template instead of the latest version. `o:template` option must also be provided. t:text: type: string enum: - 'yes' description: Render template in case of template sending 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/#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/#tagging) for more information o:dkim: type: string enum: - 'yes' - 'no' - 'true' - 'false' description: Enables/disables DKIM signatures on a per-message basis 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/user-manual/get-started/#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. 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** 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** 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. See [Sending in Test Mode](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/#sending-in-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). Has higher priority than domain-level 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: >- Requires the message only be sent over a TLS connection, see [TLS Sending Connection Settings](https://documentation.mailgun.com/docs/mailgun/user-manual/tls-sending/). If a TLS connection can not be established, Mailgun will not deliver the message. If set to `false` or `no`, Mailgun will still try and upgrade the connection, but if Mailgun cannot, the message will be delivered over a plaintext SMTP connection. The default is `false` 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: >- If you send long emails that experience truncation or other rendering issues at the recipient, you can ensure opens are being tracked accurately with placement of the tracking pixel at the top of your emails 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 h:X-My-Header: type: string description: >- h: prefix followed by a Header/Value pair. For example: h:X-Mailgun-Sending-Ip-Pool=xx.xx.xxx.x. v:my-var: type: string description: >- `v:` prefix followed by an arbitrary name allows to attach a custom JSON data to the message. See **Attaching Data to Messages** for more information recipient-variables: type: string description: >- A valid JSON-encoded dictionary, where key is a plain recipient address and value is a dictionary with variables that can be referenced in the message body. See **Batch Sending** for more information required: - from - to - subject - html 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). Example: `"Bob "`. You can use commas to separate multiple recipients 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** for more information t:version: type: string description: >- Render a specific version of the given template instead of the latest version. `o:template` option must also be provided. t:text: type: string enum: - 'yes' description: >- Render template in the text part of the message in case of template sending 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** for more information o:tag: type: array items: type: string description: Tag string. See **Tagging** for more information o:dkim: type: string enum: - 'yes' - 'no' - 'true' - 'false' description: Enables/disables DKIM signatures on a per-message basis 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 singing 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://mailgun-docs.redoc.ly/docs/mailgun/api-reference/intro/#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. 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** 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** 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. See [Sending in Test Mode](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/#sending-in-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). Has higher priority than domain-level 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: >- Requires the message only be sent over a TLS connection, see [TLS Sending Connection Settings](https://documentation.mailgun.com/docs/mailgun/user-manual/tls-sending/). If a TLS connection can not be established, Mailgun will not deliver the message. If set to `false` or `no`, Mailgun will still try and upgrade the connection, but if Mailgun cannot, the message will be delivered over a plaintext SMTP connection. The default is `false` 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: >- If you send long emails that experience truncation or other rendering issues at the recipient, you can ensure opens are being tracked accurately with placement of the tracking pixel at the top of your emails 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 h:X-My-Header: type: string description: >- h: prefix followed by a Header/Value pair. For example: h:X-Mailgun-Sending-Ip-Pool=xx.xx.xxx.x. v:my-var: type: string description: >- `v:` prefix followed by an arbitrary name allows to attach a custom JSON data to the message. See **Attaching Data to Messages** for more information recipient-variables: type: string description: >- A valid JSON-encoded dictionary, where key is a plain recipient address and value is a dictionary with variables that can be referenced in the message body. See **Batch Sending** for more information required: - to - message additionalProperties: true github.com-mailgun-influx-httpapi-GetMessageResponseBasicExample: type: object properties: Content-Transfer-Encoding: type: string Content-Type: type: string From: type: string Message-Id: type: string Mime-Version: type: string Subject: type: string To: type: string X-Mailgun-Tag: type: string sender: type: string recipients: type: string from: type: string subject: type: string body-html: type: string body-plain: type: string stripped-html: type: string stripped-text: type: string stripped-signature: type: string message-headers: type: array items: type: array items: type: string X-Mailgun-Template-Name: type: string X-Mailgun-Template-Variables: type: string required: - Content-Transfer-Encoding - Content-Type - From - Message-Id - Mime-Version - Subject - To - X-Mailgun-Tag - sender - recipients - from - subject - 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 required: - message github.com-mailgun-domains-httpapi-CreateDomainResp: type: object properties: message: type: string domain: type: object properties: created_at: type: string id: type: string is_disabled: type: boolean name: type: string require_tls: type: boolean skip_verification: type: boolean smtp_login: type: string smtp_password: type: string spam_action: type: string state: type: string type: type: string tracking_host: type: string use_automatic_sender_security: type: boolean web_prefix: type: string web_scheme: type: string wildcard: type: boolean disabled: type: object properties: code: type: string note: type: string permanently: type: boolean reason: type: string until: type: string required: - code - note - permanently - reason 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 receiving_dns_records: type: array items: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value sending_dns_records: type: array items: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value required: - message - domain - receiving_dns_records - sending_dns_records github.com-mailgun-scaffold-httpapi-GenericResponse: type: object properties: message: type: string required: - message POST-v4-domains-multipart-form-data-RequestBody: type: object properties: 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, a subdomain of the domain 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` https://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: >- Determines whether the domain will accept email for sub-domains when sending messages. Default to 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. spam_action: type: string description: >- Disabled, block or tag. Default to disabled. If disabled, no spam filtering will occur for inbound messages. If block, inbound spam messages will not be delivered. If tag, inbound messages will be tagged with a spam header. See Spam Filter. 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. required: - name github.com-mailgun-domains-httpapi-ListDomainResponse: type: object properties: total_count: type: integer format: int32 items: type: array items: type: object properties: created_at: type: string id: type: string is_disabled: type: boolean name: type: string require_tls: type: boolean skip_verification: type: boolean smtp_login: type: string smtp_password: type: string spam_action: type: string state: type: string type: type: string tracking_host: type: string use_automatic_sender_security: type: boolean web_prefix: type: string web_scheme: type: string wildcard: type: boolean disabled: type: object properties: code: type: string note: type: string permanently: type: boolean reason: type: string until: type: string required: - code - note - permanently - reason 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 required: - total_count - items github.com-mailgun-domains-httpapi-FindDomainByNameResp: type: object properties: domain: type: object properties: created_at: type: string id: type: string is_disabled: type: boolean name: type: string require_tls: type: boolean skip_verification: type: boolean smtp_login: type: string smtp_password: type: string spam_action: type: string state: type: string type: type: string tracking_host: type: string use_automatic_sender_security: type: boolean web_prefix: type: string web_scheme: type: string wildcard: type: boolean disabled: type: object properties: code: type: string note: type: string permanently: type: boolean reason: type: string until: type: string required: - code - note - permanently - reason 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 receiving_dns_records: type: array items: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value sending_dns_records: type: array items: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value required: - domain github.com-mailgun-domains-httpapi-VerifyDomainResponse: type: object properties: message: type: string domain: type: object properties: created_at: type: string id: type: string is_disabled: type: boolean name: type: string require_tls: type: boolean skip_verification: type: boolean smtp_login: type: string smtp_password: type: string spam_action: type: string state: type: string type: type: string tracking_host: type: string use_automatic_sender_security: type: boolean web_prefix: type: string web_scheme: type: string wildcard: type: boolean disabled: type: object properties: code: type: string note: type: string permanently: type: boolean reason: type: string until: type: string required: - code - note - permanently - reason 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 sending_dns_records: type: array items: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value receiving_dns_records: type: array items: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value required: - message - domain - sending_dns_records - receiving_dns_records github.com-mailgun-domains-httpapi-GetDomainConnectionResp: type: object properties: require_tls: type: boolean skip_verification: type: boolean required: - require_tls - skip_verification github.com-mailgun-domains-httpapi-UpdateDomainConnectionResp: type: object properties: message: type: string require_tls: type: boolean skip_verification: type: boolean required: - message - require_tls - skip_verification PUT-v3-domains-name-connection-multipart-form-data-RequestBody: type: object properties: 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. If 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. The default value is false. skip_verification: type: boolean description: >- If set to true, the certificate and hostname will not be verified when tryingto establish a TLS connection and Mailgun will accept any certificate during delivery of a message. If set to false, Mailgun will verify the certificate and hostname. If either one can not be verified, a TLS connection will not be established. The default value is false. github.com-mailgun-domains-httpapi-WebhookResponse: type: object properties: urls: type: array items: type: string url: type: string github.com-mailgun-domains-httpapi-CreateDomainWebhookResp: type: object properties: message: type: string webhook: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-WebhookResponse required: - message - webhook github.com-mailgun-scaffold-httpapi-GenericAPIError: type: object properties: Reason: type: string required: - Reason POST-v3-domains-domain-webhooks-multipart-form-data-RequestBody: type: object properties: 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. id: type: string description: >- Webhook type to create. Valid types are accepted, clicked, opened, unsubscribed, delivered, permanent_fail, temporary_fail, complained required: - url - id 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: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-WebhookResponse required: - webhook github.com-mailgun-domains-httpapi-WebhooksResponse: type: object properties: accepted: type: object properties: urls: type: array items: type: string required: - urls clicked: type: object properties: urls: type: array items: type: string required: - urls opened: type: object properties: urls: type: array items: type: string required: - urls unsubscribed: type: object properties: urls: type: array items: type: string required: - urls delivered: type: object properties: urls: type: array items: type: string required: - urls permanent_fail: type: object properties: urls: type: array items: type: string required: - urls temporary_fail: type: object properties: urls: type: array items: type: string required: - urls complained: type: object properties: urls: type: array items: type: string required: - urls github.com-mailgun-domains-httpapi-GetAllDomainWebhooksResp: type: object properties: webhooks: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-WebhooksResponse required: - webhooks github.com-mailgun-domains-httpapi-openSettings: type: object properties: active: type: boolean place_at_the_top: type: boolean required: - active - place_at_the_top github.com-mailgun-domains-httpapi-clickSettings: type: object properties: active: type: boolean required: - active github.com-mailgun-domains-httpapi-unsubscribeSettings: type: object properties: active: type: boolean html_footer: type: string text_footer: type: string required: - active - html_footer - text_footer github.com-mailgun-domains-httpapi-trackingSettings: type: object properties: open: $ref: '#/components/schemas/github.com-mailgun-domains-httpapi-openSettings' click: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-clickSettings unsubscribe: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-unsubscribeSettings web_scheme: type: string 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 click: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-clickSettings 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 open: $ref: '#/components/schemas/github.com-mailgun-domains-httpapi-openSettings' 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 unsubscribe: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-unsubscribeSettings 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: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value 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-domains-httpapi-DomainKeyListResponse: type: object properties: items: type: array items: type: object properties: signing_domain: type: string selector: type: string dns_record: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value required: - signing_domain - selector paging: type: object properties: previous: type: string first: type: string next: type: string last: type: string required: - previous - first - next - last 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-ReassignDkimAuthorityResp: type: object properties: message: type: string sending_dns_records: type: array items: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value 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. 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. 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-ExceededQueueQuotaDisabledJSON: type: object properties: until: type: string reason: type: string required: - until - reason github.com-mailgun-domains-httpapi-ExceededQueueQuotaJSON: type: object properties: is_disabled: type: boolean disabled: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-ExceededQueueQuotaDisabledJSON required: - is_disabled github.com-mailgun-domains-httpapi-GetDomainSendingQueuesResp: type: object properties: regular: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-ExceededQueueQuotaJSON scheduled: $ref: >- #/components/schemas/github.com-mailgun-domains-httpapi-ExceededQueueQuotaJSON required: - regular - scheduled PUT-v3-domains-name-message_ttl-multipart-form-data-RequestBody: type: object properties: message_ttl: type: integer description: Duration of the message retrieval TTL in seconds. PUT-v3-domains-name-mailfrom_host-multipart-form-data-RequestBody: type: object properties: mailfrom_host: type: string description: The hostname to update to. Must be in lower case github.com-mailgun-domains-httpapi-UpdateDomainResp: type: object properties: message: type: string domain: type: object properties: created_at: type: string id: type: string is_disabled: type: boolean name: type: string require_tls: type: boolean skip_verification: type: boolean smtp_login: type: string smtp_password: type: string spam_action: type: string state: type: string type: type: string tracking_host: type: string use_automatic_sender_security: type: boolean web_prefix: type: string web_scheme: type: string wildcard: type: boolean disabled: type: object properties: code: type: string note: type: string permanently: type: boolean reason: type: string until: type: string required: - code - note - permanently - reason 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 receiving_dns_records: type: array items: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value sending_dns_records: type: array items: type: object properties: is_active: type: boolean cached: type: array items: type: string name: type: string priority: type: string record_type: type: string valid: type: string value: type: string required: - is_active - cached - record_type - valid - value required: - message - domain PUT-v4-domains-name-multipart-form-data-RequestBody: type: object properties: mailfrom_host: type: string description: The hostname to update to. Must be in lower case message_ttl: type: integer description: Duration of the message retrieval TTL in seconds. 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: >- Web prefix to be used for tracking. Must be a valid atom. Nothing will be updated if omitted wildcard: type: boolean description: Updates the domain's wildcard status with the given boolean PUT-v3-domains-name-web_prefix-multipart-form-data-RequestBody: type: object properties: web_prefix: type: string description: >- Web prefix to be used for tracking. Must be a valid atom. Nothing will be updated if omitted domain: type: object properties: records: type: array items: type: object properties: comment: type: string name: type: string type: type: string identifier: type: string value: type: string required: - name - type - identifier - value - comment state: type: string active_selector: type: string rotation_enabled: type: string rotation_interval: type: string account_id: type: string name: type: string sid: type: string id: type: string required: - id - account_id - sid - name - state - rotation_enabled - rotation_interval DomainResponse: type: object properties: domain: $ref: '#/components/schemas/domain' required: - domain GenericAPIError: type: object properties: Reason: type: string required: - Reason NotFoundError: type: object properties: Description: type: string required: - Description PUT-v1-dkim_management-domains-name-rotation-multipart-form-data-RequestBody: type: object properties: rotation_interval: type: string description: The interval at which to rotate keys. Example, '5d' for five days rotation_enabled: type: boolean description: If true, enables DKIM Auto-Rotation. If false, disables it required: - rotation_enabled GenericResponse: type: object properties: message: type: string required: - message ListSubaccountDIPPsResponse: type: object properties: total_count: type: integer format: int32 items: type: array items: type: object properties: subaccount_id: type: string pool_id: type: string required: - pool_id - subaccount_id required: - items - total_count StartSagaResponse: type: object properties: reference_id: type: string message: type: string required: - message - reference_id domainsResponse: type: object properties: total_count: type: integer format: int32 items: type: array items: type: object properties: domain: type: string ips: type: array items: type: string required: - ips - domain 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 POST-v3-ip_pools-multipart-form-data-RequestBody: type: object properties: name: type: string description: Short name of the DIPP description: type: string description: Description of the DIPP ip: type: string description: IP address to add to the DIPP (may be specified multiple times) required: - description - name PATCH-v3-ip_pools-pool_id-multipart-form-data-RequestBody: type: object properties: unlink_domain: type: string description: >- The ID of the domain to unlink from the DIPP (may be specified multiple times) 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) addMultipleIPsRequestBody: type: object properties: ips: type: array items: type: string description: IPs to add to the DIPP required: - ips github.com-mailgun-terminator-httpapi-StatusResponse: type: object properties: certificate: type: string error: type: string status: type: object required: - status - error github.com-mailgun-scaffold-httpapi-NotFoundError: type: object properties: Description: type: string required: - Description github.com-mailgun-terminator-httpapi-GenerateResponse: type: object properties: message: type: string location: type: string required: - message - location github.com-mailgun-scaffold-httpapi-ConflictError: type: object properties: Description: type: string required: - Description 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: Hard bounces failure permanent: Soft bounces failure github.com-mailgun-scaffold-httpapi-paging-PagingResponse: type: object properties: previous: type: string first: type: string next: type: string last: type: string required: - previous - first - next - last github.com-mailgun-scout-api-TagListResponse: type: object properties: paging: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse items: type: array items: type: object properties: last-seen: type: string format: date-time tag: type: string first-seen: type: string format: date-time description: type: string required: - tag - description required: - items - paging github.com-mailgun-scout-model-tags-TagItem: type: object properties: last-seen: type: string format: date-time description: type: string tag: type: string first-seen: type: string format: date-time required: - tag - description github.com-mailgun-scout-api-TagAggregateResponse: type: object properties: device: type: object additionalProperties: type: object additionalProperties: type: integer format: int32 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 github.com-mailgun-scout-api-StatsResponse: type: object properties: stats: type: array items: type: object properties: delivered: type: object properties: optimized: type: integer format: int32 total: type: integer format: int32 smtp: type: integer format: int32 http: type: integer format: int32 required: - smtp - http - optimized - total time: type: string accepted: type: object properties: outgoing: type: integer format: int32 incoming: type: integer format: int32 total: type: integer format: int32 required: - incoming - outgoing - total stored: type: object properties: total: type: integer format: int32 required: - total failed: type: object properties: temporary: type: object properties: total: type: integer format: int32 espblock: type: integer format: int32 required: - espblock - total permanent: type: object properties: suppress-complaint: type: integer format: int32 suppress-unsubscribe: type: integer format: int32 suppress-bounce: type: integer format: int32 bounce: type: integer format: int32 delayed-bounce: type: integer format: int32 webhook: type: integer format: int32 total: type: integer format: int32 optimized: type: integer format: int32 required: - suppress-bounce - suppress-unsubscribe - suppress-complaint - bounce - delayed-bounce - webhook - optimized - total required: - temporary - permanent unsubscribed: type: object properties: total: type: integer format: int32 required: - total opened: type: object properties: unique: type: integer format: int32 total: type: integer format: int32 required: - total campaign: type: object properties: total: type: integer format: int32 required: - total clicked: type: object properties: unique: type: integer format: int32 total: type: integer format: int32 required: - total complained: type: object properties: total: type: integer format: int32 required: - total seed_test: type: object properties: total: type: integer format: int32 required: - total email_validation: type: object properties: mailgun: type: integer format: int32 total: type: integer format: int32 public: type: integer format: int32 single: type: integer format: int32 valid: type: integer format: int32 bulk: type: integer format: int32 list: type: integer format: int32 mailjet: type: integer format: int32 required: - total - public - valid - single - bulk - list - mailgun - mailjet link_validation_failed: type: object properties: total: type: integer format: int32 required: - total link_validation: type: object properties: total: type: integer format: int32 required: - total email_preview: type: object properties: total: type: integer format: int32 required: - total email_preview_failed: type: object properties: total: type: integer format: int32 required: - total required: - time description: type: string tag: type: string end: type: string type: type: object properties: key: type: string type: type: string required: - type - key resolution: type: string start: type: string 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: limit: type: integer format: int32 id: type: string 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: limit: type: integer format: int64 description: The maximum number of items returned in the response. 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. sort: type: string description: >- Colon-separated value indicating column name and sort direction e.g. 'domain:asc'. 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-internal-api-RegularMetrics: type: object properties: accepted_count: type: integer format: int64 accepted_incoming_count: type: integer format: int64 accepted_outgoing_count: type: integer format: int64 delivered_smtp_count: type: integer format: int64 delivered_count: type: integer format: int64 delivered_optimized_count: type: integer format: int64 delivered_http_count: type: integer format: int64 stored_count: type: integer format: int64 processed_count: type: integer format: int64 clicked_count: type: integer format: int64 unique_opened_count: type: integer format: int64 opened_count: type: integer format: int64 sent_count: type: integer format: int64 unique_clicked_count: type: integer format: int64 unsubscribed_count: type: integer format: int64 complained_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 webhook_count: type: integer format: int64 failed_count: type: integer format: int64 rate_limit_count: type: integer format: int64 permanent_failed_optimized_count: type: integer format: int64 bounced_count: type: integer format: int64 hard_bounces_count: type: integer format: int64 permanent_failed_old_count: type: integer format: int64 suppressed_unsubscribed_count: type: integer format: int64 suppressed_bounces_count: type: integer format: int64 soft_bounces_count: type: integer format: int64 delayed_first_attempt_count: type: integer format: int64 delivered_first_attempt_count: type: integer format: int64 delivered_subsequent_count: type: integer format: int64 unique_opened_rate: type: string unsubscribed_rate: type: string complained_rate: type: string delayed_bounce_count: type: integer format: int64 unique_clicked_rate: type: string bounce_rate: type: string delivered_two_plus_attempts_count: type: integer format: int64 fail_rate: type: string temporary_fail_rate: type: string suppressed_complaints_count: type: integer format: int64 permanent_fail_rate: type: string delayed_rate: type: string delivered_rate: type: string clicked_rate: type: string opened_rate: type: string github.com-mailgun-analytics-internal-api-RegularAggregates: type: object properties: metrics: type: object properties: accepted_outgoing_count: type: integer format: int64 delivered_smtp_count: type: integer format: int64 accepted_count: type: integer format: int64 delivered_http_count: type: integer format: int64 accepted_incoming_count: type: integer format: int64 delivered_optimized_count: type: integer format: int64 stored_count: type: integer format: int64 delivered_count: type: integer format: int64 processed_count: type: integer format: int64 sent_count: type: integer format: int64 opened_count: type: integer format: int64 unique_opened_count: type: integer format: int64 clicked_count: type: integer format: int64 unique_clicked_count: type: integer format: int64 complained_count: type: integer format: int64 permanent_failed_count: type: integer format: int64 failed_count: type: integer format: int64 rate_limit_count: type: integer format: int64 unsubscribed_count: type: integer format: int64 temporary_failed_count: type: integer format: int64 permanent_failed_optimized_count: type: integer format: int64 bounced_count: type: integer format: int64 esp_block_count: type: integer format: int64 webhook_count: type: integer format: int64 delayed_bounce_count: type: integer format: int64 soft_bounces_count: type: integer format: int64 permanent_failed_old_count: type: integer format: int64 suppressed_bounces_count: type: integer format: int64 delivered_subsequent_count: type: integer format: int64 delivered_rate: type: string delayed_first_attempt_count: type: integer format: int64 unsubscribed_rate: type: string delivered_first_attempt_count: type: integer format: int64 opened_rate: type: string suppressed_complaints_count: type: integer format: int64 delivered_two_plus_attempts_count: type: integer format: int64 hard_bounces_count: type: integer format: int64 suppressed_unsubscribed_count: type: integer format: int64 unique_opened_rate: type: string fail_rate: type: string complained_rate: type: string clicked_rate: type: string unique_clicked_rate: type: string bounce_rate: type: string delayed_rate: type: string permanent_fail_rate: type: string temporary_fail_rate: type: string required: - metrics github.com-mailgun-analytics-internal-api-RegularMetricsResponse: type: object properties: resolution: type: string start: type: string aggregates: $ref: >- #/components/schemas/github.com-mailgun-analytics-internal-api-RegularAggregates dimensions: type: array items: type: string items: type: array items: type: object properties: dimensions: type: array items: type: object properties: value: type: string description: The dimension value display_value: type: string description: The dimension value in displayable form dimension: type: string description: The dimension required: - dimension - value - display_value metrics: $ref: >- #/components/schemas/github.com-mailgun-analytics-internal-api-RegularMetrics pagination: $ref: >- #/components/schemas/github.com-mailgun-analytics-client-golang-Pagination end: type: string duration: type: string required: - items github.com-mailgun-analytics-client-golang-Query: type: object properties: 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 metrics: type: array items: type: string description: >- Name of the metrics to receive the stats for such as 'processed_count'. include_aggregates: type: boolean description: Include top-level aggregate metrics. 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 dimensions: type: array items: type: string description: Attributes of the metric data such as 'subaccount'. 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. filter: type: object properties: AND: type: array items: type: object properties: attribute: type: string comparator: type: string values: type: array items: type: object properties: value: type: string label: type: string required: - label - value required: - attribute - comparator required: - AND description: Filters to apply to the query. resolution: type: string description: A resolution in the format of 'day' 'hour' 'month'. Default is day. include_subaccounts: type: boolean description: Include stats from all subaccounts. required: - start - end - resolution - duration - dimensions - metrics - filter - include_subaccounts - include_aggregates github.com-mailgun-analytics-internal-api-UsageMetrics: type: object properties: email_validation_single_count: type: integer format: int64 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_list_count: type: integer format: int64 processed_count: type: integer format: int64 email_validation_bulk_count: type: integer format: int64 email_validation_mailjet_count: type: integer format: int64 email_preview_count: type: integer format: int64 email_validation_mailgun_count: type: integer format: int64 link_validation_count: type: integer format: int64 email_preview_failed_count: type: integer format: int64 link_validation_failed_count: type: integer format: int64 seed_test_count: type: integer format: int64 github.com-mailgun-analytics-internal-api-UsageAggregates: type: object properties: metrics: type: object properties: link_validation_failed_count: type: integer format: int64 email_validation_list_count: type: integer format: int64 email_preview_count: type: integer format: int64 email_validation_mailjet_count: type: integer format: int64 email_preview_failed_count: type: integer format: int64 link_validation_count: type: integer format: int64 email_validation_mailgun_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_count: type: integer format: int64 email_validation_public_count: type: integer format: int64 processed_count: type: integer format: int64 seed_test_count: type: integer format: int64 required: - metrics github.com-mailgun-analytics-internal-api-UsageMetricsResponse: type: object properties: aggregates: $ref: >- #/components/schemas/github.com-mailgun-analytics-internal-api-UsageAggregates pagination: type: object properties: total: type: integer format: int64 description: The total number of items in the query result set. 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. sort: type: string description: >- Colon-separated value indicating column name and sort direction e.g. 'domain:asc'. limit: type: integer format: int64 description: The maximum number of items returned in the response. required: - sort - skip - limit - total resolution: type: string items: type: array items: type: object properties: dimensions: type: array items: type: object properties: value: type: string description: The dimension value display_value: type: string description: The dimension value in displayable form dimension: type: string description: The dimension required: - dimension - value - display_value metrics: $ref: >- #/components/schemas/github.com-mailgun-analytics-internal-api-UsageMetrics dimensions: type: array items: type: string start: type: string end: type: string duration: type: string required: - items github.com-mailgun-timetools-RFC2822Time: type: object github.com-mailgun-blackbook-model-Whitelist: type: object properties: type: type: string value: type: string reason: type: string createdAt: $ref: '#/components/schemas/github.com-mailgun-timetools-RFC2822Time' required: - type - value - createdAt - reason github.com-mailgun-blackbook-api-getWhitelistPaginationResponse: type: object properties: items: type: array items: type: object properties: value: type: string type: type: string reason: type: string createdAt: $ref: '#/components/schemas/github.com-mailgun-timetools-RFC2822Time' required: - type - value - createdAt - reason paging: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse required: - items - paging github.com-mailgun-blackbook-api-insertWhitelistRecordResponse: type: object properties: type: type: string message: type: string value: type: string required: - message - type - value github.com-mailgun-scaffold-httpapi-MissingFieldError: type: object properties: Field: type: string required: - Field POST-v3-domainID-whitelists-application-form-data-RequestBody: type: object properties: domain: type: string description: Valid domain name if you would like whitelist entire domain name address: type: string description: >- Valid email address if you would like to whitelist email address (prior over 'domain' parameter) required: - address github.com-mailgun-blackbook-api-deleteWhitelistRecordResponse: type: object properties: message: type: string value: type: string required: - message - value POST-v3-domainID-unsubscribes-import-multipart-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 POST-v3-domainID-bounces-import-multipart-form-data-RequestBody: type: object properties: error: type: string description: 'Error description (optional, default: empty string)' address: type: string description: Valid email address code: type: string description: 'Error code (optional, default: 550)' created_at: type: string description: >- Timestamp of a bounce event in RFC2822 format (optional, default: current time) required: - address POST-v3-domainID-complaints-import-multipart-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 POST-v3-domainID-whitelists-import-multipart-form-data-RequestBody: type: object properties: address: type: string description: >- Valid email address if you would like to whitelist email address (prior over 'domain' parameter) domain: type: string description: Valid domain name if you would like whitelist entire domain name required: - address github.com-mailgun-blackbook-model-Bounce: type: object properties: error: type: string address: type: string created_at: type: object '-': type: string code: type: string required: - address - code - error - created_at - '-' github.com-mailgun-blackbook-api-getBouncesPaginationResponse: type: object properties: paging: type: object properties: last: type: string next: type: string first: type: string previous: type: string required: - previous - first - next - last items: type: array items: type: object properties: '-': type: string address: type: string created_at: type: object error: type: string code: type: string required: - address - code - error - created_at - '-' required: - items - paging github.com-mailgun-blackbook-api-BouncesList: type: array items: type: object properties: created_at: type: object address: type: string '-': type: string code: type: string error: type: string required: - address - code - error - created_at - '-' POST-v3-domainID-bounces-application-form-data-RequestBody: type: object properties: code: type: string description: 'Error code (optional, default: 550)' address: type: string description: Valid email address created_at: type: string description: >- Timestamp of a bounce event in RFC2822 format (optional, default: current time) error: type: string description: 'Error description (optional, default: empty string)' required: - address github.com-mailgun-blackbook-api-suppressionResponse: type: object properties: message: type: string address: type: string required: - message - address github.com-mailgun-blackbook-model-Unsubscribe: type: object properties: created_at: type: object address: type: string tags: type: array items: type: string required: - address - tags - created_at github.com-mailgun-blackbook-api-getUnsubscribesPaginationResponse: type: object properties: paging: type: object properties: previous: type: string next: type: string last: type: string first: type: string required: - previous - first - next - last items: type: array items: type: object properties: address: type: string tags: type: array items: type: string created_at: type: object required: - address - tags - created_at required: - items - paging github.com-mailgun-blackbook-api-UnsubscribesList: type: array items: type: object properties: created_at: type: object address: type: string tags: type: array items: type: string required: - address - tags - created_at 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: created_at: type: object address: type: string required: - address - created_at github.com-mailgun-blackbook-api-getComplaintsPaginationResponse: type: object properties: items: type: array items: type: object properties: address: type: string created_at: type: object required: - address - created_at paging: type: object properties: previous: type: string first: type: string next: type: string last: type: string required: - previous - first - next - last required: - items - paging github.com-mailgun-blackbook-api-ComplaintsList: type: array items: type: object properties: address: type: string created_at: type: object required: - address - created_at POST-v3-domainID-complaints-application-form-data-RequestBody: type: object properties: created_at: type: string description: >- Timestamp of a complaint event in RFC2822 format (optional, default: current time) address: type: string description: Valid email address required: - address RouteResponse: type: object title: RouteResponse properties: id: type: string priority: type: integer description: type: string expression: type: string actions: type: array items: type: string created_at: type: string 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: MailingListResponse properties: address: type: string name: type: string description: type: string access_level: type: string reply_preference: type: string created_at: type: string members_count: type: integer 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 name: type: string vars: type: object subscribed: type: boolean 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 next: type: string previous: type: string last: type: string 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-httpapi-createTemplateOrVersionResponse: type: object properties: template: type: object properties: name: type: string description: type: string createdAt: type: string createdBy: type: string version: type: object properties: engine: type: string template: type: string createdAt: type: string mjml: type: string active: type: boolean tag: type: string comment: type: string headers: type: object additionalProperties: type: string id: type: string required: - tag - engine - mjml - createdAt - comment - active - id id: type: string versions: type: array items: type: object required: - name - description - createdAt - createdBy - id message: type: string required: - message - template POST-v3-domainId-templates-multipart-form-data-RequestBody: type: object properties: createdBy: type: string description: >- Optional metadata field api user can indicate who created the template. name: type: string description: >- Name of the template being stored. Supports utf-8 characters and name will be down cased. 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. template: type: string description: Content of the template. description: type: string description: Description of the template being stored 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 dictionary of headers to be stored with the template. Where key is the header name and value is the header value. The header names `From`, `Subject`, and `Reply-To` are the only ones currently supported. These headers will be inserted into the mime at the time we attempt delivery. Headers 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` engine: type: string description: >- The template engine to be used when rendering the template. Supported value are handlebars and go (golang template). The default if parameter is not provided is handlebars. required: - name POST-v3-domainId-templates-templateId-versions-multipart-form-data-RequestBody: type: object properties: tag: type: string description: >- Tag of the version that is being created. Must be unique to the template. template: type: string description: Content of the template. engine: type: string description: >- The template engine to be used when rendering the template. Supported value are handlebars and go (golang template). The default if parameter is not provided is handlebars. 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 dictionary of headers to be stored with the template. Where key is the header name and value is the header value. The header names `From`, `Subject`, and `Reply-To` are the only ones currently supported. These headers will be inserted into the mime at the time we attempt delivery. Headers 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: type: object properties: version: type: object properties: template: type: string tag: type: string createdAt: type: string mjml: type: string engine: type: string comment: type: string id: type: string headers: type: object additionalProperties: type: string active: type: boolean required: - tag - engine - mjml - createdAt - comment - active - id createdBy: type: string id: type: string createdAt: type: string versions: type: array items: type: object name: type: string description: type: string required: - name - description - createdAt - createdBy - id required: - template github.com-mailgun-temple-httpapi-getVersionsPageResponse: type: object properties: template: type: object properties: description: type: string versions: type: array items: type: object id: type: string version: type: object properties: mjml: type: string template: type: string tag: type: string engine: type: string createdAt: type: string comment: type: string headers: type: object additionalProperties: type: string active: type: boolean id: type: string required: - tag - engine - mjml - createdAt - comment - active - id createdAt: type: string name: type: string createdBy: type: string required: - name - description - createdAt - createdBy - id paging: $ref: >- #/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse required: - template - paging github.com-mailgun-temple-httpapi-getPageResponse: type: object properties: items: type: array items: type: object paging: type: object properties: next: type: string last: type: string first: type: string previous: type: string required: - previous - first - next - last required: - items - paging github.com-mailgun-temple-httpapi-templateUpdate: type: object properties: version: type: object properties: tag: type: string required: - tag name: type: string required: - name github.com-mailgun-temple-httpapi-updateOrDeleteTempateOrVersionResponse: type: object properties: template: $ref: >- #/components/schemas/github.com-mailgun-temple-httpapi-templateUpdate message: type: string required: - message - template PUT-v3-domainId-templates-templateId-versions-versionId-multipart-form-data-RequestBody: type: object properties: engine: type: string description: >- The template engine to be used when rendering the template. Supported value are handlebars and go (golang 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 dictionary 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. template: type: string description: Content of the template. PUT-v3-domainId-templates-templateId-multipart-form-data-RequestBody: type: object properties: description: type: string description: Update description of the template being updated. 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-CustomMessageLimitGenericSuccess: type: object properties: success: type: boolean description: Indicates success of request 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 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-SubAccountsGenericSuccess: type: object properties: message: type: string description: Success message github.com-mailgun-accounts-api-GenericError: type: object properties: message: type: string description: Error message 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-cerberus-keys-KeysResp: type: object properties: items: type: array items: $ref: '#/components/schemas/github.com-mailgun-cerberus-keys-KeyInfoResp' total_count: type: integer format: int32 required: - total_count - items github.com-mailgun-cerberus-keys-KeyInfoResp: type: object properties: requestor: type: - string - 'null' expires_at: type: string created_at: type: string id: type: string secret: type: string updated_at: type: string kind: type: string domain_name: type: - string - 'null' description: type: string user_name: type: - string - 'null' role: type: string required: - id - description - kind - role - created_at - updated_at - domain_name - requestor - user_name github.com-mailgun-cerberus-keys-CreateKeyResp: type: object properties: message: type: string key: $ref: '#/components/schemas/github.com-mailgun-cerberus-keys-KeyInfoResp' required: - message - key POST-v1-keys-multipart-form-data-RequestBody: type: object properties: email: type: string description: >- API Key user's email address; should be provided for all keys of 'user' & 'web' kinds domain_name: type: string description: Web domain to associate with the key, for keys of 'domain' kind kind: type: string description: >- Type of api key ('domain', 'user', or 'web'). Defaults to 'user' if not provided. Note: web keys are not subject to IP whitelisting and have a default/maximum validity period of 1 day. expiration: type: integer description: Key lifetime in seconds, must be greater than 0 if set role: type: string description: >- Key role ('admin', 'basic' [use in place of analyst], 'sending' [use with keys of domain kind], 'support', or 'developer') user_id: type: string description: >- API Key user's string user ID; should be provided for all keys of 'user' & 'web' kinds user_name: type: string description: API Key user's name; should be provided for all keys of 'user' kind description: type: string description: Key description required: - role github.com-mailgun-cerberus-keys-PublicKeyResp: type: object properties: message: type: string key: type: string required: - key - message github.com-mailgun-cerberus-credentials-ListCredsResp: type: object properties: total_count: type: integer format: int32 items: type: array items: type: object properties: size_bytes: type: - string - 'null' mailbox: type: string login: type: string created_at: type: string required: - mailbox - login - created_at - size_bytes required: - items - total_count github.com-mailgun-cerberus-credentials-CreateCredsResp: type: object properties: credentials: type: object additionalProperties: type: string message: type: string note: type: string 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 PUT-v3-domain_name-mailboxes-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: count: type: integer format: int32 message: type: string required: - message - count github.com-mailgun-cerberus-credentials-DeleteCredsResp: type: object properties: message: type: string spec: type: string required: - message - spec github.com-mailgun-cerberus-whitelist-V2WhitelistResp: type: object properties: addresses: type: array items: type: object properties: ip_address: type: string description: type: string required: - ip_address - description required: - addresses POST-v2-ip_whitelist-multipart-form-data-RequestBody: type: object properties: description: type: string description: >- Description of the address to be added to the allowlist, defaults to empty string address: type: string description: Address to be added to the allowlist required: - address PUT-v2-ip_whitelist-multipart-form-data-RequestBody: type: object properties: description: type: string description: >- Description of the address to be updated in the allowlist, defaults to empty string address: type: string description: Address to be updated in the allowlist required: - address github.com-mailgun-users-api-UserListResponse: type: object properties: users: type: array items: $ref: '#/components/schemas/github.com-mailgun-users-api-UserResponse' 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: type: string description: the date and time at which 2-factor auth was activated 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: type: - string - 'null' description: Github ID, if part of Github Student Developer Pack account salesforce_user_id: type: - string - 'null' description: Salesforce ID, if part of Salesforce platform account 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: - Webhooks - name: Events tags: - Events - name: Tags tags: - Tags - name: Reporting tags: - Metrics - Stats - name: Suppressions tags: - Unsubscribe - Complaints - Bounces - Whitelist - name: Routes tags: - Routes - name: Mailing Lists tags: - Mailing Lists - name: Templates tags: - Templates - name: IP Pools tags: - IP Pools - name: IPs tags: - IPs - name: Subaccounts tags: - Subaccounts - name: Custom Message Limit tags: - Custom Message Limit - name: Keys tags: - Keys - name: Credentials tags: - Credentials - name: IP Allowlist tags: - IP Allowlist - name: Users tags: - Users