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

Responses
200

A 200 response

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

A 404 response

Request samples
Response samples
application/json
{
  • "code": "550",
  • "created_at": "Fri, 16 Feb 2024 16:25:16 UTC",
  • "address": "foo@bar.com",
  • "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

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
{
  • "address": "foo@bar.com",
  • "message": "Bounced addresses for this domain have been removed"
}

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

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

Insert multiple bounce records via JSON

post/v3/{domainID}/bounces

Request body is expected to be a valid JSON encoded sting containing up to 1000 bounce records.

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

Request Body schema: application/json
optional
Array
address
required
string
code
required
string
error
required
string
created_at
required
object
MessageHash
required
string
Responses
200

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

Request samples
application/json
[
  • {
    • "address": "alice@example.com",
    • "code": "550",
    • "createdat": { },
    • "error": "Bounced",
    • "messagehash": ""
    },
  • {
    • "address": "bob@example.com",
    • "code": "550",
    • "createdat": { },
    • "error": "Bounced",
    • "messagehash": ""
    },
  • {
    • "address": "carol@example.com",
    • "code": "550",
    • "createdat": { },
    • "error": "",
    • "messagehash": ""
    },
  • {
    • "address": "dan@example.com",
    • "code": "",
    • "createdat": { },
    • "error": "",
    • "messagehash": ""
    }
]
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"
}