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

created_at
string

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

code
string

Error code (optional, default: 550)

error
string

Error description (optional, default: empty string)

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
{
  • "address": "foo@bar.com",
  • "created_at": "Fri, 05 Apr 2024 15:34:16 UTC",
  • "error": "No such mailbox",
  • "code": "550"
}
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


 
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": {
    • "previous": "<previous page url>",
    • "first": "<first page url>",
    • "next": "<next page url>",
    • "last": "<last page url>"
    }
}
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"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.