Bounces

Bounces - Bounce list stores events of delivery failures due to permanent recipient mailbox errors such as non-existent mailbox. Soft bounces (for example, mailbox is full) and other failures (for example, ESP rejects an email because it thinks it is spam) are not added to the list.

Import list of bounces

post/v3/{domainID}/bounces/import

Import a CSV file containing a list of addresses to add to the bounce list. The CSV file must be 25MB or under and must contain the following column headers: address, code, error, created_at

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

error
string

Error description (optional, default: empty string)

code
string

Error code (optional, default: 550)

created_at
string

Timestamp of a bounce event in RFC2822 format (optional, default: current time)

Responses
202

A 202 response

400

A 400 response

500

A 500 response

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

View single bounce event

get/v3/{domainID}/bounces/{address}

Fetch a single bounce event by a given email address.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to get bounce from

address
required
string.+

The address to search for

Responses
200

A 200 response

Response Schema: application/json
address
required
string
code
required
string
error
required
string
created_at
required
object
-
required
string
404

A 404 response

Request samples
Response samples
application/json
{
  • "address": "foo@bar.com",
  • "created_at": "Fri, 18 Oct 2024 18:28:14 UTC",
  • "code": "550",
  • "error": "No such mailbox"
}

Clear a single bounce

delete/v3/{domainID}/bounces/{address}

The delivery to the deleted email address resumes until it bounces again.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to delete a bounce from

address
required
string.+

The address to remove

Responses
200

A 200 response

Response Schema: application/json
message
required
string
address
required
string
400

A 400 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "message": "Bounced addresses for this domain have been removed",
  • "address": "foo@bar.com"
}

View all bounces

get/v3/{domainID}/bounces

Paginate over a list of bounces for a domain.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The name of the domain you want to get bounces from

query Parameters
limit
required
integer

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

page
required
string

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

term
required
string

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

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": {
    • "next": "<next page url>",
    • "last": "<last page url>",
    • "previous": "<previous page url>",
    • "first": "<first page url>"
    }
}

Insert bounce records to the bounces list

post/v3/{domainID}/bounces

Request body is expected to be a valid JSON encoded sting containing up to 1000 bounce records or a single bounce record as application/form-data

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to insert bounces

header Parameters
Content-Type
required
string

Content-Type must be application/json if inserting using JSON, no header necessary for form-data insertion

Request Body schema:
required
address
required
string

Valid email address

code
string

Error code (optional, default: 550)

created_at
string

Timestamp of a bounce event in RFC2822 format (optional, default: current time)

error
string

Error description (optional, default: empty string)

Responses
200

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

Request samples
No sample
Response samples
application/json
{
  • "message": "4 addresses have been added to the bounces table"
}

Delete entire bounce list

delete/v3/{domainID}/bounces

Clears all email addresses with bounces from the domain. Delivery to the deleted email addresses will longer be suppressed.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to delete bounces from

Responses
200

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

404

A 404 response

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