GreenArrow Email Software Documentation

Suppression Lists API

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

suppression_scope

string



The suppression scope specifies to which mailings a suppression list will apply. The possible values for this field are defined below.

Earlier releases of the software determined the scope of the suppression list through the value of the global field and the existence of the mailing_list_id value. Now you can directly specify the scope through the suppression_scope field. However, if you don’t specify suppression_scope, then the scope will be determined as done formerly (determined from the global and mailing_list_id values).

If you specify values for suppression_scope, global, and mailing_list_id that are inconsistent with each other then the API will return an error.

system

This option is available only if your user is a system admin and part of the System Organization. It causes the suppression list to be applied to all campaigns and autoresponders across all organizations.

organization

This option causes the suppression list to be applied to all campaigns and autoresponders on this organization.

mailing_list

This option causes the suppression list to be applied to all campaigns and autoresponders on a single mailing list.

When this is selected, mailing_list_id must be specified.

segment

This option prevents this suppression list from being automatically applied. It must be specifically selected as part of a segment using the “Not In Suppression List” clause.

global

boolean

This field is deprecated and will be removed in a future version of this API. Use is discouraged. See the attribute suppression_scope defined above.

Whether this suppression list is system global.

mailing_list_id

integer

The mailing list this suppression list is for, if suppression_scope is set to mailing_list.

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 id for this address

user_id

integer

The user id that added this address

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.

a

Email address is matched case-insensitively

example: [email protected]

d

All addresses at this domain are matched

example: @example.com

m

The MD5 of the lowercased email address is matched

example: 8629e8a722df2930a7513c4955ff886b

s

The SHA256 of the lowercased email address is matched.

example: 973dfe463ec85785f5f95af5ba3906eedb2d931c24e69824a89ea65dba4e813b

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

suppression_list_id

integer

The id of the suppression list.

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

organization_id

integer

The specific organization to query. Set to all to search all organizations. This may only be used by system administrators.

mailing_list_id

integer

The specific mailing list to query. When this option is used, the following will be matched:

  • Suppression lists that are organization-global to the mailing list’s organization.
  • Suppression lists that are specific to the mailing list.
  • Global suppression lists - only if the API key is a system administrator.

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 organization_id is set to all.

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
}


Copyright © 2012–2024 GreenArrow Email