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

global

boolean

Whether this suppression list is system global.

mailing_list_id

integer

The mailing list this suppression list is for, or NULL if it is for the entire organization

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.

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–2019 GreenArrow Email