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'
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
get:
tags:
- Mailing Lists
summary: Get mailing lists
description: >-
A mailing list is a group of members (recipients) which itself has an
email address. This address becomes an ID for this mailing list.
operationId: get-v3-lists
parameters:
- name: limit
in: query
description: Set limit for the list length returned. Defaults to 100.
schema:
type: string
- name: skip
in: query
description: Skip the first n values in the list. Defaults to 0.
schema:
type: string
- name: address
in: query
description: Filter mailing lists matching a specific address
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
total_count:
type: integer
items:
type: array
items:
$ref: '#/components/schemas/MailingListResponse'
examples:
Example:
value:
total_count: 1
items:
- address: developers@mailgun.net
name: Developers
description: Describe the mailing list
access_level: readonly
reply_preference: list
created_at: Tue, 09 Aug 2011 20:50:27 -0000
members_count: 2
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
/v3/lists/{list_address}/members:
get:
tags:
- Mailing Lists
summary: Get mailing lists members
description: Lists members in a given mailing list
operationId: get-lists-string:list_address-members
parameters:
- name: address
in: query
description: A valid email address specification.
schema:
type: string
- name: subscribed
in: query
description: Filtering list on whether the member is subscribed or not.
schema:
type: boolean
- name: limit
in: query
description: Maximum number of records to return. Max is 100. Defaults to 100.
schema:
type: integer
- name: skip
in: query
schema:
type: integer
- name: list_address
in: path
description: The mailing list's address
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
total_count:
type: integer
items:
type: array
items:
$ref: '#/components/schemas/ListMemberResponse'
examples:
Example:
value:
total_count: 1
items:
- address: alice@example.com
name: Alice
vars:
gender: female
age: 27
subscribed: true
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
post:
tags:
- Mailing Lists
summary: Create a mailing list member
description: >-
Adds a new member to the mailing list. For adding many list members,
consider bulk upload endpoints "POST
/v3/lists/{list_address}/members.json" or "members.csv".
operationId: post-lists-string:list_address-members
parameters:
- name: list_address
in: path
description: The mailing list's address
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
address:
type: string
description: Valid email address specification.
name:
type: string
description: An optional member name.
vars:
type: object
description: JSON-encoded dictionary string with arbitrary parameters.
subscribed:
type: boolean
description: Set the member as subscribed or not. Defaults to true.
upsert:
type: boolean
description: >-
Set to True to update member if present, False to raise
error in case of a duplicate member. Defaults to false.
examples:
Example:
value:
address: alice@example.com
name: Alice
vars:
gender: female
age: 27
subscribed: true
upsert: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
member:
$ref: '#/components/schemas/ListMemberResponse'
message:
type: string
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'
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
/v3/lists/{list_address}/members.json:
post:
tags:
- Mailing Lists
summary: Bulk upload members to a mailing list (JSON)
description: >
Adds multiple members, up to 1000 per call, to a mailing list, using
JSON array format.
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
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
/v3/lists/{list_address}/members.csv:
post:
tags:
- Mailing Lists
summary: Bulk upload members to a mailing list (CSV)
description: >-
Adds multiple members, up to 1000 per call, to a mailing list via CSV
file.
operationId: post-lists-list_address-members.csv
parameters:
- name: list_address
in: path
description: The mailing list's address
required: true
schema:
type: string
requestBody:
description: ''
content:
multipart/form-data:
schema:
type: object
properties:
subscribed:
type: boolean
upsert:
type: boolean
members:
type: string
description: Absolute path to the CSV file
examples:
Example:
value:
upsert: true
members: absolute/path/to/file/members.csv
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
list:
$ref: '#/components/schemas/MailingListResponse'
task-id:
type: string
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
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
/v3/lists/{list_address}/members/{member_address}:
get:
tags:
- Mailing Lists
summary: Get a member
description: Get details about a specific mailing list member
operationId: get-lists-list_address-members-member_address
parameters:
- name: list_address
in: path
description: The mailing list's address
required: true
schema:
type: string
- name: member_address
in: path
description: The member's address
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListMemberResponse'
examples:
Example:
value:
address: alice@example.com
name: Alice
vars:
gender: female
age: 27
subscribed: true
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
put:
tags:
- Mailing Lists
summary: Update a mailing list member
description: >-
Updates a mailing list member with the given properties. Existing
properties not included in the request will not be changed.
operationId: put-lists-list_address-members-member_address
parameters:
- name: list_address
in: path
description: The mailing list's address
required: true
schema:
type: string
- name: member_address
in: path
description: The member's address
required: true
schema:
type: string
requestBody:
description: ''
content:
multipart/form-data:
schema:
type: object
properties:
address:
type: string
description: A valid email address specification.
name:
type: string
description: An optional member name.
vars:
type: object
description: JSON-encoded dictionary string with arbitrary parameters.
subscribed:
type: boolean
description: Set the member to subscribed or not. Defaults to True.
examples:
Example:
value:
address: alice@example.com
name: Alice
vars:
gender: female
age: 27
subscribed: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
member:
$ref: '#/components/schemas/ListMemberResponse'
message:
type: string
examples:
Example:
value:
member:
address: alice@example.com
name: Alice
vars:
gender: female
age: 27
subscribed: true
message: Mailing list member has been updated
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
delete:
tags:
- Mailing Lists
summary: Delete a member
description: Deletes a member from a mailing list
operationId: delete-lists-list_address-members-member_address
parameters:
- name: list_address
in: path
description: The mailing list's address
required: true
schema:
type: string
- name: member_address
in: path
description: The member's address
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
member:
type: object
properties:
address:
type: string
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
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
/v3/lists/{list_address}:
put:
tags:
- Mailing Lists
summary: Update a mailing list
description: Update mailing list properties, such as address, description or name
operationId: put-v3-lists-address
parameters:
- name: list_address
in: path
description: The mailing list's address
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
address:
type: string
description: The new mailing list address.
description:
type: string
name:
type: string
access_level:
type: string
description: 'One of: readonly, members, everyone. Defaults to readonly.'
reply_reference:
type: string
description: >-
Set where replies should go. Can be list or sender. Defaults
to list.
list-id:
type: string
examples:
Example:
value:
address: developers@mailgun.net
name: Developers
description: Describe the mailing list
access_level: readonly
reply_preference: list
list_id: '123'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
message:
type: string
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
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
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
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
get:
tags:
- Mailing Lists
summary: Get a mailing list by address
description: Returns the matching mailing list for the given address
operationId: get-v3-lists-address
parameters:
- name: list_address
in: path
description: The mailing list's address
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
list:
$ref: '#/components/schemas/MailingListResponse'
examples:
Example:
value:
list:
address: developers@mailgun.net
name: Developers
description: Describe the mailing list
access_level: readonly
reply_preference: list
created_at: Tue, 09 Aug 2011 20:50:27 -0000
members_count: 2
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Mailing list developers@mailgun.net not found
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
/v3/lists/pages:
get:
tags:
- Mailing Lists
summary: Get mailing lists by page
description: Paginate over mailing lists
operationId: get-v3-lists-pages
parameters:
- name: limit
in: query
description: Set limit for the list length returned. Defaults to 100.
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PaginateMailingListResponse'
examples:
Example:
value:
paging:
first: https://url_to_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: ''
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
/v3/lists/{list_address}/members/pages:
get:
tags:
- Mailing Lists
summary: Get members by page
description: Paginate over list members in a given mailing list in ascending order
operationId: get-lists-list_address-members-pages
parameters:
- name: subscribed
in: query
description: Filtering list on whether the member is subscribed or not.
schema:
type: boolean
- name: limit
in: query
description: Set limit for the list length returned. Defaults to 100.
schema:
type: integer
- name: address
in: query
description: Use as pivot for pagination.
schema:
type: string
- name: page
in: query
description: 'Could be either: first, last, next or prev'
schema:
type: string
- name: list_address
in: path
description: The mailing list's address
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PaginateListMemberResponse'
examples:
Example:
value:
paging:
first: https://url_to_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: ''
'429':
description: Too Many Requests
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example:
value:
message: Too Many Requests
security:
- basicAuth: []
/v3/{domain_name}/templates:
get:
tags:
- Templates
summary: Get templates
description: Returns a list of templates for the domain.
operationId: GET-v3--domain-name--templates
parameters:
- name: domain_name
in: path
description: Domain name to fetch the templates for.
required: true
schema:
type: string
- name: page
in: query
description: >-
Name of the page to retrieve. Value can be `first`, `last`, `next`,
or `previous`. Defaults to `first`.
schema:
type: string
enum:
- first
- last
- next
- previous
x-enumDescriptions:
first: Get the first list's page
last: Get the last list's page
next: Get the next list's page
previous: Get the previous list's page
- name: limit
in: query
description: Number of templates to retrieve. Default and max limit is 100.
schema:
type: integer
- name: p
in: query
description: Pivot used to retrieve the next page of templates.
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-getPageResponse
examples:
Example:
value:
items:
- name: template.0
description: template description
createdAt: Sat, 12 Nov 1955 06:38:00 UTC
createdBy: ''
id: 48d63154-8c8f-4104-ab14-687d01dbf296
version: null
versions: null
- name: template.1
description: template description
createdAt: Sat, 12 Nov 1955 06:38:00 UTC
createdBy: ''
id: 8d9c0f0d-7bf7-43a4-92a9-791a854d12a4
version: null
versions: null
paging:
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
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
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: POST-v3--domain-name--templates
parameters:
- name: domain_name
in: path
description: Domain name the template is associated with.
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
$ref: >-
#/components/schemas/POST-v3-domain_name-templates-multipart-form-data-RequestBody
required: true
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-createTemplateOrVersionResponse
examples:
Example:
value:
message: template has been stored
template:
name: template_name
description: This is the description of the template
createdAt: Sat, 12 Nov 1955 06:38:00 UTC
createdBy: user-supplied-value
id: 46565d87-68b6-4edb-8b3c-34554af4bb77
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: DELETE-v3--domain-name--templates
parameters:
- name: domain_name
in: path
description: Domain name the template is associated with.
required: true
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
examples:
Example:
value:
message: templates have been deleted
security:
- basicAuth: []
/v3/{domain_name}/templates/{template_name}/versions:
get:
tags:
- Templates
summary: Get all template versions
description: Returns a paginated list of template versions.
operationId: GET-v3--domain-name--templates--template-name--versions
parameters:
- name: domain_name
in: path
description: Domain name to fetch the templates for.
required: true
schema:
type: string
- name: template_name
in: path
description: template name to fetch the versions for.
required: true
schema:
type: string
- name: page
in: query
description: >-
Name of the page to retrieve. Value can be `first`, `last`, `next`,
or `previous`. Defaults to `first`.
schema:
type: string
enum:
- first
- last
- next
- previous
x-enumDescriptions:
first: Get the first list's page
last: Get the last list's page
next: Get the next list's page
previous: Get the previous list's page
- name: limit
in: query
description: Number of templates to retrieve. Default and max limit is 100.
schema:
type: integer
- name: p
in: query
description: Pivot used to retrieve the next page of templates.
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-getVersionsPageResponse
examples:
Example:
value:
template:
name: template_name
description: This is the description of the template
createdAt: Sat, 12 Nov 1955 06:38:00 UTC
createdBy: user-supplied-value
id: 46565d87-68b6-4edb-8b3c-34554af4bb77
versions:
- tag: v0
template: ''
engine: handlebars
mjml: ''
createdAt: Sat, 12 Nov 1955 06:38:00 UTC
comment: version comment
active: false
id: 71bd07b8-fe81-4199-8fcf-67c956ccdc34
headers: {}
parsedhandlebar: null
- tag: v1
template: ''
engine: handlebars
mjml: ''
createdAt: Sat, 12 Nov 1955 06:38:00 UTC
comment: version comment
active: true
id: d4a36e91-1b5f-44e0-bf5a-3542ea712b62
headers: {}
parsedhandlebar: null
- tag: v2
template: ''
engine: handlebars
mjml: ''
createdAt: Sat, 12 Nov 1955 06:38:00 UTC
comment: version comment
active: true
id: d4a36e91-1b5f-44e0-bf5a-3542ea712b62
headers: {}
parsedhandlebar: null
paging:
previous: >-
https://api.mailgun.net/v3/{domain}/templates/z4ujt7CiEeik0RJbspqxaQ/versions?page=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
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: POST-v3--domain-name--templates--template-name--versions
parameters:
- name: domain_name
in: path
description: Domain name the template is associated with.
required: true
schema:
type: string
- name: template_name
in: path
description: template name to create the new version for.
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
$ref: >-
#/components/schemas/POST-v3-domain_name-templates-template_name-versions-multipart-form-data-RequestBody
required: true
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-createTemplateOrVersionResponse
examples:
Example:
value:
message: new version of the template has been stored
template:
name: template_name
description: This is the description of the template
createdAt: Sat, 12 Nov 1955 06:38:00 UTC
createdBy: user-supplied-value
id: 46565d87-68b6-4edb-8b3c-34554af4bb77
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: []
/v3/{domain_name}/templates/{template_name}:
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: GET-v3--domain-name--templates--template-name-
parameters:
- name: domain_name
in: path
description: Domain name the template is stored under.
required: true
schema:
type: string
- name: template_name
in: path
description: Template name to fetch.
required: true
schema:
type: string
- name: active
in: query
description: >-
If this flag is set to yes the active version of the template is
included in the response.
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-getTemplateOrVersionResponse
examples:
Example:
value:
template:
name: template_name
description: This is the description of the template
createdAt: Sat, 12 Nov 1955 06:38:00 UTC
createdBy: user-supplied-value
id: 46565d87-68b6-4edb-8b3c-34554af4bb77
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: []
put:
tags:
- Templates
summary: Update template
description: Update the description of a template.
operationId: PUT-v3--domain-name--templates--template-name-
parameters:
- name: domain_name
in: path
description: Domain name the template is associated with.
required: true
schema:
type: string
- name: template_name
in: path
description: The template name.
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
$ref: >-
#/components/schemas/PUT-v3-domain_name-templates-template_name-multipart-form-data-RequestBody
required: true
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-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: DELETE-v3--domain-name--templates--template-name-
parameters:
- name: domain_name
in: path
description: Domain name the template is associated with.
required: true
schema:
type: string
- name: template_name
in: path
description: template name to be deleted.
required: true
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTempateOrVersionResponse
examples:
Example:
value:
message: template has been deleted
template:
name: template_name
security:
- basicAuth: []
/v3/{domain_name}/templates/{template_name}/versions/{version_name}:
get:
tags:
- Templates
summary: Get a version
description: >-
Retrieve the information and content of the specified version of a
template.
operationId: GET-v3--domain-name--templates--template-name--versions--version-name-
parameters:
- name: domain_name
in: path
description: Domain name the template is stored under.
required: true
schema:
type: string
- name: template_name
in: path
description: template name the version is for.
required: true
schema:
type: string
- name: version_name
in: path
description: Tag of the version of the template to fetch.
required: true
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-getTemplateOrVersionResponse
examples:
Example:
value:
template:
name: template_name
description: This is the description of the template
createdAt: Sat, 12 Nov 1955 06:38:00 UTC
createdBy: user-supplied-value
id: 46565d87-68b6-4edb-8b3c-34554af4bb77
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: []
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: PUT-v3--domain-name--templates--template-name--versions--version-name-
parameters:
- name: domain_name
in: path
description: Domain name the template is associated with.
required: true
schema:
type: string
- name: template_name
in: path
description: template name the version is stored under.
required: true
schema:
type: string
- name: version_name
in: path
description: Tag of the version of the template to be updated
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
$ref: >-
#/components/schemas/PUT-v3-domain_name-templates-template_name-versions-version_name-multipart-form-data-RequestBody
required: true
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTempateOrVersionResponse
examples:
Example:
value:
message: version has been updated
template:
name: template_name
version:
tag: tag
security:
- basicAuth: []
delete:
tags:
- Templates
summary: Delete a version
description: Delete a specific template version.
operationId: >-
DELETE-v3--domain-name--templates--template-name--versions--version-name-
parameters:
- name: domain_name
in: path
description: Domain name the template is associated with.
required: true
schema:
type: string
- name: template_name
in: path
description: template name the version is stored under.
required: true
schema:
type: string
- name: version_name
in: path
description: Tag of the version of the template to be deleted.
required: true
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-updateOrDeleteTempateOrVersionResponse
examples:
Example:
value:
message: version has been deleted
template:
name: template_name
version:
tag: tag
security:
- basicAuth: []
/v3/{domain_name}/templates/{template_name}/versions/{version_name}/copy/{new_version_name}:
put:
tags:
- Templates
summary: Copy a version
description: Copies an existing version into a new version with the provided name.
operationId: >-
PUT-v3--domain-name--templates--template-name--versions--version-name--copy--new-version-name-
parameters:
- name: domain_name
in: path
description: Domain name the template is associated with.
required: true
schema:
type: string
- name: template_name
in: path
description: template name the version is stored under.
required: true
schema:
type: string
- name: version_name
in: path
description: Tag of the version to copy.
required: true
schema:
type: string
- name: new_version_name
in: path
description: >-
The name for the new version. If the version name already exists, it
will be overridden.
required: true
schema:
type: string
- name: comment
in: query
description: Comment to be used for the new version.
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-versionCopyResponse
examples:
Example:
value:
message: version has been copied
version:
tag: cloned version
template: {{firstname}} {{lastname}}
engine: handlebars
createdAt: Fri, 21 Mar 2025 15:00:44 UTC
comment: a comment value from copy
id: 95658c55-e93a-40d5-a02f-a4fadfbbb3ca
security:
- basicAuth: []
/v5/accounts:
put:
tags:
- Account Management
summary: Update variable account settings
description: Update variable account settings
operationId: put-v5-accounts
parameters:
- name: name
in: query
description: The new account organization name
required: false
schema:
type: string
- name: inactive_session_timeout
in: query
description: The login session timeout period for inactivity
required: false
schema:
type: integer
- name: absolute_session_timeout
in: query
description: The login session timeout period limit
required: false
schema:
type: integer
- name: logout_redirect_url
in: query
description: The url to redirect to upon logout
required: false
schema:
type: string
responses:
'200':
description: Successfully updated the account setting(s)
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Account info has been updated
'400':
description: Error response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: >-
Either `name`, `absolute_timeout`, `inactive_timeout`, or
`logout_redirect_url` must be provided to update account
info.
security:
- basicAuth: []
/v5/accounts/http_signing_key:
get:
tags:
- Account Management
summary: Get webhook signing key saved on the account
description: Get webhook signing key saved on the account
operationId: get-v5-accounts-http_signing_key
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-HTTPSigningKey
examples:
Example:
value:
http_signing_key: key-55c5c5c5c55f55ca5cd5f55d5c555c55
'400':
description: Error response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: could not get HSK for account
security:
- basicAuth: []
post:
tags:
- Account Management
summary: Create or regenerate webhook signing key on an account
description: Create or regenerate webhook signing key on an account
operationId: post-v5-accounts-http_signing_key
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-HTTPSigningKey
examples:
Example:
value:
message: regenerated HTTP signing key for account
http_signing_key: key-55c5c5c5c55f55ca5cd5f55d5c555c55
security:
- basicAuth: []
/v5/sandbox/auth_recipients:
get:
tags:
- Account Management
summary: Get authorized email recipients for a sandbox domain
description: Get webhook signing key saved on the account
operationId: get-v5-sandbox-auth_recipients
responses:
'200':
description: A 200 response
content:
application/json:
schema:
type: object
properties:
recipients:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-RecipientResponse
examples:
Example:
value:
recipients:
- email: test_recipient@sandbox.com
activated: true
security:
- basicAuth: []
post:
tags:
- Account Management
summary: Add authorized email recipient for a sandbox domain
description: Add authorized email recipient for a sandbox domain
operationId: post-v5-sandbox-auth_recipients
parameters:
- name: email
in: query
description: The email address of the new recipient
required: true
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
type: object
properties:
recipient:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-RecipientResponse
examples:
Example:
value:
recipient:
email: test_recipient@sandbox.com
activated: false
'400':
description: Error response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Only 5 sandbox recipients are allowed
security:
- basicAuth: []
/v5/sandbox/auth_recipients/{email}:
delete:
tags:
- Account Management
summary: Remove an authorized sandbox domain email recipient
description: Remove an authorized sandbox domain email recipient
operationId: delete-v5-sandbox-auth_recipients-email
parameters:
- name: email
in: path
description: The email address of the authorized recipient to be removed
required: true
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Sandbox recipient deleted.
'400':
description: Error response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Invalid email address.
security:
- basicAuth: []
/v5/accounts/resend_activation_email:
post:
tags:
- Account Management
summary: Resend account activation email to the account owner
description: Resend account activation email to the account owner
operationId: post-v5-accounts-resend_activation_email
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericSuccess
examples:
Example:
value:
success: true
security:
- basicAuth: []
/v5/accounts/subaccounts/{subaccount_id}:
get:
tags:
- Subaccounts
summary: Get a single subaccount
description: Fetch the details of a single subaccount
operationId: get-v5-accounts-subaccounts-subaccount_id
parameters:
- name: subaccount_id
in: path
description: The ID of the subaccount
required: true
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-SubaccountResponse
examples:
Example:
value:
subaccount:
id: '123'
name: My subaccount
status: open
'404':
description: A 404 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Not Found
security:
- basicAuth: []
/v5/accounts/subaccounts:
get:
tags:
- Subaccounts
summary: List all subaccounts
description: Fetch all subaccounts
operationId: get-v5-accounts-subaccounts
parameters:
- name: sort
in: query
description: Sort order
schema:
type: string
enum:
- asc
- desc
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-GenericMessage
examples:
Example:
value:
message: Bad request
security:
- basicAuth: []
delete:
tags:
- Subaccounts
summary: Delete a subaccount
description: Delete a subaccount
operationId: delete-v5-accounts-subaccounts-subaccount_id
parameters:
- name: X-Mailgun-On-Behalf-Of
in: header
description: The ID of the subaccount
required: true
schema:
type: string
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Subaccount successfully deleted
'400':
description: Bad request
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Bad request
'403':
description: Forbidden
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Forbidden
security:
- basicAuth: []
/v5/accounts/subaccounts/{subaccount_id}/disable:
post:
tags:
- Subaccounts
summary: Disable a subaccount
description: Disable a subaccount
operationId: post-v5-accounts-subaccounts-subaccount_id-disable
parameters:
- name: subaccount_id
in: path
description: The ID of the subaccount
required: true
schema:
type: string
- name: reason
in: query
description: The reason for disabling the subaccount
required: false
schema:
type: string
- name: note
in: query
description: A note for the subaccount
required: false
schema:
type: string
responses:
'200':
description: Subaccount disabled successfully
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-SubaccountResponse
examples:
Example:
value:
subaccount:
id: '123'
name: My subaccount
status: disabled
'400':
description: Subaccount is already disabled
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: subaccount is already disabled
'404':
description: Not found
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Not Found
security:
- basicAuth: []
/v5/accounts/subaccounts/{subaccount_id}/enable:
post:
tags:
- Subaccounts
summary: Enable a subaccount
description: Enable a subaccount
operationId: post-v5-accounts-subaccounts-subaccount_id-enable
parameters:
- name: subaccount_id
in: path
description: The ID of the subaccount
required: true
schema:
type: string
responses:
'200':
description: Subaccount enabled successfully
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-SubaccountResponse
examples:
Example:
value:
subaccount:
id: '123'
name: My subaccount
status: open
'400':
description: Cannot enable due to limit reached
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Parent account has reached its allotted child limit
'404':
description: Not found
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Not Found
security:
- basicAuth: []
/v5/accounts/limit/custom/monthly:
get:
tags:
- Custom Message Limit
summary: Get current custom sending limit
description: Fetch the details of custom sending limit on the account
operationId: get-v5-accounts-limit-custom-monthly
responses:
'200':
description: A 200 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-CustomMessageLimitResponse
examples:
Example:
value:
limit: 10000
current: 0
period: 1m
'404':
description: A 404 response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: No threshold for account
security:
- basicAuth: []
put:
tags:
- Custom Message Limit
summary: Set a custom sending limit
description: Set a custom sending limit
operationId: put-v5-accounts-limit-custom-monthly
parameters:
- name: limit
in: query
description: The limit to set
required: true
schema:
type: number
responses:
'200':
description: Successfully set the sending limit
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericSuccess
examples:
Example:
value:
success: true
'400':
description: Error response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: The limit parameter minumum is 1000
security:
- basicAuth: []
delete:
tags:
- Custom Message Limit
summary: Delete a custom sending limit
description: Delete a custom sending limit
operationId: delete-v5-accounts-limit-custom-monthly
responses:
'200':
description: Successfully deleted the sending limit
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericSuccess
examples:
Example:
value:
success: true
'400':
description: Error response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Could not delete threshold for account
security:
- basicAuth: []
/v5/accounts/limit/custom/enable:
put:
tags:
- Custom Message Limit
summary: Re-enable account disabled for hitting send limit
description: >-
Re-enable an account that was disabled for reaching the custom sending
limit
operationId: put-v5-accounts-limit-custom-enable
responses:
'200':
description: Successfully re-enabled the account
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericSuccess
examples:
Example:
value:
success: true
'400':
description: Error response
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: >-
Unable to re-enable account with current account
disablement
security:
- basicAuth: []
/v5/accounts/subaccounts/{subaccount_id}/features:
put:
tags:
- Subaccounts
summary: Update subaccount feature
description: Update subaccount feature
operationId: put-v5-accounts-subaccounts-subaccount_id-features
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
email_preview:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-FeatureOverrideEnabledParam
inbox_placement:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-FeatureOverrideEnabledParam
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-GenericMessage
examples:
Example:
value:
message: No valid updates provided
'404':
description: Not found
content:
application/json:
schema:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-GenericMessage
examples:
Example:
value:
message: Not Found
security:
- basicAuth: []
/v1/keys:
get:
tags:
- Keys
summary: List Mailgun API keys
description: List Mailgun API keys
operationId: 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
description: >-
The unique identifier of the message as defined by
[RFC-2392](https://datatracker.ietf.org/doc/html/rfc2392).
message:
type: string
description: A success message
required:
- id
- message
github.com-mailgun-influx-httpapi-GetMessageResponseNotFound:
type: object
properties:
message:
type: string
description: A failure message
required:
- message
string:
type: string
POST-v3-domain_name-messages-multipart-form-data-RequestBody:
type: object
properties:
from:
type: string
description: >-
Email address for the `From` header. Note: not required if sending
with a template that has a pre-set From header, but it will override
it if provided.
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. Note: not required if sending with a template that
has a pre-set Subject header, but it will override it if provided.
text:
type: string
description: Body of the message (text version)
html:
type: string
description: Body of the message (HTML version)
amp-html:
type: string
description: >-
AMP part of the message. Please follow Google guidelines to compose
and send AMP emails
attachment:
type: array
items:
type: string
format: binary
description: >-
File attachment. You can post multiple `attachment` values.
**Important:** You must use `multipart/form-data` encoding for
sending attachments
inline:
type: array
items:
type: string
format: binary
format: binary
description: >-
Attachment with `inline` disposition. Can be used to send inline
images (see example). You can post multiple `inline` values
template:
type: string
description: >-
Name of a template stored via 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
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
description: The content transfer encoding if enabled
Content-Type:
type: string
description: The content type sent with the message with a possible boundary
From:
type: string
description: The full 'From' email address entry of the email
Message-Id:
type: string
description: >-
The unique identifier of the message as defined by
[RFC-2392](https://datatracker.ietf.org/doc/html/rfc2392)
Mime-Version:
type: string
description: The MIME version of the email
Subject:
type: string
description: Subject of the email
To:
type: string
description: The full 'To' email address entries
X-Mailgun-Tag:
type: string
description: The raw tags of the message if provided
sender:
type: string
description: Just the email address from the provided 'From'' field
recipients:
type: string
description: A list of email addresses from the 'To'' field
body-html:
type: string
description: The full HTML body of the full message
body-plain:
type: string
description: The plain text body of the full message
stripped-html:
type: string
description: Only the body of the email in HTML
stripped-text:
type: string
description: Only the body of the email in plain text
stripped-signature:
type: string
description: The signature stripped from the body
message-headers:
type: array
items:
type: array
items:
type: string
description: The full list of headers of the MIME upon send
X-Mailgun-Template-Name:
type: string
description: The name of the template if one was used
X-Mailgun-Template-Variables:
type: string
description: The variables used in the template if one was used
required:
- Content-Transfer-Encoding
- Content-Type
- From
- Message-Id
- Mime-Version
- Subject
- To
- X-Mailgun-Tag
- sender
- recipients
- body-html
- body-plain
- stripped-html
- stripped-text
- stripped-signature
- message-headers
- X-Mailgun-Template-Name
- X-Mailgun-Template-Variables
github.com-mailgun-influx-httpapi-GetMessageResponseBadRequest:
type: object
properties:
message:
type: string
description: A failure message
required:
- message
github.com-mailgun-domains-client-golang-Disabled:
type: object
properties:
code:
type: string
note:
type: string
permanently:
type: boolean
reason:
type: string
until:
type: string
required:
- code
- note
- permanently
- reason
github.com-mailgun-domains-client-golang-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
subaccount_id:
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:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Disabled
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
github.com-mailgun-domains-client-golang-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
github.com-mailgun-domains-httpapi-CreateDomainResp:
type: object
properties:
message:
type: string
domain:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Domain
receiving_dns_records:
type: array
items:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Record
sending_dns_records:
type: array
items:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Record
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:
$ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Domain
required:
- total_count
- items
github.com-mailgun-domains-httpapi-FindDomainByNameResp:
type: object
properties:
domain:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Domain
receiving_dns_records:
type: array
items:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Record
sending_dns_records:
type: array
items:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Record
required:
- domain
github.com-mailgun-domains-httpapi-VerifyDomainResponse:
type: object
properties:
message:
type: string
domain:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Domain
sending_dns_records:
type: array
items:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Record
receiving_dns_records:
type: array
items:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Record
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-WebhookURLs:
type: object
properties:
urls:
type: array
items:
type: string
required:
- urls
github.com-mailgun-domains-httpapi-WebhooksResponse:
type: object
properties:
accepted:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs
clicked:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs
opened:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs
unsubscribed:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs
delivered:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs
permanent_fail:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs
temporary_fail:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs
complained:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-httpapi-WebhookURLs
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:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Record
required:
- signing_domain
- selector
POST-v1-dkim-keys-multipart-form-data-RequestBody:
type: object
properties:
signing_domain:
type: string
description: Signing domain to be used for the new domain key
selector:
type: string
description: Selector to be used for the new domain key
bits:
type: integer
description: Key size, can be 1024 or 2048
pem:
type: string
description: Private key PEM file
required:
- signing_domain
- selector
github.com-mailgun-domains-httpapi-UpdateDomainKeyResp:
type: object
properties:
message:
type: string
authority:
type: string
selector:
type: string
active:
type: boolean
required:
- message
- authority
- selector
- active
github.com-mailgun-scaffold-httpapi-paging-PagingResponse:
type: object
properties:
previous:
type: string
first:
type: string
next:
type: string
last:
type: string
required:
- previous
- first
- next
- last
github.com-mailgun-domains-httpapi-DomainKeyListResponse:
type: object
properties:
items:
type: array
items:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-httpapi-DomainKeyResponse
paging:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse
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:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Record
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
description: End date in RFC-822 date format
reason:
type: string
description: Cause description
required:
- until
- reason
github.com-mailgun-domains-httpapi-ExceededQueueQuotaJSON:
type: object
properties:
is_disabled:
type: boolean
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:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Domain
receiving_dns_records:
type: array
items:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Record
sending_dns_records:
type: array
items:
anyOf:
- type: 'null'
- $ref: >-
#/components/schemas/github.com-mailgun-domains-client-golang-Record
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
github.com-mailgun-pendulum-api-Domain:
type: object
properties:
id:
type: string
account_id:
type: string
sid:
type: string
name:
type: string
state:
type: string
active_selector:
type: string
rotation_enabled:
type: string
rotation_interval:
type: string
records:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
identifier:
type: string
value:
type: string
comment:
type: string
required:
- name
- type
- identifier
- value
- comment
required:
- id
- account_id
- sid
- name
- state
- rotation_enabled
- rotation_interval
github.com-mailgun-pendulum-api-DomainResponse:
type: object
properties:
domain:
$ref: '#/components/schemas/github.com-mailgun-pendulum-api-Domain'
required:
- domain
github.com-mailgun-scaffold-httpapi-NotFoundError:
type: object
properties:
Description:
type: string
required:
- Description
PUT-v1-dkim_management-domains-name-rotation-multipart-form-data-RequestBody:
type: object
properties:
rotation_enabled:
type: boolean
description: If true, enables DKIM Auto-Rotation. If false, disables it
rotation_interval:
type: string
description: The interval at which to rotate keys. Example, '5d' for five days
required:
- rotation_enabled
github.com-mailgun-tower-api-subaccounts-ListSubaccountDIPPsResponse:
type: object
properties:
items:
type: array
items:
type: object
properties:
pool_id:
type: string
subaccount_id:
type: string
required:
- pool_id
- subaccount_id
total_count:
type: integer
format: int32
required:
- items
- total_count
github.com-mailgun-tower-api-StartSagaResponse:
type: object
properties:
message:
type: string
reference_id:
type: string
required:
- message
- reference_id
github.com-mailgun-tower-api-account-domainsResponse:
type: object
properties:
items:
type: array
items:
type: object
properties:
ips:
type: array
items:
type: string
domain:
type: string
required:
- ips
- domain
total_count:
type: integer
format: int32
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:
description:
type: string
description: Description of the DIPP
ip:
type: string
description: IP address to add to the DIPP (may be specified multiple times)
name:
type: string
description: Short name of the DIPP
required:
- description
- name
PATCH-v3-ip_pools-pool_id-multipart-form-data-RequestBody:
type: object
properties:
add_ip:
type: string
description: The IP to add to the DIPP (may be specified multiple times)
description:
type: string
description: The new description for the DIPP
link_domain:
type: string
description: >-
The ID of the domain link to the DIPP (may be specified multiple
times)
name:
type: string
description: The new short for the DIPP
remove_ip:
type: string
description: The IP to remove from the DIPP (may be specified multiple times)
unlink_domain:
type: string
description: >-
The ID of the domain to unlink from the DIPP (may be specified
multiple times)
github.com-mailgun-tower-api-ip_pools-add_ip-addMultipleIPsRequestBody:
type: object
properties:
ips:
type: array
items:
type: string
description: IPs to add to the DIPP
required:
- ips
GenericResponse:
type: object
properties:
message:
type: string
required:
- message
github.com-mailgun-terminator-httpapi-StatusResponse:
type: object
properties:
certificate:
type: string
error:
type: string
status:
type: object
required:
- status
- error
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: >-
Mailgun could not deliver the email to the recipient email server, but
will retry
permanent: >-
Mailgun could not deliver the email to the recipient email server, and
will drop the message without retrying sending.
github.com-mailgun-scout-model-tags-TagItem:
type: object
properties:
tag:
type: string
description:
type: string
first-seen:
type: string
format: date-time
last-seen:
type: string
format: date-time
required:
- tag
- description
github.com-mailgun-scout-api-TagListResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/github.com-mailgun-scout-model-tags-TagItem'
paging:
$ref: >-
#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse
required:
- items
- paging
github.com-mailgun-scout-api-TagAggregateResponse:
type: object
properties:
tag:
type: string
provider:
type: object
additionalProperties:
type: object
additionalProperties:
type: integer
format: int32
country:
type: object
additionalProperties:
type: object
additionalProperties:
type: integer
format: int32
device:
type: object
additionalProperties:
type: object
additionalProperties:
type: integer
format: int32
github.com-mailgun-scout-model-types-StatType:
type: object
properties:
type:
type: string
key:
type: string
required:
- type
- key
github.com-mailgun-scout-model-stats-Accepted:
type: object
properties:
incoming:
type: integer
format: int32
outgoing:
type: integer
format: int32
total:
type: integer
format: int32
required:
- incoming
- outgoing
- total
github.com-mailgun-scout-model-stats-Delivered:
type: object
properties:
smtp:
type: integer
format: int32
http:
type: integer
format: int32
optimized:
type: integer
format: int32
total:
type: integer
format: int32
required:
- smtp
- http
- optimized
- total
github.com-mailgun-scout-model-stats-Failed:
type: object
properties:
temporary:
type: object
properties:
espblock:
type: integer
format: int32
total:
type: integer
format: int32
required:
- espblock
- total
permanent:
type: object
properties:
suppress-bounce:
type: integer
format: int32
suppress-unsubscribe:
type: integer
format: int32
suppress-complaint:
type: integer
format: int32
bounce:
type: integer
format: int32
delayed-bounce:
type: integer
format: int32
webhook:
type: integer
format: int32
optimized:
type: integer
format: int32
total:
type: integer
format: int32
required:
- suppress-bounce
- suppress-unsubscribe
- suppress-complaint
- bounce
- delayed-bounce
- webhook
- optimized
- total
required:
- temporary
- permanent
github.com-mailgun-scout-model-stats-Stored:
type: object
properties:
total:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-Opened:
type: object
properties:
total:
type: integer
format: int32
unique:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-Clicked:
type: object
properties:
total:
type: integer
format: int32
unique:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-Unsubscribed:
type: object
properties:
total:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-Complained:
type: object
properties:
total:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-Campaign:
type: object
properties:
total:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-EmailValidation:
type: object
properties:
total:
type: integer
format: int32
public:
type: integer
format: int32
valid:
type: integer
format: int32
single:
type: integer
format: int32
bulk:
type: integer
format: int32
list:
type: integer
format: int32
mailgun:
type: integer
format: int32
mailjet:
type: integer
format: int32
required:
- total
- public
- valid
- single
- bulk
- list
- mailgun
- mailjet
github.com-mailgun-scout-model-stats-SeedTest:
type: object
properties:
total:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-BlocklistMonitoring:
type: object
properties:
total:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-EmailPreview:
type: object
properties:
total:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-EmailPreviewFailed:
type: object
properties:
total:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-LinkValidation:
type: object
properties:
total:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-LinkValidationFailed:
type: object
properties:
total:
type: integer
format: int32
required:
- total
github.com-mailgun-scout-model-stats-StatsItem:
type: object
properties:
time:
type: string
accepted:
$ref: '#/components/schemas/github.com-mailgun-scout-model-stats-Accepted'
delivered:
$ref: '#/components/schemas/github.com-mailgun-scout-model-stats-Delivered'
failed:
$ref: '#/components/schemas/github.com-mailgun-scout-model-stats-Failed'
stored:
$ref: '#/components/schemas/github.com-mailgun-scout-model-stats-Stored'
opened:
$ref: '#/components/schemas/github.com-mailgun-scout-model-stats-Opened'
clicked:
$ref: '#/components/schemas/github.com-mailgun-scout-model-stats-Clicked'
unsubscribed:
$ref: >-
#/components/schemas/github.com-mailgun-scout-model-stats-Unsubscribed
complained:
$ref: '#/components/schemas/github.com-mailgun-scout-model-stats-Complained'
campaign:
$ref: '#/components/schemas/github.com-mailgun-scout-model-stats-Campaign'
email_validation:
$ref: >-
#/components/schemas/github.com-mailgun-scout-model-stats-EmailValidation
seed_test:
$ref: '#/components/schemas/github.com-mailgun-scout-model-stats-SeedTest'
ip_blocklist_monitoring:
$ref: >-
#/components/schemas/github.com-mailgun-scout-model-stats-BlocklistMonitoring
domain_blocklist_monitoring:
$ref: >-
#/components/schemas/github.com-mailgun-scout-model-stats-BlocklistMonitoring
email_preview:
$ref: >-
#/components/schemas/github.com-mailgun-scout-model-stats-EmailPreview
email_preview_failed:
$ref: >-
#/components/schemas/github.com-mailgun-scout-model-stats-EmailPreviewFailed
link_validation:
$ref: >-
#/components/schemas/github.com-mailgun-scout-model-stats-LinkValidation
link_validation_failed:
$ref: >-
#/components/schemas/github.com-mailgun-scout-model-stats-LinkValidationFailed
required:
- time
github.com-mailgun-scout-api-StatsResponse:
type: object
properties:
tag:
type: string
description:
type: string
start:
type: string
end:
type: string
type:
$ref: '#/components/schemas/github.com-mailgun-scout-model-types-StatType'
resolution:
type: string
stats:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-scout-model-stats-StatsItem
required:
- description
- start
- end
- resolution
- stats
github.com-mailgun-scout-api-StatTypesResponse:
type: object
properties:
items:
type: array
items:
type: string
required:
- items
github.com-mailgun-scout-model-types-TagLimitItem:
type: object
properties:
id:
type: string
limit:
type: integer
format: int32
count:
type: integer
format: int32
required:
- limit
- count
github.com-mailgun-scout-api-ProvidersAggregateResponse:
type: object
properties:
providers:
type: object
additionalProperties:
type: object
additionalProperties:
type: integer
format: int32
github.com-mailgun-scout-api-DevicesAggregateResponse:
type: object
properties:
devices:
type: object
additionalProperties:
type: object
additionalProperties:
type: integer
format: int32
github.com-mailgun-scout-api-CountriesAggregateResponse:
type: object
properties:
countries:
type: object
additionalProperties:
type: object
additionalProperties:
type: integer
format: int32
github.com-mailgun-analytics-client-golang-Pagination:
type: object
properties:
sort:
type: string
description: >-
Colon-separated value indicating column name and sort direction e.g.
'domain:asc'.
skip:
type: integer
format: int64
description: >-
The number of items to skip over when satisfying the request. To get
the first page of data set skip to zero. Then increment the skip by
the limit for subsequent calls.
limit:
type: integer
format: int64
description: The maximum number of items returned in the response.
total:
type: integer
format: int64
description: The total number of items in the query result set.
required:
- sort
- skip
- limit
- total
github.com-mailgun-analytics-client-golang-Dimension:
type: object
properties:
dimension:
type: string
description: The dimension
value:
type: string
description: The dimension value
display_value:
type: string
description: The dimension value in displayable form
required:
- dimension
- value
- display_value
github.com-mailgun-analytics-internal-api-RegularMetrics:
type: object
properties:
accepted_incoming_count:
type: integer
format: int64
accepted_outgoing_count:
type: integer
format: int64
accepted_count:
type: integer
format: int64
delivered_smtp_count:
type: integer
format: int64
delivered_http_count:
type: integer
format: int64
delivered_optimized_count:
type: integer
format: int64
delivered_count:
type: integer
format: int64
stored_count:
type: integer
format: int64
processed_count:
type: integer
format: int64
sent_count:
type: integer
format: int64
opened_count:
type: integer
format: int64
clicked_count:
type: integer
format: int64
unique_opened_count:
type: integer
format: int64
unique_clicked_count:
type: integer
format: int64
unsubscribed_count:
type: integer
format: int64
complained_count:
type: integer
format: int64
failed_count:
type: integer
format: int64
temporary_failed_count:
type: integer
format: int64
permanent_failed_count:
type: integer
format: int64
temporary_failed_esp_block_count:
type: integer
format: int64
description: Use instead of esp_block_count.
permanent_failed_esp_block_count:
type: integer
format: int64
rate_limit_count:
type: integer
format: int64
webhook_count:
type: integer
format: int64
permanent_failed_optimized_count:
type: integer
format: int64
permanent_failed_old_count:
type: integer
format: int64
bounced_count:
type: integer
format: int64
hard_bounces_count:
type: integer
format: int64
soft_bounces_count:
type: integer
format: int64
delayed_bounce_count:
type: integer
format: int64
suppressed_bounces_count:
type: integer
format: int64
suppressed_unsubscribed_count:
type: integer
format: int64
suppressed_complaints_count:
type: integer
format: int64
delivered_first_attempt_count:
type: integer
format: int64
delayed_first_attempt_count:
type: integer
format: int64
delivered_subsequent_count:
type: integer
format: int64
delivered_two_plus_attempts_count:
type: integer
format: int64
delivered_rate:
type: string
opened_rate:
type: string
clicked_rate:
type: string
unique_opened_rate:
type: string
unique_clicked_rate:
type: string
unsubscribed_rate:
type: string
complained_rate:
type: string
bounce_rate:
type: string
fail_rate:
type: string
permanent_fail_rate:
type: string
temporary_fail_rate:
type: string
delayed_rate:
type: string
github.com-mailgun-analytics-internal-api-RegularItem:
type: object
properties:
dimensions:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-client-golang-Dimension
metrics:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-internal-api-RegularMetrics
github.com-mailgun-analytics-internal-api-RegularAggregates:
type: object
properties:
metrics:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-internal-api-RegularMetrics
required:
- metrics
github.com-mailgun-analytics-internal-api-RegularMetricsResponse:
type: object
properties:
start:
type: string
end:
type: string
resolution:
type: string
duration:
type: string
dimensions:
type: array
items:
type: string
pagination:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-client-golang-Pagination
items:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-internal-api-RegularItem
aggregates:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-internal-api-RegularAggregates
required:
- items
github.com-mailgun-analytics-client-golang-LabeledValue:
type: object
properties:
label:
type: string
value:
type: string
required:
- label
- value
github.com-mailgun-analytics-client-golang-FilterPredicate:
type: object
properties:
attribute:
type: string
comparator:
type: string
values:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-client-golang-LabeledValue
required:
- attribute
- comparator
github.com-mailgun-analytics-client-golang-FilterPredicateGroup:
type: object
properties:
AND:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-client-golang-FilterPredicate
required:
- AND
github.com-mailgun-analytics-client-golang-Query:
type: object
properties:
start:
type: string
description: >-
A start date (default: 7 days before current time). Must be in RFC
2822 format:
https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
end:
type: string
description: >-
An end date (default: current time). Must be in RFC 2822 format:
https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
resolution:
type: string
description: A resolution in the format of 'day' 'hour' 'month'. Default is day.
duration:
type: string
description: >-
A duration in the format of '1d' '2h' '2m'. If duration is provided
then it is calculated from the end date and overwrites the start
date.
dimensions:
type: array
items:
type: string
description: Attributes of the metric data such as 'subaccount'.
metrics:
type: array
items:
type: string
description: >-
Name of the metrics to receive the stats for such as
'processed_count'.
filter:
type: object
allOf:
- $ref: >-
#/components/schemas/github.com-mailgun-analytics-client-golang-FilterPredicateGroup
description: Filters to apply to the query.
include_subaccounts:
type: boolean
description: Include stats from all subaccounts.
include_aggregates:
type: boolean
description: Include top-level aggregate metrics.
required:
- start
- end
- resolution
- duration
- dimensions
- metrics
- filter
- include_subaccounts
- include_aggregates
github.com-mailgun-analytics-internal-api-UsageMetrics:
type: object
properties:
processed_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_single_count:
type: integer
format: int64
email_validation_bulk_count:
type: integer
format: int64
email_validation_list_count:
type: integer
format: int64
email_validation_mailgun_count:
type: integer
format: int64
email_validation_mailjet_count:
type: integer
format: int64
email_preview_count:
type: integer
format: int64
email_preview_failed_count:
type: integer
format: int64
link_validation_count:
type: integer
format: int64
link_validation_failed_count:
type: integer
format: int64
seed_test_count:
type: integer
format: int64
ip_blocklist_monitoring_count:
type: integer
format: int64
domain_blocklist_monitoring_count:
type: integer
format: int64
github.com-mailgun-analytics-internal-api-UsageItem:
type: object
properties:
dimensions:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-client-golang-Dimension
metrics:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-internal-api-UsageMetrics
github.com-mailgun-analytics-internal-api-UsageAggregates:
type: object
properties:
metrics:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-internal-api-UsageMetrics
required:
- metrics
github.com-mailgun-analytics-internal-api-UsageMetricsResponse:
type: object
properties:
start:
type: string
end:
type: string
resolution:
type: string
duration:
type: string
dimensions:
type: array
items:
type: string
pagination:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-client-golang-Pagination
items:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-internal-api-UsageItem
aggregates:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-internal-api-UsageAggregates
required:
- items
github.com-mailgun-logs-api-pkg-api-model-Account:
type: object
properties:
parent-id:
type: string
id:
type: string
github.com-mailgun-logs-api-pkg-api-model-Campaign:
type: object
properties:
id:
type: string
name:
type: string
github.com-mailgun-logs-api-pkg-api-model-DeliveryStatus:
type: object
properties:
message:
type: string
attempt-no:
type: integer
format: int32
code:
type: integer
format: int32
bounce-type:
type: string
description:
type: string
session-seconds:
type: number
format: float
retry-seconds:
type: integer
format: int32
enhanced-code:
type: string
mx-host:
type: string
certificate-verified:
type: boolean
tls:
type: boolean
utf8:
type: boolean
first-delivery-attempt-seconds:
type: number
format: float
last-code:
type: integer
format: int32
last-message:
type: string
github.com-mailgun-logs-api-pkg-api-model-Domain:
type: object
properties:
name:
type: string
required:
- name
github.com-mailgun-logs-api-pkg-api-model-Envelope:
type: object
properties:
sender:
type: string
transport:
type: string
sending-ip:
type: string
targets:
type: string
i-ip-pool-id:
type: string
github.com-mailgun-logs-api-pkg-api-model-Storage:
type: object
properties:
region:
type: string
env:
type: string
key:
type: string
url:
type: array
items:
type: string
github.com-mailgun-logs-api-pkg-api-model-Template:
type: object
properties:
name:
type: string
version:
type: string
is-text:
type: boolean
github.com-mailgun-logs-api-pkg-api-model-MessageHeaders:
type: object
properties:
to:
type: string
message-id:
type: string
from:
type: string
subject:
type: string
github.com-mailgun-logs-api-pkg-api-model-Attachment:
type: object
properties:
filename:
type: string
content-type:
type: string
size:
type: integer
format: int32
github.com-mailgun-logs-api-pkg-api-model-Message:
type: object
properties:
headers:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-MessageHeaders
attachments:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Attachment
recipients:
type: array
items:
type: string
size:
type: integer
format: int32
scheduled-for:
type: integer
format: int64
github.com-mailgun-logs-api-pkg-api-model-Flags:
type: object
properties:
is-authenticated:
type: boolean
is-system-test:
type: boolean
is-routed:
type: boolean
is-amp:
type: boolean
is-test-mode:
type: boolean
is-delayed-bounce:
type: boolean
is-callback:
type: boolean
is-encrypted:
type: boolean
required:
- is-authenticated
- is-system-test
- is-routed
- is-test-mode
- is-delayed-bounce
- is-callback
github.com-mailgun-logs-api-pkg-api-model-GeoLocation:
type: object
properties:
city:
type: string
country:
type: string
region:
type: string
timezone:
type: string
github.com-mailgun-logs-api-pkg-api-model-ClientInfo:
type: object
properties:
client-name:
type: string
client-os:
type: string
client-type:
type: string
device-type:
type: string
user-agent:
type: string
ip:
type: string
bot:
type: string
github.com-mailgun-logs-api-pkg-api-model-RoutesMatch:
type: object
properties:
recipient:
type: string
github.com-mailgun-logs-api-pkg-api-model-Routes:
type: object
properties:
actions:
type: string
description:
type: string
expression:
type: string
id:
type: string
priority:
type: integer
format: int32
match:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-RoutesMatch
github.com-mailgun-logs-api-pkg-api-model-MailingList:
type: object
properties:
address:
type: string
list-id:
type: string
sid:
type: string
github.com-mailgun-logs-api-pkg-api-model-LogEvent:
type: object
properties:
id:
type: string
event:
type: string
'@timestamp':
type: string
account:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Account
campaigns:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Campaign
tags:
type: array
items:
type: string
method:
type: string
originating-ip:
type: string
api-key-id:
type: string
delivery-status:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-DeliveryStatus
i-delivery-optimizer:
type: string
domain:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Domain
recipient:
type: string
recipient-domain:
type: string
recipient-provider:
type: string
envelope:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Envelope
storage:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Storage
template:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Template
log-level:
type: string
user-variables:
type: string
message:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Message
flags:
$ref: '#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Flags'
primary-dkim:
type: string
ip:
type: string
geolocation:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-GeoLocation
client-info:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-ClientInfo
severity:
type: string
reason:
type: string
routes:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Routes
mailing-list:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-MailingList
url:
type: string
required:
- id
- event
- '@timestamp'
- domain
github.com-mailgun-logs-api-pkg-api-model-PagingResponse:
type: object
properties:
previous:
type: string
description: Token to previous page
next:
type: string
description: Token to next page
first:
type: string
description: Token to first page
last:
type: string
description: Token to last page
total:
type: integer
format: int64
description: Total number of items
github.com-mailgun-logs-api-pkg-api-model-Aggregates:
type: object
properties:
all:
type: integer
format: int64
metrics:
type: object
additionalProperties:
type: integer
format: int64
github.com-mailgun-logs-api-pkg-api-model-LogsResponse:
type: object
properties:
start:
type: string
end:
type: string
items:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-LogEvent
pagination:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-PagingResponse
aggregates:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Aggregates
required:
- start
- end
- items
- pagination
github.com-mailgun-logs-api-pkg-api-model-LabeledValue:
type: object
properties:
label:
type: string
value:
type: string
required:
- label
- value
github.com-mailgun-logs-api-pkg-api-model-FilterPredicate:
type: object
properties:
attribute:
type: string
comparator:
type: string
values:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-LabeledValue
required:
- attribute
- comparator
- values
github.com-mailgun-logs-api-pkg-api-model-FilterPredicateGroup:
type: object
properties:
AND:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-FilterPredicate
required:
- AND
github.com-mailgun-logs-api-pkg-api-model-Pagination:
type: object
properties:
sort:
type: string
description: >-
Colon-separated value indicating column name and sort direction e.g.
'timestamp:desc'.
token:
type: string
description: A token to the requested page.
limit:
type: integer
format: int32
description: The maximum number of items returned (100 max).
github.com-mailgun-logs-api-pkg-api-model-LogsRequest:
type: object
properties:
start:
type: string
description: >-
The start date (default: 1 day before current time). Must be in RFC
2822 format:
https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
end:
type: string
description: >-
The end date (default: current time). Must be in RFC 2822 format:
https://datatracker.ietf.org/doc/html/rfc2822.html#page-14
events:
type: array
items:
type: string
description: The set of events to include.
metric_events:
type: array
items:
type: string
description: >-
Optional set of analytics metric events. Will be converted into
corresponding events.
filter:
type: object
allOf:
- $ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-FilterPredicateGroup
description: Filters to apply to the query.
include_subaccounts:
type: boolean
description: Include logs from all subaccounts.
include_totals:
type: boolean
description: Include total number of log entries.
pagination:
$ref: >-
#/components/schemas/github.com-mailgun-logs-api-pkg-api-model-Pagination
github.com-mailgun-tags-api-pkg-api-model-CustomTime:
type: object
github.com-mailgun-analytics-client-golang-Metrics:
type: object
properties:
accepted_incoming_count:
type: integer
format: int64
accepted_outgoing_count:
type: integer
format: int64
accepted_count:
type: integer
format: int64
delivered_smtp_count:
type: integer
format: int64
delivered_http_count:
type: integer
format: int64
delivered_optimized_count:
type: integer
format: int64
delivered_count:
type: integer
format: int64
stored_count:
type: integer
format: int64
sent_count:
type: integer
format: int64
opened_count:
type: integer
format: int64
clicked_count:
type: integer
format: int64
unique_opened_count:
type: integer
format: int64
unique_clicked_count:
type: integer
format: int64
unsubscribed_count:
type: integer
format: int64
complained_count:
type: integer
format: int64
failed_count:
type: integer
format: int64
temporary_failed_count:
type: integer
format: int64
permanent_failed_count:
type: integer
format: int64
esp_block_count:
type: integer
format: int64
temporary_failed_esp_block_count:
type: integer
format: int64
permanent_failed_esp_block_count:
type: integer
format: int64
rate_limit_count:
type: integer
format: int64
webhook_count:
type: integer
format: int64
permanent_failed_optimized_count:
type: integer
format: int64
permanent_failed_old_count:
type: integer
format: int64
bounced_count:
type: integer
format: int64
hard_bounces_count:
type: integer
format: int64
soft_bounces_count:
type: integer
format: int64
delayed_bounce_count:
type: integer
format: int64
suppressed_bounces_count:
type: integer
format: int64
suppressed_unsubscribed_count:
type: integer
format: int64
suppressed_complaints_count:
type: integer
format: int64
delivered_first_attempt_count:
type: integer
format: int64
delayed_first_attempt_count:
type: integer
format: int64
delivered_subsequent_count:
type: integer
format: int64
delivered_two_plus_attempts_count:
type: integer
format: int64
processed_count:
type: integer
format: int64
delivered_rate:
type: string
opened_rate:
type: string
clicked_rate:
type: string
unique_opened_rate:
type: string
unique_clicked_rate:
type: string
unsubscribed_rate:
type: string
complained_rate:
type: string
bounce_rate:
type: string
hard_bounce_rate:
type: string
soft_bounce_rate:
type: string
fail_rate:
type: string
permanent_fail_rate:
type: string
temporary_fail_rate:
type: string
delayed_rate:
type: string
email_validation_count:
type: integer
format: int64
email_validation_public_count:
type: integer
format: int64
email_validation_valid_count:
type: integer
format: int64
email_validation_single_count:
type: integer
format: int64
email_validation_bulk_count:
type: integer
format: int64
email_validation_list_count:
type: integer
format: int64
email_validation_mailgun_count:
type: integer
format: int64
email_validation_mailjet_count:
type: integer
format: int64
email_preview_count:
type: integer
format: int64
email_preview_failed_count:
type: integer
format: int64
link_validation_count:
type: integer
format: int64
link_validation_failed_count:
type: integer
format: int64
seed_test_count:
type: integer
format: int64
accessibility_count:
type: integer
format: int64
accessibility_failed_count:
type: integer
format: int64
image_validation_count:
type: integer
format: int64
image_validation_failed_count:
type: integer
format: int64
github.com-mailgun-tags-api-pkg-api-model-Tag:
type: object
properties:
account_id:
type: string
parent_account_id:
type: string
tag:
type: string
description:
type: string
first_seen:
$ref: >-
#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-CustomTime
last_seen:
$ref: >-
#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-CustomTime
metrics:
$ref: >-
#/components/schemas/github.com-mailgun-analytics-client-golang-Metrics
account_name:
type: string
required:
- account_id
- parent_account_id
- tag
- description
- account_name
github.com-mailgun-tags-api-pkg-api-model-Pagination:
type: object
properties:
sort:
type: string
description: >-
Colon-separated value indicating column name and sort direction e.g.
'lastseen:desc'.
skip:
type: integer
format: int64
description: >-
The number of items to skip over when satisfying the request. To get
the first page of data set skip to zero. Then increment the skip by
the limit for subsequent calls.
limit:
type: integer
format: int64
description: >-
The maximum number of items returned in the response. Default 10 max
1000.
total:
type: integer
format: int64
description: The total number of tags matching the search criteria.
include_total:
type: boolean
description: >-
Boolean indicating whether or not to include total number of items.
Default false.
github.com-mailgun-tags-api-pkg-api-model-TagsResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-Tag'
pagination:
$ref: >-
#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-Pagination
required:
- items
github.com-mailgun-tags-api-pkg-api-model-ListTagsRequest:
type: object
properties:
pagination:
$ref: >-
#/components/schemas/github.com-mailgun-tags-api-pkg-api-model-Pagination
include_subaccounts:
type: boolean
description: >-
Boolean indicating whether or not to include data from all
subaccounts. Default false.
include_metrics:
type: boolean
description: >-
Boolean indicating whether or not to include metrics for tags.
Default false. When true max limit is 20.
tag:
type: string
description: The tag or tag prefix.
github.com-mailgun-tags-api-pkg-api-model-UpdateTagRequest:
type: object
properties:
tag:
type: string
description: The tag to update.
description:
type: string
description: The updated tag description.
github.com-mailgun-tags-api-pkg-api-model-DeleteTagRequest:
type: object
properties:
tag:
type: string
description: The tag to delete.
github.com-mailgun-tags-api-pkg-api-model-TagLimitCountResponse:
type: object
properties:
limit:
type: integer
format: int32
count:
type: integer
format: int64
limit_reached:
type: boolean
required:
- limit
- count
- limit_reached
POST-v3-domainID-unsubscribes-import-multipart-form-data-RequestBody:
type: object
properties:
file:
type: string
description: CSV file
required:
- file
POST-v3-domainID-bounces-import-multipart-form-data-RequestBody:
type: object
properties:
file:
type: string
description: CSV file
required:
- file
POST-v3-domainID-complaints-import-multipart-form-data-RequestBody:
type: object
properties:
file:
type: string
description: CSV file
required:
- file
POST-v3-domainID-whitelists-import-multipart-form-data-RequestBody:
type: object
properties:
file:
type: string
description: CSV file
required:
- file
github.com-mailgun-holster-v4-clock-RFC822Time:
type: object
github.com-mailgun-blackbook-model-Bounce:
type: object
properties:
address:
type: string
code:
type: string
error:
type: string
created_at:
$ref: '#/components/schemas/github.com-mailgun-holster-v4-clock-RFC822Time'
required:
- address
- code
- error
- created_at
github.com-mailgun-blackbook-api-getBouncesPaginationResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/github.com-mailgun-blackbook-model-Bounce'
paging:
$ref: >-
#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse
required:
- items
- paging
github.com-mailgun-blackbook-api-BouncesList:
type: array
items:
$ref: '#/components/schemas/github.com-mailgun-blackbook-model-Bounce'
POST-v3-domainID-bounces-application-form-data-RequestBody:
type: object
properties:
address:
type: string
description: Valid email address
code:
type: string
description: 'Error code (optional, default: 550)'
error:
type: string
description: 'Error description (optional, default: empty string)'
created_at:
type: string
description: >-
Timestamp of a bounce event in RFC2822 format (optional, default:
current time)
required:
- address
github.com-mailgun-blackbook-api-suppressionResponse:
type: object
properties:
message:
type: string
address:
type: string
required:
- message
- address
github.com-mailgun-blackbook-model-Unsubscribe:
type: object
properties:
address:
type: string
tags:
type: array
items:
type: string
created_at:
$ref: '#/components/schemas/github.com-mailgun-holster-v4-clock-RFC822Time'
required:
- address
- tags
- created_at
github.com-mailgun-blackbook-api-getUnsubscribesPaginationResponse:
type: object
properties:
items:
type: array
items:
$ref: >-
#/components/schemas/github.com-mailgun-blackbook-model-Unsubscribe
paging:
$ref: >-
#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse
required:
- items
- paging
github.com-mailgun-blackbook-api-UnsubscribesList:
type: array
items:
$ref: '#/components/schemas/github.com-mailgun-blackbook-model-Unsubscribe'
POST-v3-domainID-unsubscribes-application-form-data-RequestBody:
type: object
properties:
address:
type: string
description: Valid email address
tags:
type: string
description: >-
Tag to unsubscribe from, use * to unsubscribe an address from all
domain’s correspondence (optional, default: *)
created_at:
type: string
description: >-
Timestamp of an unsubscribe event in RFC2822 format (optional,
default: current time)
required:
- address
github.com-mailgun-blackbook-model-Complaint:
type: object
properties:
address:
type: string
created_at:
$ref: '#/components/schemas/github.com-mailgun-holster-v4-clock-RFC822Time'
required:
- address
- created_at
github.com-mailgun-blackbook-api-getComplaintsPaginationResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/github.com-mailgun-blackbook-model-Complaint'
paging:
$ref: >-
#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse
required:
- items
- paging
github.com-mailgun-blackbook-api-ComplaintsList:
type: array
items:
$ref: '#/components/schemas/github.com-mailgun-blackbook-model-Complaint'
POST-v3-domainID-complaints-application-form-data-RequestBody:
type: object
properties:
address:
type: string
description: Valid email address
created_at:
type: string
description: >-
Timestamp of a complaint event in RFC2822 format (optional, default:
current time)
required:
- address
github.com-mailgun-blackbook-model-Whitelist:
type: object
properties:
type:
type: string
value:
type: string
createdAt:
$ref: '#/components/schemas/github.com-mailgun-holster-v4-clock-RFC822Time'
reason:
type: string
required:
- type
- value
- createdAt
- reason
github.com-mailgun-blackbook-api-getWhitelistPaginationResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/github.com-mailgun-blackbook-model-Whitelist'
paging:
$ref: >-
#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse
required:
- items
- paging
github.com-mailgun-blackbook-api-insertWhitelistRecordResponse:
type: object
properties:
message:
type: string
type:
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:
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-api-deleteWhitelistRecordResponse:
type: object
properties:
message:
type: string
value:
type: string
required:
- message
- value
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-model-Version:
type: object
properties:
tag:
type: string
template:
type: string
engine:
type: string
mjml:
type: string
createdAt:
type: string
readOnly: true
comment:
type: string
active:
type: boolean
id:
type: string
readOnly: true
headers:
type: object
additionalProperties:
type: string
required:
- tag
- engine
- mjml
- createdAt
- comment
- active
- id
github.com-mailgun-temple-model-Template:
type: object
properties:
name:
type: string
description: Name of the template
description:
type: string
description: Description of the template
createdAt:
type: string
description: Creation date in RFC822 format
readOnly: true
createdBy:
type: string
description: Indicate who created the template
id:
type: string
readOnly: true
version:
type: object
allOf:
- $ref: '#/components/schemas/github.com-mailgun-temple-model-Version'
description: Active version information
readOnly: true
versions:
type: array
items:
$ref: '#/components/schemas/github.com-mailgun-temple-model-Version'
description: List of template's versions
readOnly: true
required:
- name
github.com-mailgun-temple-httpapi-createTemplateOrVersionResponse:
type: object
properties:
message:
type: string
template:
$ref: '#/components/schemas/github.com-mailgun-temple-model-Template'
required:
- message
- template
POST-v3-domain_name-templates-multipart-form-data-RequestBody:
type: object
properties:
name:
type: string
description: >-
Name of the template being stored. Supports utf-8 characters and
name will be down cased.
description:
type: string
description: Description of the template being stored
createdBy:
type: string
description: >-
Optional metadata field api user can indicate who created the
template.
template:
type: string
description: Content of the template.
tag:
type: string
description: >-
Initial tag of the created version. If the template parameter is
provided and the tag is missing, the default value `initial` is
used.
comment:
type: string
description: >-
Version comment. This is valid only if a new version is being
created. (template parameter is provided.)
headers:
type: string
description: >-
Key Value json 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:
- name
POST-v3-domain_name-templates-template_name-versions-multipart-form-data-RequestBody:
type: object
properties:
template:
type: string
description: Content of the template.
tag:
type: string
description: >-
Tag of the version that is being created. Must be unique to the
template.
comment:
type: string
description: Comment related to the version that is being created.
active:
type: string
description: If this flag is set to yes, this version becomes active
headers:
type: string
description: >-
Key Value json 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:
$ref: '#/components/schemas/github.com-mailgun-temple-model-Template'
required:
- template
github.com-mailgun-temple-httpapi-getVersionsPageResponse:
type: object
properties:
template:
$ref: '#/components/schemas/github.com-mailgun-temple-model-Template'
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:
$ref: '#/components/schemas/github.com-mailgun-temple-model-Template'
paging:
$ref: >-
#/components/schemas/github.com-mailgun-scaffold-httpapi-paging-PagingResponse
required:
- items
- paging
github.com-mailgun-temple-httpapi-versionCopyResponse:
type: object
properties:
message:
type: string
version:
type: object
allOf:
- $ref: '#/components/schemas/github.com-mailgun-temple-model-Version'
description: Created version information
template:
type: object
allOf:
- $ref: '#/components/schemas/github.com-mailgun-temple-model-Version'
description: 'Deprecated: Use ''version'' field'
deprecated: true
required:
- message
- version
- template
github.com-mailgun-temple-httpapi-versionUpdate:
type: object
properties:
tag:
type: string
required:
- tag
github.com-mailgun-temple-httpapi-templateUpdate:
type: object
properties:
name:
type: string
version:
$ref: '#/components/schemas/github.com-mailgun-temple-httpapi-versionUpdate'
required:
- name
github.com-mailgun-temple-httpapi-updateOrDeleteTempateOrVersionResponse:
type: object
properties:
message:
type: string
template:
$ref: >-
#/components/schemas/github.com-mailgun-temple-httpapi-templateUpdate
required:
- message
- template
PUT-v3-domain_name-templates-template_name-versions-version_name-multipart-form-data-RequestBody:
type: object
properties:
template:
type: string
description: Content of the template.
comment:
type: string
description: Comment related to the version that is being created.
active:
type: string
description: If this flag is set to yes, this version becomes active
headers:
type: string
description: >-
Key Value json 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.
PUT-v3-domain_name-templates-template_name-multipart-form-data-RequestBody:
type: object
properties:
description:
type: string
description: Update description of the template being updated.
github.com-mailgun-accounts-api-CustomMessageLimitResponse:
type: object
properties:
limit:
type: number
description: The custom limit set for the account
current:
type: number
description: The number of messages already sent
period:
type: string
description: >-
The timeframe for which the limit applies - m for months, d for
days, h for hours
github.com-mailgun-accounts-api-SubaccountStatus:
type: string
enum:
- disabled
- open
- closed
description: The status of the subaccount
x-enumDescriptions:
disabled: Account is disabled
open: Account is open
closed: Account is closed
github.com-mailgun-accounts-api-Subaccount:
type: object
properties:
id:
type: string
description: The ID of the subaccount
name:
type: string
description: The name of the subaccount
status:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-SubaccountStatus
features:
$ref: >-
#/components/schemas/github.com-mailgun-accounts-api-FeaturesResponse
github.com-mailgun-accounts-api-SubaccountResponse:
type: object
properties:
subaccount:
$ref: '#/components/schemas/github.com-mailgun-accounts-api-Subaccount'
github.com-mailgun-accounts-api-SubaccountListResponse:
type: object
properties:
subaccounts:
type: array
items:
$ref: '#/components/schemas/github.com-mailgun-accounts-api-Subaccount'
total:
type: integer
description: The total number of subaccounts
github.com-mailgun-accounts-api-HTTPSigningKey:
type: object
properties:
message:
type: string
description: Success message
http_signing_key:
type: string
description: Decoded webhook signing key
github.com-mailgun-accounts-api-RecipientResponse:
type: object
properties:
email:
type: string
description: Email address of sandbox domain recipient
activated:
type: boolean
description: Activated/verified status of the recipient
github.com-mailgun-accounts-api-FeaturesResponse:
type: object
additionalProperties: true
github.com-mailgun-accounts-api-FeatureOverrideEnabledParam:
type: object
properties:
enabled:
type: boolean
description: The enabled status of the feature
required:
- enabled
github.com-mailgun-accounts-api-GenericSuccess:
type: object
properties:
success:
type: boolean
description: Indicates success of request
github.com-mailgun-accounts-api-GenericMessage:
type: object
properties:
message:
type: string
description: Response message
github.com-mailgun-cerberus-keys-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: Reporting
tags:
- Metrics
- Logs
- Tags New
- Stats
- Tags
- Events
- 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: Account Management
tags:
- Account Management
- name: Keys
tags:
- Keys
- name: Credentials
tags:
- Credentials
- name: IP Allowlist
tags:
- IP Allowlist
- name: Users
tags:
- Users