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

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": "Fri, 05 Apr 2024 15:34:16 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


 
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
{
  • "value": "example.com",
  • "message": "Whitelist address/domain has been removed"
}
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
{
  • "paging": {
    • "previous": "<previous page url>",
    • "first": "<first page url>",
    • "next": "<next page url>",
    • "last": "<last page url>"
    },
  • "items": [
    • {
      }
    ]
}
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/json
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 
application/json
{
  • "address": "string"
}
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"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.