Prepare a list for download

POST

/optout-list/prepare-download

const url = 'https://api.optizmo.com/optout-list/prepare-download';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"optoutListId":"901fad4c46a1e723","columns":["plain"],"collectionType":["collected"],"dateRange":{"from":"2021-07-30","to":"2021-12-13"},"domainFilter":"gmail.com, co.uk","metadataFilter":"order-88421"}'
};

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

curl --request POST \
  --url https://api.optizmo.com/optout-list/prepare-download \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "optoutListId": "901fad4c46a1e723", "columns": [ "plain" ], "collectionType": [ "collected" ], "dateRange": { "from": "2021-07-30", "to": "2021-12-13" }, "domainFilter": "gmail.com, co.uk", "metadataFilter": "order-88421" }'

Starts preparing a list for download and immediately returns a link to where the download will be available.

NOTE The download link will return a 404 NOT FOUND response until the file is ready. The time it takes to prepare the download is not constant and may take up to 10 minutes for it to be available. Continue to poll the download link until it returns the file.

Authorizations

api_key

Request Body

Details of what should be included in the list download file.

application/json

object

optoutListId

required

The Opt-Out list id, which can be found on the Opt-Out list page under Opt-Out List Details

string

Example

901fad4c46a1e723

columns

required

Specifies which columns should appear in the exported file

plain - The plain text email or sms opt-out. If this is an MD5 Only list, make sure to also specify hashed otherwise your list may be full of blanks.
hashed - An MD5 or SHA512 hash of the plain text email or sms opt-out.
timestamp - When the opt-out was received into the system.
campaign - Columns for Campaign, Affiliate & Sub-Affiliate names will be added to the output file. Note that this only applies to opt-outs collected through Optizmo, not opt-outs that have been imported.
ip - The ip address that submitted an opt-out via an unsubscribe link.
metadata - The external reference (extRef) captured from the opt-out link’s query string at collection time, returned exactly as captured. Note that this is empty for imported opt-outs, for opt-outs collected before this column was introduced, and wherever no usable reference was captured.

Array<string>

>= 1 items

Allowed values: plain hashed timestamp campaign ip metadata

collectionType

required

Specifies which optouts should appear in the download based on how they were collected

collected - Optouts that were received via unsubscribe links
imported - Optouts that were imported into the system via transfers or file uploads

Array<string>

>= 1 items

Allowed values: collected imported

dateRange

Excludes opt-outs that were received outside of the specified date parameters.

object

from

Includes optouts collected + imported on or after this date in format yyyy-MM-dd

string

Example

2021-07-30

Includes optouts collected + imported on or before this date in format yyyy-MM-dd

string

Example

2021-12-13

domainFilter

Only include optouts from matching domain names. Enter the last part (root domain) of the domain name(s) you want to restrict optouts to, with multiple domains separated by commas.

string

Example

gmail.com, co.uk

metadataFilter

Only include optouts whose captured external reference (see the metadata column) exactly matches this value.

This is a single value, not a list. A comma is matched as a literal character rather than treated as a separator.
Matching is case-sensitive and exact - no wildcards, no partial matches, and no trimming of leading or trailing whitespace.
Requesting the metadata column is not required in order to filter by it. As with domainFilter, the filter narrows the rows returned whether or not the value itself appears as a column in the file.
The maxLength above is counted in characters, and the value is additionally bounded at 64 bytes of UTF-8 to match the cap applied to captured values at collection time. A value within 64 characters but over 64 bytes - roughly 22 or more CJK characters, or 33 or more accented Latin ones - is rejected with a 400 BAD REQUEST rather than accepted and then matched against nothing.

string

<= 64 characters

Example

order-88421

Responses

202

Request to prepare the download has been accepted and is currently underway.

application/json

object

downloadUrl

A url that the download will be available at once prepared. This will return a 404 NOT FOUND response until the file has been produced. Continue to poll this endpoint until the file is available.

Note that processing times depend on list size and will take between a few seconds to several minutes to become available.

string

Example

{
  "downloadUrl": "https://temp-storage.optizmo.com/downloads/suppression_list--abc-20210101.zip\""
}

400

Invalid request payload sent. This includes an empty columns array - at least one column must be requested.

401

Authorization not sent or failed.