Suppression Lists API

• Table of Contents
• Suppression List Attributes
• Suppressed Address Attributes
• Address Formats
• Get a list of suppression lists
  • URL
  • Response
• Create a new suppression list
  • URL
  • Post Data
  • Response
• Update an existing suppression list
  • URL
  • Response
• Delete a suppression list
  • URL
  • Request Parameters
  • Response
  • Example
• Get a list of suppressed addresses
  • URL
  • Response
• Add new suppressed addresses
  • URL
  • Post Data
• Remove an address from the suppression list
  • URL
• Find the given email address in any suppression list on an organization
  • URL
  • URL Parameters
  • Query String Parameters
  • Response
  • Example

Suppression List Attributes

Suppressed Address Attributes

Address Formats

Get a list of suppression lists

URL

GET /ga/api/v2/suppression_lists

Response

Returns an array of suppression lists.

Create a new suppression list

URL

POST /ga/api/v2/suppression_lists

Post Data

{
  "suppression_list": {
    "name": "New Suppression List",
    "mailing_list_id": null
  }
}

Response

Returns a suppression list object.

Update an existing suppression list

URL

PUT /ga/api/v2/suppression_lists/:suppression_list_id

Response

Returns the updated suppression list object.

Delete a suppression list

Deleting a suppression list also deletes all existing addresses in the suppression list.

Global Suppression lists currently used by the Automatic Suppression List feature may not be deleted.

URL

DELETE /ga/api/v2/suppression_lists/:suppression_list_id

Request Parameters

Response

An empty successful response to this request indicates that the suppression list was successfully deleted.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

DELETE /ga/api/v2/suppression_lists/44
HTTP/1.1 200 OK
{
  "success": true,
  "data": null,
  "error_code": null,
  "error_message": null
}

Get a list of suppressed addresses

URL

GET /ga/api/v2/suppression_lists/:suppression_list_id/suppressed_addresses?page=0&per_page=250

Response

This endpoint returns an array of suppressed addresses.

Add new suppressed addresses

URL

POST /ga/api/v2/suppression_lists/:suppression_list_id/suppressed_addresses/create_multiple

Post Data

This endpoint accepts a data parameter that contains an array of addresses.

{
  "data": [
    "@example.com",
    "[email protected]",
    "8629e8a722df2930a7513c4955ff886b"
  ]
}

Remove an address from the suppression list

URL

DELETE /ga/api/v2/suppression_lists/:suppression_list_id/suppressed_addresses/:id

The value of :id can either be the internal identifier of the suppressed address or the address of the record.

Find the given email address in any suppression list on an organization

URL

Search for suppressed addresses in the authenticated API key’s organization:

GET /ga/api/v2/suppressed_addresses_by_email/:email

Search for suppressed addresses in a specific organization:

GET /ga/api/v2/organizations/:organization_id/suppressed_addresses_by_email/:email

Search for suppressed addresses in all organizations:

GET /ga/api/v2/organizations/all/suppressed_addresses_by_email/:email

Search for suppressed addresses that apply to a given mailing list:

GET /ga/api/v2/mailing_lists/:mailing_list_id/suppressed_addresses_by_email/:email

Any of the above URIs can be instructed to also return hashes in the suppression list that match the given email:

GET /ga/api/v2/suppressed_addresses_by_email/:email?include_hashes=true

URL Parameters

Query String Parameters

Response

The response will be a JSON array of “Suppressed Address” entries as defined above.

Additionally, the following keys are added:

Example

GET /ga/api/v2/organizations/1/suppressed_addresses_by_email/[email protected]

HTTP/1.1 200 OK

{
  "success": true,
  "error_code": null,
  "error_message": null,
  "per_page": 1000,
  "page": 0,
  "data": [
    {
      "added_as_auto_scomp": false,
      "address_type": "a",
      "auto_converted_to_punycode": false,
      "created_at": "2019-06-19T12:16:57Z",
      "email": "[email protected]",
      "id": 22,
      "organization_id": 1,
      "suppression_list_id": 22,
      "updated_at": "2019-06-19T12:16:57Z",
      "user_id": 1397,
      "suppression_list_name": "Suppression List #22"
    },
    {
      "added_as_auto_scomp": false,
      "address_type": "a",
      "auto_converted_to_punycode": false,
      "created_at": "2019-06-19T12:16:57Z",
      "email": "[email protected]",
      "id": 23,
      "organization_id": 1,
      "suppression_list_id": 23,
      "updated_at": "2019-06-19T12:16:57Z",
      "user_id": 1398,
      "suppression_list_name": "Suppression List #23"
    },
    {
      "added_as_auto_scomp": false,
      "address_type": "a",
      "auto_converted_to_punycode": false,
      "created_at": "2019-06-19T12:16:57Z",
      "email": "[email protected]",
      "id": 24,
      "organization_id": 1,
      "suppression_list_id": 24,
      "updated_at": "2019-06-19T12:16:57Z",
      "user_id": 1399,
      "suppression_list_name": "Suppression List #24"
    }
  ],
  "num_records": 3,
  "num_pages": 1
}