Allowlist

The allowlist API provides the ability to allowlist specific addresses from being added to bounce list. You can allowlist 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 allowlisted. 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 allowlisted addresses/domains

post/v3/{domainID}/whitelists/import

Import a CSV file containing a list of addresses and/or domains to add to the allowlist. 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 allowlist records
get/v3/{domainID}/whitelists/{value}
Fetch a single allowlist 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 allowlist record for


 
value
required
string
The address to search for


 
Responses 
200
A 200 response


Response Schema: application/json
type
required
string
Type of allowlist


 
value
required
string
Domain or address allowlisted


 
createdAt
required
object
Timestamp for when the entry was created in RFC822 format


 
reason
required
string
User-provided reason for allowlisting


 
404
A 404 response


Request samples 
Response samples 
application/json
{
  • "type": "domain",
  • "value": "alice@example.com",
  • "createdAt": "Thu, 01 May 2025 15:36:42 UTC",
  • "reason": "why the record was created"
}
Remove a record from an allowlist
delete/v3/{domainID}/whitelists/{value}
Remove a record from an allowlist


SecuritybasicAuth 
Request 
path Parameters
domainID
required
string
The id of the domain you want to delete an allowlisted record


 
value
required
string
The address to remove


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
Response message


 
value
required
string
Domain or address


 
404
A 404 response


Request samples 
Response samples 
application/json
{
  • "message": "Allowlist address/domain has been removed",
  • "value": "example.com"
}
View all allowlist records for a domain
get/v3/{domainID}/whitelists
Paginate over  all allowlist records for a domain.


SecuritybasicAuth 
Request 
path Parameters
domainID
required
string
The name of the domain you want to get allowlist 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 allowlist record
post/v3/{domainID}/whitelists
Add an address or domain to the allowlist table


SecuritybasicAuth 
Request 
path Parameters
domainID
required
string
The id of the domain you want to allowlist from


 
Request Body schema: application/form-data
required
address
required
string
Valid email address if you would like to allowlist email address (prior over 'domain' parameter)


 
domain
string
Valid domain name if you would like allowlist entire domain name


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
Response message


 
type
required
string
Type of allowlist


 
value
required
string
Domain or address


 
400
A 400 response


Request samples 
Response samples 
application/json
{
  • "message": "Address/Domain has been added to the allowlists table",
  • "type": "domain",
  • "value": "example.com"
}
Clear domains allowlist
delete/v3/{domainID}/whitelists
Delete an entire allowlist for a domain


SecuritybasicAuth 
Request 
path Parameters
domainID
required
string
The id of the domain you want to delete allowlist table from


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
Response message


 
400
A 400 response


Request samples 
Response samples 
application/json
{
  • "message": "Allowlist addresses/domains for this domain have been removed"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.