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.

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. For each row provide either an address or a domain, but not both - choose one, keep the other blank.

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
file
required
string

CSV file

Responses
202

A 202 response

400

A 400 response

500

A 500 response

Request samples 
Response samples 
application/json
{
  • "message": "file uploaded successfully for processing. standby..."
}
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",
  • "value": "alice@example.com",
  • "createdAt": "Tue, 07 Jan 2025 19:25:45 UTC",
  • "reason": "why the record was created"
}
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"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.