Suppression Lists API
- Table of Contents
- Suppression List Attributes
- Suppressed Address Attributes
- Address Formats
- Get a list of suppression lists
- Create a new suppression list
- Update an existing suppression list
- Get a list of suppressed addresses
- Add new suppressed addresses
- Remove an address from the suppression list
- Find the given email address in any suppression list on an organization
Suppression List Attributes
|
id
integer |
Internal identifier for this suppression list |
|
organization_id
integer |
The organization this suppression list belongs to |
|
name
string |
Unique name of this list |
|
global
boolean |
Whether this suppression list is system global. |
|
mailing_list_id
integer |
The mailing list this suppression list is for, or |
Suppressed Address Attributes
|
id
integer |
Internal identifier for this address |
||||||||
|
suppression_list_id
integer |
Identifier of the suppression list for this address |
||||||||
|
organization_id
integer |
Organization |
||||||||
|
user_id
integer |
The user |
||||||||
|
email
string |
Address used by this record. See the “Address Formats” table below for details |
||||||||
|
added_as_auto_scomp
boolean |
This address address was added to the suppression list automatically due to a spam complaint. |
||||||||
|
auto_converted_to_punycode
boolean |
This email address originally contained unicode characters as an Internationalized Domain Name. This domain has been converted to punycode. |
||||||||
|
created_at
timestamp |
The time at which this entry was added to the suppression list. |
||||||||
|
updated_at
timestamp |
The time at which this entry was most recently edited. |
||||||||
|
address_type
string Type of this address.
|
|||||||||
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.
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
|
organization_id
integer |
The specific organization to query. Set to |
|
mailing_list_id
integer |
The specific mailing list to query. When this option is used, the following will be matched:
Only system administrators may specify a mailing list that does not belong to their organization. |
|
email
string |
The email address to search for within this organization. This value should be URI encoded. |
Query String Parameters
|
include_hashes
boolean, default: false |
Include MD5 and SHA-256 hashes that match the given address. |
Response
The response will be a JSON array of “Suppressed Address” entries as defined above.
Additionally, the following keys are added:
|
suppression_list_name
string |
The user-specified name of the suppression list. |
|
organization_name
string |
The user-specified name of the organization on which this suppression list appears. This key will only be present if |
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
}