Prepare a suppression list download

GET

/accesskey/download/{mailer_access_key}

const url = 'https://mailer-api.optizmo.net/accesskey/download/m-a12-a92b82cd3848ef7810d9ef0e?format=md5&deltas=1&delta_timestamp=1546300800&token=<token>';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://mailer-api.optizmo.net/accesskey/download/m-a12-a92b82cd3848ef7810d9ef0e?format=md5&deltas=1&delta_timestamp=1546300800&token=<token>'

Prepares the campaign’s suppression list as a ZIP file (including domain suppression where applicable) and returns a download_link. Retrieve the file by making a GET request to that link — see Retrieve the prepared suppression file.

Note: Campaigns that have email creative attached will have to be manually downloaded the first time so as they need to be selected.

Authorizations

mailerToken

Parameters

Path Parameters

mailer_access_key

required

string

The Mailer Access Key (MAK) identifying the campaign whose suppression list you are downloading.

Query Parameters

format

Suppression file output format.

string

Allowed values: plain md5

Output format for the suppression file. Defaults to the list’s configured format when omitted.

Example

md5

deltas

integer

Allowed values: 0 1

Set to 1 to retrieve only additions since your last download. Defaults to 0.

Example

delta_timestamp

integer format: int64

Used in conjuction with the deltas=1 query param, emails will be grabbed from this Unix timestamp to now. If omitted, the timestamp for when the suppression file was last prepared will be used.

Example

1546300800

Responses

200

The request always returns HTTP 200. On success the response contains the download_link and campaign details; on failure (including an invalid token) it returns an error response whose error_code identifies the problem.

application/json

One of:

object
object

Returned when a suppression download is prepared successfully.

object

result

required

Always success for a successful response.

string

Allowed value: success

format

required

Suppression file output format.

string

Allowed values: plain md5

campaign_name

required

Name of the campaign the suppression list belongs to.

string

download_link

required

URL for retrieving the suppression ZIP file. The token and dcma query parameters are already embedded — issue a GET to this link as-is.

string format: uri

optout_link

required

Public opt-out URL for the campaign.

string format: uri

delta_timestamp

required

Unix timestamp marking the point this download was prepared from. Pass it as the delta_timestamp query parameter on a subsequent request to fetch only additions collected since.

integer format: int64

help

required

Human-readable guidance on what to do next.

string

Error response returned when a request fails.

object

result

required

Always error for a failed response.

string

Allowed value: error

error_code

required

Error code.

string

error

required

Title of the error.

string

help

Detailed description of error with help on how to resolve it.

string

Examples

A prepared download

{
  "result": "success",
  "format": "plain",
  "campaign_name": "Example Campaign",
  "download_link": "https://mailer-api.optizmo.net/accesskey/getfile/m-crlc-e51-abef0eb8a275f3?token=<token>&dcma=<dcma>",
  "optout_link": "http://www.optout-crlc.net/o-crlc-e51-490cb3212b3f17b35d990627d4a79",
  "delta_timestamp": 1546300800,
  "help": "Use the download_link to grab the suppression file."
}

Invalid access key

{
  "result": "error",
  "error_code": "internal_error",
  "error": "Invalid access key."
}