API docs by Redocly

Optizmo API (1.0.0)

Download OpenAPI specification:Download

Authentication

All API endpoints require authentication. To become authenticated you will need your Optizmo API key which is found on the SUPPRESS Account Settings page.

The API key needs to be sent with every request as an Authorization header:

Authorization: Bearer <API key>

Rate Limiting

API endpoints are rate limited to ensure stable and fair access to the API.

Refer to the x-rate-limit-limit, x-rate-limit-remaining, and x-rate-limit-reset response headers for rate limit information.

Response Times

API endpoints should respond almost immediately. Where long-running processing are started (e.g. Preparing a list for download) a complementary method is provided for checking the process status.

optout-list

Lists that contain a collection of all emails/phone numbers/hashes of users who have opted out.

Prepare a list for download

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.

header Parameters
Authorization
required
any

Your API key used to authenticate the request

Request Body schema: application/json

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

optoutListId
required
string

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

columns
required
Array of strings
Items Enum: "plain" "hashed" "timestamp" "campaign" "ip"

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.
collectionType
required
Array of strings
Items Enum: "collected" "imported"

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
object

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

domainFilter
string

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.

Responses

Request samples

Content type
application/json
{
  • "optoutListId": "901fad4c46a1e723",
  • "columns": [
    ],
  • "collectionType": [
    ],
  • "dateRange": {
    },
  • "domainFilter": "gmail.com, co.uk"
}

Response samples

Add to a list

Generates a URL that a file of Opt-Outs can be uploaded to, in order to add them to an existing Opt-Out list

header Parameters
Authorization
required
any

Your API key used to authenticate the request

Request Body schema: application/json

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

optoutListId
required
string

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

fileContentLength
required
number

The size of the Opt-Out file in bytes. The size cannot exceed 5gb.

Responses

Request samples

Content type
application/json
{
  • "optoutListId": "901fad4c46a1e723",
  • "fileContentLength": 536870912
}

Response samples

Content type
application/json
{}

Fetch upload status

Fetches the current status of an optout-list upload

path Parameters
reference
required
any

Reference returned from the request to /optout-list/prepare-upload

header Parameters
Authorization
required
any

Your API key used to authenticate the request

Responses

Response samples

Content type
application/json
{
  • "status": "running",
  • "message": "string",
  • "elapsedSeconds": 0,
  • "addedCount": 0,
  • "malformedCount": 0,
  • "submittedCount": 0
}

Has Opt-Out

Checks to see if an Opt-Out exists in an optout-list. This feature is not currently available. Please contact us to register your interest in this feature.

query Parameters
optoutListId
required
any
Example: optoutListId=901fad4c46a1e723

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

optout
required
any
Example: optout=foo@bar.com

The Opt-Out to search for in the list

header Parameters
Authorization
required
any

Your API key used to authenticate the request

Responses

Response samples

Content type
application/json
{
  • "hasOptout": true
}

client-optout

Collect an optout

Collects an optout to be processed and stored directly into an Opt-Out List.

header Parameters
Authorization
required
any

Your API key used to authenticate the request

Request Body schema: application/json

Details of what should be included in the list collect optout request.

One of
optoutListId
required
string

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

email
required
string

An email to collect as an optout into an email list.

Responses

Request samples

Content type
application/json
{
  • "optoutListId": "901fad4c46a1e723",
  • "sms": "12345678900"
}