Suppressions

On this page:

Get all suppressions

The /api/suppressions endpoint lists all your suppressions.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/suppressions \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Searching for a specific suppression by its email is possible on this endpoint using ?filter[search]=info@example.com.

Filtering is also possible on the reason, possible values are hard_bounce, spam_complaint and manual using for example: ?filter[reason]=manual.

Sorting is possible on this endpoint on created_at. For example ?sort=-created_at to sort descending on created_at.

As a result, you get the details of all your suppressions:

{
    "data": [
        {
            "uuid": "2ca0e737-b907-468f-819f-5d16e6bd6852",
            "email": "john@doe.com",
            "reason": "hard_bounce",
            "created_at": "2020-08-06T12:11:26.000000Z",
            "updated_at": "2020-08-06T12:11:26.000000Z"
        },
        {
            "uuid": "a69075c6-ff5c-4b6a-b217-12026cb72e4f",
            "email": "jane@doe.com",
            "reason": "spam_complaint",
            "created_at": "2020-08-06T12:11:26.000000Z",
            "updated_at": "2020-08-06T12:11:26.000000Z"
        }
    ],
    "links": {
        "first": "https://<your-mailcoach-domain>/api/suppressions?page=1",
        "last": "https://<your-mailcoach-domain>/api/suppressions?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://<your-mailcoach-domain>/api/suppressions",
        "per_page": 15,
        "to": 3,
        "total": 3
    }
}

Get a specific suppression

If you don’t want to retrieve all suppressions, you can get a specific suppression if you know its uuid or email. The example below will get the details of the suppression with email john@doe.com.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/suppressions/john@doe.com \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Response:

{
    "data": {
        "uuid": "2ca0e737-b907-468f-819f-5d16e6bd6852",
        "email": "john@doe.com",
        "reason": "hard_bounce",
        "created_at": "2020-08-06T12:11:26.000000Z",
        "updated_at": "2020-08-06T12:11:26.000000Z"
    },
}

Add a suppression

To add a suppression, create a POST call to the /api/suppressions/ endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/suppressions \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"email":"info@example.com"}'

Your request payload should also be a valid JSON. The actual payload, when formatted, looks like this:

{
  "email": "info@example.com",
  "reason": "manual"
}

The only field is the suppression’s email, this field is required.

If the API call succeeds, you will be given output like this:

{
    "data": {
        "uuid": "2ca0e737-b907-468f-819f-5d16e6bd6852",
        "email": "john@doe.com",
        "reason": "hard_bounce",
        "created_at": "2020-08-06T12:11:26.000000Z",
        "updated_at": "2020-08-06T12:11:26.000000Z"
    }
}

Delete a suppression

To delete a suppression, create a DELETE call to the /api/suppressions/<uuid> endpoint. In the example below, we are deleting the suppression with email john@doe.com.

$ MAILCOACH_TOKEN="your API token"
$ curl -X DELETE https://<your-mailcoach-domain>/api/suppressions/john@doe.com \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

If the API call succeeds, you will be given an empty response with a 204 status code.

On our hosted service, deleting suppressions that result from a spam_complaint are not able to be deleted.

Error handling

If an error occurs, you will be given a non-HTTP/200 response code. The resulting payload might look like this:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}
Sends