Complaints

Emaill addresses of recipients who marked your messages as a spam (for ESPs that support FBL).

Import list of complaints

post/v3/{domainID}/complaints/import

Import CSV file containing a list of addresses to add to the complaint list.The CSV file must be 25MB or under and must contain the following column headers: address, 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 complaint 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 a single complaint record

get/v3/{domainID}/complaints/{address:.+}

Fetch a single complaint records to check if a given address is present in the list of complaints.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to fetch a complaint from

Responses
200

A 200 response

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

A 404 response

Request samples
Response samples
application/json
{
  • "address": "alice@example.com",
  • "created_at": "Fri, 16 Feb 2024 16:25:16 UTC"
}

Clear a single complaint event

delete/v3/{domainID}/complaints/{address:.+}

The delivery to the deleted email address resumes until there is another complaint.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

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

Responses
200

A 200 response

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

A 404 response

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

View all complaints

get/v3/{domainID}/complaints

Paginate a list of complaints for the domain.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The name of the domain you want to get complaints from

query Parameters
address
required
string

address serving as a "divider" between pages

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>"
    }
}

Insert multiple complaint records provided in JSON format

post/v3/{domainID}/complaints

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

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to insert complaints

header Parameters
Content-Type
required
string

Content-Type must be application/json

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

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

Request samples
application/json
[
  • {
    • "address": "alice@example.com",
    • "createdat": { }
    },
  • {
    • "address": "bob@example.com",
    • "createdat": { }
    }
]
Response samples
application/json
{
  • "message": "2 complaint addresses have been added to the complaints table"
}

Delete entire complaints list

delete/v3/{domainID}/complaints

Clears all email addresses with complaints 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 complaints from

Responses
200

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

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