Whitelist

The whitelist API provides the ability to whitelist specific addresses from being added to bounce list. You can whitelist by domain name (i.e example.com) or by specific address (i.e. alice@example.com). Mailgun doesn’t add an address to bounce list if the address is whitelisted. This API is very useful if you test against your private services and don’t want to constantly clean up bounce lists.

View a single whitelist records

get/v3/{domainID}/whitelists/{value}

Fetch a single whitelist record to check if a given address or domain is present.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want the whitelist record for

value
required
string.+

The address to search for

Responses
200

A 200 response

Response Schema: application/json
type
required
string
value
required
string
createdAt
required
object
reason
required
string
404

A 404 response

Request samples
Response samples
application/json
{
  • "type": "domain",
  • "reason": "why the record was created",
  • "value": "alice@example.com",
  • "createdAt": "Fri, 18 Oct 2024 18:28:14 UTC"
}

Remove a record from whitelist

delete/v3/{domainID}/whitelists/{value}

Remove a record from whitelist

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to delete a whitelisted record

value
required
string

The address to remove

Responses
200

A 200 response

Response Schema: application/json
message
required
string
value
required
string
404

A 404 response

Request samples
Response samples
application/json
{
  • "message": "Whitelist address/domain has been removed",
  • "value": "example.com"
}

View all whitelist records for a domain

get/v3/{domainID}/whitelists

Paginate over all whitelist records for a domain.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The name of the domain you want to get whitelist from

query Parameters
address
required
string

address serving as a "divider" between pages

term
required
string

Filter records based on addresses that start with the specified substring.

limit
integer

Maximum number of records to return (optional, default: 100, max: 1000)

page
string

Page direction relative to the above address, can be next, previous or last, if empty, returns the first page

Responses
200

A 200 response

Response Schema: application/json
required
Array of objects
required
object
400

A 400 response

Request samples
Response samples
application/json
{
  • "items": [
    • {
      }
    ],
  • "paging": {
    • "previous": "<previous page url>",
    • "first": "<first page url>",
    • "next": "<next page url>",
    • "last": "<last page url>"
    }
}

Add a single whitelist record

post/v3/{domainID}/whitelists

Add an address or domain to the whitelist table

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to whitelist from

Request Body schema: application/form-data
required
address
required
string

Valid email address if you would like to whitelist email address (prior over 'domain' parameter)

domain
string

Valid domain name if you would like whitelist entire domain name

Responses
200

A 200 response

Response Schema: application/json
message
required
string
type
required
string
value
required
string
400

A 400 response

Request samples
Response samples
application/json
{
  • "message": "Address/Domain has been added to the whitelists table",
  • "type": "domain",
  • "value": "example.com"
}

Clear domains whitelist

delete/v3/{domainID}/whitelists

Delete an entire whitelist for a domain

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to delete whitelist table from

Responses
200

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

Request samples
Response samples
application/json
{
  • "message": "Whitelist addresses/domains for this domain have been removed"
}

Import list of whitelisted addresses/domains

post/v3/{domainID}/whitelists/import

Import a CSV file containing a list of addresses and/or domains to add to the whitelist. The CSV file must be 25MB or under and must contain the following column headers: address, domain.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to update

header Parameters
Content-Type
required
string

Content-Type must be multipart/form-data

Request Body schema: multipart/form-data
required
address
required
string

Valid email address if you would like to whitelist email address (prior over 'domain' parameter)

domain
string

Valid domain name if you would like whitelist entire domain name

Responses
202

A 202 response

400

A 400 response

500

A 500 response

Request samples
Response samples
application/json
{
  • "message": "file uploaded successfully"
}