Usage Notes
Get the details of the Account and any transaction limits applied.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Account not found |
490 | Account is disabled, API access denied |
Response Details
{
company_name: string,Account Name
api_identifier: string,API Identifier
timezone: string,Timezone name
date_format: string,Date Format
transactions_limited: boolean,Transactions limited [TRUE,FALSE]
transactions_balance: integerCurrent Transaction Balance
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get a list of Workflows and related API identifers. Use the results to then request more specific information about individual Workflows.
All Workflows are returned by default and optionally filter on 'ACTIVE', 'PAUSED' and 'DEACTIVATED'.
This command never returns 'draft' Workflows, they are only accessible through the UI.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
workflow_status | string |
[ACTIVE, PAUSED, DEACTIVATED]
|
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | No Workflows detected |
421 | Invalid Workflow status - must be either ACTIVE, DEACTIVATED or PAUSED |
490 | Account is disabled, API access denied |
Response Details
{
0: {
workflow_id: integer,Our internal ID for the Workflow
workflow_api_identifier: string,Workflow API identifier
workflow_description: string,Workflow description
workflow_notes: string,Workflow notes
workflow_status: stringWorkflow status
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get a list of Email Actions for an individual Workflow.
Use the results to then request more specific information about individual Workflow Emails using this request.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
workflow_api_identifier | string | Workflow API Identifier | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Workflow not detected |
421 | Workflow API Identifier must be provided |
422 | No Workflow Email Actions detected |
490 | Account is disabled, API access denied |
Response Details
{
0: {
workflow_action_id: integer,Internal ID for the Email Action
workflow_action_description: string,Email Action description
workflow_action_notes: string,Email Action notes
status: string,Action Status [ACTIVE, DELETED]
date_created: string,
date_deleted: stringShown when the action has a status of DELETED
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Pass a Workflow API identifier or Workflow ID to access high-level and Email Action related metrics.
A date range is required to limit the amount of data that can be returned in each request. Alternatively, supply a Launch ID instead to retrieve stats for a particular launched workflow.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
workflow_api_identifier | string | Workflow API identifier | * Provide one only |
workflow_id | string | Our internal ID for the Workflow | * Provide one only |
date_from | date | Date from as YYYY-MM-DD | |
date_to | date | Date to as YYYY-MM-DD | |
launch_id | integer | Workflow Launch ID |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Workflow not detected |
421 | Workflow API Identifier or Workflow ID is required |
422 | Invalid date from, please provide in the format YYYY-MM-DD |
423 | Invalid date to, please provide in the format YYYY-MM-DD |
424 | Date From occurs ahead of Date To, please check your dates are in the correct order |
425 | A maximum of 90 days of data can be requested, check the date to and from |
426 | Please provide either a date range or Launch ID, not both |
427 | Launched workflow could not be found, check the ID and try again |
490 | Account is disabled, API access denied |
Response Details
{
0: {
workflow_id: integer,Our internal ID for the Workflow
workflow_api_identifier: string,Workflow API identifier
workflow_description: string,Workflow description
workflow_notes: string,Workflow notes
workflow_date_created: datetime,Workflow date created
workflow_status: string,Workflow Status
stats: {
trigger_requests: integer,
triggered: integer,
ignored: integer,
failed: integer,
completed: integer,
emails_queued: integer,
webhooks_queued: integer,
notifications_queued: integer,
tags_applied: integer,
lists_subscribed: integer,
lists_unsubscribed: integer,
global_suppression: integer,
global_unsuppression: integer,
additional_workflows: integer,
transactions: integer
}
emails: {
workflow_action_id: integer,
workflow_action_description: string,
template_id: string,
stats: {
queued: integer,
delivered: integer,
soft_bounced: integer,
hard_bounced: integer,
undelivered: integer,
opened: integer,
clicked: integer,
opted_out: integer,
viewed_online: integer,
workflows_triggered: integer,
auto_cleansed: integer,
email_returns: integer,
complained: integer,
conversions: integer,
conversions_value: float
}
}...
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Pass a Workflow API identifier to download a CSV file containing high-level activity data.
A date range is required to limit the amount of data that can be returned in each request. Alternatively, supply a Launch ID instead to retrieve stats for a particular launched workflow.
Use the export_type parameter to switch between activity and failed triggers.
Valid requests return a compressed ZIP archive in order to reduce transfer times of larger files. Use the optional 'filename' parameter to override the default naming convention of the zip file.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
workflow_api_identifier | string | Workflow API Identifier | * Required |
date_from | date | Date from as YYYY-MM-DD | |
date_to | date | Date to as YYYY-MM-DD | |
launch_id | integer | Workflow Launch ID | |
export_type | string |
[activity, failed, email_performance]
|
|
filename | string | Preferred filename |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Workflow API Identifier must be provided |
421 | Invalid date from, please provide in the format YYYY-MM-DD |
422 | Invalid date to, please provide in the format YYYY-MM-DD |
423 | Date From occurs ahead of Date To, please check your dates are in the correct order |
424 | Requested download does not contain any records |
425 | Workflow not detected |
426 | Workflow Action ID must be provided |
427 | Workflow Action could not be located |
428 | Export type is not valid [activity, failed, email_performance] |
429 | Please provide either a date range or Launch ID, not both |
430 | Launched workflow could not be found, check the ID and try again |
431 | Preferred Filename is invalid; alpha-numeric, underscores and dashes only |
432 | A maximum of 90 days of data can be requested, check the date to and from |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Pass a Workflow API identifier and a Workflow Action ID to download metrics data for an invidiual Email Action.
A date range is required to limit the amount of data that can be returned in each request. Alternatively, supply a Launch ID instead to retrieve stats for a particular launched workflow.
Use the export_type parameter to get access to specific data relating to the Email Action.
Valid requests return a compressed ZIP archive in order to reduce transfer times of larger files. Use the optional 'filename' parameter to override the default naming convention of the zip file.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
workflow_api_identifier | string | Workflow API Identifier | * Required |
workflow_action_id | integer | Workflow Action ID | * Required |
date_from | date | Date from as YYYY-MM-DD | |
date_to | date | Date to as YYYY-MM-DD | |
launch_id | integer | Workflow Launch ID | |
export_type | string |
[audit, sent, delivered, undelivered, soft, hard, opens, clicks, optout, complaints, cleansed, email_clients, clicks_info, conversions, location, user_agents, devices, link_scanner]
|
|
filename | string | Preferred filename |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Workflow API Identifier must be provided |
421 | Invalid date from, please provide in the format YYYY-MM-DD |
422 | Invalid date to, please provide in the format YYYY-MM-DD |
423 | Date From occurs ahead of Date To, please check your dates are in the correct order |
424 | Requested download does not contain any records |
425 | Workflow not detected |
426 | Workflow Action ID must be provided |
427 | Workflow Action could not be located |
428 | Export type is not valid [audit, sent, delivered, undelivered, soft, hard, opens, clicks, optout, complaints, cleansed, email_clients, clicks_info, conversions, location, user_agents, devices, link_scanner] |
429 | Please provide either a date range or Launch ID, not both |
430 | Launched workflow could not be found, check the ID and try again |
431 | Preferred Filename is invalid; alpha-numeric, underscores and dashes only |
432 | A maximum of 90 days of data can be requested, check the date to and from |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Trigger a Workflow for individual Users. When an email address match is not made Users are created on-demand so you do not have to create User records prior to triggering.
User Profile & Custom Field data can also be passed so that values are updated prior to the Workflow being triggered.
Trigger requests will be rejected unless the Workflow is 'active' or is 'paused' and queueing is permitted. Valid requests return an internal Workflow ID which can then be used to track and report on.
JSON encoded Session Variables can also be passed to the Workflow as it's triggered and these variables will persist for the duration of the Workflow. Reference Session Variables in any Action to influence how each step is processed.
For more information on how Workflow data is processed click here.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
workflow_api_identifier | string | Workflow API identifier | * Provide one only |
workflow_id | string | Our internal ID for the Workflow | * Provide one only |
workflow_session_variables | string | JSON encoded Workflow Session Variables | |
journey_label | string | Free-format label that is displayed in Workflow reports | |
email_address | string | Email Address | * Required |
reference_code | string | Reference Code | |
title | string | ||
first_name | string | ||
last_name | string | ||
company_name | string | ||
address_line_1 | string | ||
address_line_2 | string | ||
address_line_3 | string | ||
address_line_4 | string | ||
city | string | ||
post_code | string | ||
country | string | Two digit ISO country code | |
mobile | string | 11 digits or 12 digits including country code | |
telephone | string | ||
dob | string | Date of Birth [YYYY-MM-DD] | |
gender | string | Gender [MALE, FEMALE, M, F or blank] | |
global_opt_out | string | Global Suppression flag [Y or N] | |
variable_data_1 | string | ||
variable_data_2 | string | ||
variable_data_3 | string | ||
variable_data_4 | string | ||
variable_data_5 | string | ||
variable_data_6 | string | ||
variable_data_7 | string | ||
variable_data_8 | string | ||
variable_data_9 | string | ||
variable_data_10 | string | ||
variable_data_11 | string | ||
variable_data_12 | string | ||
variable_data_13 | string | ||
variable_data_14 | string | ||
variable_data_15 | string | ||
variable_data_16 | string | ||
variable_data_17 | string | ||
variable_data_18 | string | ||
variable_data_19 | string | ||
variable_data_20 | string | ||
variable_data_21 | string | ||
variable_data_22 | string | ||
variable_data_23 | string | ||
variable_data_24 | string | ||
variable_data_25 | string | ||
variable_data_26 | string | ||
variable_data_27 | string | ||
variable_data_28 | string | ||
variable_data_29 | string | ||
variable_data_30 | string |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
407 | Draft Workflows cannot be triggered |
408 | Deactivated Workflows cannot be triggered |
409 | Invalid Workflow structure, please contact support |
419 | Workflow not detected |
420 | Unable to parse Workflow Session Variables, please check the syntax and try again |
421 | Email address not provided |
422 | Email address not a valid format |
423 | Reference code is already in use |
424 | Country code is not valid |
425 | Mobile number can only be numerics, 11 digits or 12 including country code |
426 | Global Suppression flag is not Y or N |
430 | User cannot be created due to the User Record Limit applied to this account |
480 | Users email address is on the Realtime Block List |
481 | Users email domain is on the Realtime Block List |
482 | Users email address is on the Application Level Block List |
483 | Users email domain is on the Application Level Block List |
484 | Matching hashed email address found on the Realtime Block List |
490 | Account is disabled, API access denied |
Response Details
{
action: string,TRIGGERED or SKIPPED (based on Start Point frequency controls)
journey_id: integer,Internal ID for triggered Workflow
workflow_description: date,Workflow Description
workflow_status: date,Current Workflow status
user_id: integer,Internal User ID
email_address: string,
reference_code: string
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Trigger workflows in bulk using Lists. Launched Workflows can be post-dated so the triggering doesn't start until a specified date and Reporting Labels can be used to filter workflow reports on a particular launch.
Launch requests will be rejected unless the Workflow is 'active' or is 'paused' and queueing is permitted.
For more information on how Workflow data is processed click here. Note that JSON encoded Session Variables cannot be used with launched workflows.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
workflow_api_identifier | string | Workflow API identifier | * Required |
launch_description | string | Reporting Label | * Required |
launch_date | string | Launch date as YYYY-MM-DD HH:MM:SS | * Required |
user_selection | string | User Selection [ACTIVE or ALL] | * Required |
ignore_global_suppression | string | Ignore Global Suppression for User Selection (when set to ALL) [Y or N] | * Required |
list_api_identifier | string | Comma delimited list of List API Identifiers | * Required |
trigger_rate | integer | Throttle the rate at which Workflows are triggered | |
list_user_selection | string | Choose when Lists are analysed for Active Users. [BUILD_WHEN_QUEUED,BUILD_AT_LAUNCH] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Workflow API Identifier is required |
421 | Specified Workflow could not be detected, please check the API identifier and try again |
422 | Launch Reporting Label is required |
423 | Launch Reporting Label has been used previously, needs to be unique |
424 | Workflow Launch Date is required |
425 | Invalid launch date, please provide in the format YYYY-MM-DD HH:MM:SS |
426 | Invalid throttle rate detected, must be one of [1000, 2000, 3000, 4000, 5000, 10000, 25000, 50000, 100000, 200000, 300000, 400000, 500000] |
427 | User Selection is invalid, must be either ACTIVE or ALL |
428 | List API Identifier is required |
429 | One or more of the supplied List API identifiers are invalid, please check and try again |
430 | Workflow is currently DEACTIVATED and not accepting new requests |
431 | Workflow is currently in a DRAFT state and not ready to accept requests |
432 | One or more of the supplied List API identifiers is not available due to the Data Retention Policy |
433 | Launch cannot be queued as another launch is still being created. |
434 | Launch cannot be queued insufficient credit |
435 | Invalid value for ignore_global_suppression, must be Y or N |
436 | Invalid user selection option - Valid options are [BUILD_WHEN_QUEUED,BUILD_AT_LAUNCH] |
490 | Account is disabled, API access denied |
Response Details
{
launched: boolean,Whether the launch was successful
launch_id: integer,Identifier to access workflow launch details
launch_date: datetime,The date & time the launch is due
workflow_status: date,Current Workflow status
workflow_description: dateWorkflow Description
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Cancel individual Workflow Journeys by providing any of the following:
Journey ID
Workflow API Identifier plus email address
Workflow ID plus email address
To cancel all Workflows relating to a User provide email address only. Optionally set "Reason" as reference when viewing Workflow Journey details within the UI.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
journey_id | integer | Workflow Journey ID | |
workflow_api_identifier | string | Workflow API identifier | |
workflow_id | string | Our internal ID for the Workflow | |
email_address | string | Email Address | |
reason | string | Reason for cancellation |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Email Address is also required when supplying a Workflow API Identifier |
421 | Unable to find Workflow Journey |
422 | Specified Workflow Journey is no longer active |
423 | Unable to find specified User |
424 | Invalid Workflow API Identifier |
425 | Unable to find any active Workflow Journeys for specified User and Workflow |
426 | Email address is required when submitting an API identifier |
427 | No criteria provided |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,
cancelled_workflows: {A collection of cancelled Workflow Journeys in the following format
journey_id: integer,Internal ID for triggered Workflow
workflow_id: integer,Internal ID for the Workflow
workflow_api_identifier: string,
workflow_description: string
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Set a particular workflow status to 'ACTIVE', 'PAUSED' or 'DEACTIVATED'.
- ACTIVE Workflows will accept and process Workflow Trigger requests.
- PAUSED Workflows will stop processing Workflow Actions and queue Workflow Trigger requests until set to 'ACTIVE'.
- DEACTIVATED Workflows will reject any trigger requests and no further Workflow Actions will be processed until set to 'ACTIVE'.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
workflow_api_identifier | string | Workflow API Identifier | * Required |
workflow_status | string |
[ACTIVE, PAUSED, DEACTIVATED]
|
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Workflow not detected |
421 | Workflow API Identifier is required |
422 | Invalid Workflow status - must be either ACTIVE, DEACTIVATED or PAUSED |
490 | Account is disabled, API access denied |
Response Details
{
0: {
success: boolean,
workflow_status: stringWorkflow Status
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Retrieve the details of an individual User's Workflow Journey by providing their Workflow Journey ID.
Workflow Journey ID's are provided when Triggering a Workflow but can also be retrieved from the /automation/workflow_download Activity Report.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
journey_id | integer | Workflow Journey ID | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Workflow Journey not found |
421 | Journey ID must be provided |
490 | Account is disabled, API access denied |
Response Details
{
0: {
user_id: integer,
email_address: string,
journey_label: string,
journey_status: string,[ACTIVE, COMPLETED, IGNORED, CANCELLED, FAILED]
journey_start_date: datetime,Date the Workflow was triggered
journey_last_action_date: datetime,Last date an action was processed
journey_next_action_date: datetime,Next date an action is due to be processed (where applicable)
trigger_source: string,Where the Workflow Journey was triggered from
contacts_workflow_cancel_source: string,If present, where the workflow was cancelled from [UI, WORKFLOW, API]
workflow_api_identifier: string,
workflow_description: string,
workflow_session_variables: string,Raw JSON encoded string of Workflow Session Variables
actions: {Collection of Workflow Actions taken for this Workflow Journey
0: {START action
workflow_action_id: string,Our internal identifier for this Workflow Action
workflow_action_type: string,This will be set to START
cancel_rule: string,Whether other workflows were cancelled
workflow_action_status: string,[COMPLETE, PENDING]
date_completed: datetimeDate the action was completed
}
1: {EMAIL action
workflow_action_id: string,Our internal identifier for this Workflow Action
workflow_action_type: string,This will be set to EMAIL
workflow_action_description: string,
workflow_action_status: string,
date_completed: datetime,
email_details: {
description: string,
subject: string,
email_profile: {
type: string,How the Email Profile was selected [VARIABLE, TEMPLATE]
email_profile_name: string,
email_profile_api_identifier: string,
from_address: string
}
user_engagement: {
opened: string,[Y, N]
first_open: datetime,
clicked: string,[Y, N]
first_click: datetime,
opted_out: string,[Y, N]
first_optout: datetime
}
smtp_log: {
result_code: numeric,SMTP response code
result_message: string,SMTP response message
email_status: string,[BUILDING, QUEUED, DELIVERED, HARD_BOUNCE, SOFT_BOUNCE, IGNORED]
mail_server: stringRecipient mail server
}
}
}...
2: {DELAY action
workflow_action_id: string,Our internal identifier for this Workflow Action
workflow_action_type: string,This will be set to DELAY
workflow_action_description: string,
workflow_action_status: string,
date_completed: datetime,
details: {
offset_type: string,
delay_until: string,When the next action will be processed
offset_source: string,Where the delay information comes from
offset_execution: string,
offset: {
days: integer,
hours: integer,
minutes: integer
}
}
}...
3: {DECISION action
workflow_action_id: string,Our internal identifier for this Workflow Action
workflow_action_type: string,This will be set to DECISION
workflow_action_description: string,
winning_decision: string,Name of the winning Decision path
workflow_action_status: string,
date_completed: datetime
}...
4: {USER_DATA action
workflow_action_id: string,Our internal identifier for this Workflow Action
workflow_action_type: string,This will be set to USER_DATA
workflow_action_description: string,
workflow_action_status: string,
date_completed: datetime,
user_updated: string,Whether User Data was actually updated [Y, N]
changes: {
0: {
field: string,Personalisation field name
type: string,
previous_value: string,The value of the field prior to the update
new_value: string,The value of the field after the update
valid: booleanIf the User update request was valid
}...
}
}...
5: {TAG_USER action
workflow_action_id: string,Our internal identifier for this Workflow Action
workflow_action_type: string,This will be set to TAG_USER
workflow_action_description: string,
workflow_action_status: string,
date_completed: datetime,
added: {Collection of Tag associations created for this User
0: {
type: string,[STATIC, DYNAMIC]
tag_name: string
}...
}
removed: {Collection of Tag associations removed for this User
0: {
type: string,[STATIC, DYNAMIC]
tag_name: string
}...
}
}...
6: {EMAIL_PREFERENCE action
workflow_action_id: string,Our internal identifier for this Workflow Action
workflow_action_type: string,This will be set to EMAIL_PREFERENCE
workflow_action_description: string,
workflow_action_status: string,
date_completed: datetime,
global_optout: {
action: string[NO_CHANGE, SUPPRESS, UNSUPRESS]
}
lists: {
0: {
list_description: string,List Name
type: string,[OPT_IN, OPT_OUT]
previously_subscribed: string[Y, N]
}...
}
}...
7: {WEBHOOK action
workflow_action_id: string,Our internal identifier for this Workflow Action
workflow_action_type: string,This will be set to WEBHOOK
workflow_action_description: string,
workflow_action_status: string,
date_completed: datetime,
request: {Details of the web request
url: string,
status: string,[SENT, FAILED]
response_code: string,HTTP Response Code
response_details: stringHTTP Response Detail (if status FAILED)
}...
}...
8: {NOTIFICATION action
workflow_action_id: string,Our internal identifier for this Workflow Action
workflow_action_type: string,This will be set to NOTIFICATION
workflow_action_description: string,
workflow_action_status: string,
date_completed: datetime,
details: {Notification message details
to: {Collection of To recipients
0: {
name: string,
email_address: string
}...
}
bcc: {Collection of BCC recipients
0: {
name: string,
email_address: string
}...
}
subject: string,
message: string,
email_profile: {Details of the Email Profile used
email_profile_name: string,
email_profile_api_identifier: string,
from_address: string
}
}
}...
9: {END action
workflow_action_id: string,Our internal identifier for this Workflow Action
workflow_action_type: string,This will be set to END
workflow_action_description: string,
workflow_action_status: string,
date_completed: datetime,
workflows: {
triggered: {Collection of triggered Workflows
0: {
workflow_api_identifier: string,
workflow_description: string
}
}
cancelled: {Collected of cancelled Workflows
0: {
workflow_api_identifier: string,
workflow_description: string
}
}
}
}
10: {Action present when contacts_workflow_status is FAILED
workflow_action_type: string,This will be set to FAILED
workflow_action_description: string,
date_cancelled: datetime,Datetime the Workflow Journey was cancelled
reason: stringFailure reason
}
11: {Action present when contacts_workflow_status is CANCELLED
workflow_action_type: string,This will be set to CANCELLED
source: string,Where the workflow was cancelled from [UI, WORKFLOW]
date_cancelled: datetime,Datetime the Workflow Journey was cancelled
workflow_api_identifier: stringIf present, the API Identifier of the Workflow that initiated the cancellation
}
}...
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Add or remove Anonymous Hashes from the Block List by uploading a CSV file containing a single column of email addresses.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
import_mode | string |
[ADDITIONS, DELETIONS]
|
* Required |
import_file | file | Import File | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Import file not found |
422 | Invalid Mode specified - must be either ADDITIONS or DELETIONS |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Generate and add a single anonymous hash onto the Block List using an email address.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
block_email | string | Email Address | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
421 | Invalid email address specified |
422 | Email address is already on the Block List |
423 | Invalid email address format |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Remove a single Anonymous Hash from the Block List using an email address.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
block_email | string | Email Address | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Email Address already matches an Anonymous Hash on the Block List. |
421 | Invalid email address specified |
422 | Hash added by support - removal blocked. |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Search for a particular Anonymous Hash and retrieve details on when and how it was added to the Block List.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
block_email | string | Email Address | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Add or remove domain names from the Block List by uploading a CSV file containing a single column of values.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
import_mode | string |
[ADDITIONS, DELETIONS]
|
* Required |
import_file | file | Import File | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Import file not found |
422 | Invalid Mode specified - must be either ADDITIONS or DELETIONS |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Add a single domain onto the Block List.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
block_domain | string | Domain Name | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
421 | Invalid domain name specified |
422 | Domain name is already on the Block List |
423 | Invalid domain name format |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Remove a single domain name from the Block List.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
block_domain | string | Domain Name | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Domain name not found |
421 | Invalid domain name specified |
422 | Domain added by support - removal blocked |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Search for a particular domain name and retrieve details on when and how it was added to the Block List.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
block_domain | string | Domain Name | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Domain name not found |
421 | Invalid domain name specified |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Export into a zipped one column CSV file.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
date_from | date | Date from as YYYY-MM-DD | |
date_to | date | Date to as YYYY-MM-DD |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
421 | The requested download contains no records |
422 | Invalid date from, please provide in the format YYYY-MM-DD |
423 | Invalid date to, please provide in the format YYYY-MM-DD |
424 | Date From occurs ahead of Date To, please check dates are in the correct order |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Add or remove email addresses from the Block List by uploading a CSV file containing a single column of values.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
import_mode | string |
[ADDITIONS, DELETIONS]
|
* Required |
import_file | file | Import File | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Import file not found |
422 | Invalid Mode specified - must be either ADDITIONS or DELETIONS |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Add a single email address onto the Block List.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
block_email | string | Email Address | * Required |
anonymous_hash | string | Store Email Address as an anonymous hash [Y or N] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
421 | Invalid email address specified |
422 | Email Address already matches an Anonymous Hash on the Block List. |
423 | Invalid email address format |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Remove a single email address from the Block List.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
block_email | string | Email Address | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Email address not found |
421 | Invalid email address specified |
422 | Email address added by support - removal blocked |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Search for a particular email address and retrieve details on when and how it was added to the Block List.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
block_email | string | Email Address | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Export into a zipped one column CSV file.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
date_from | date | Date from as YYYY-MM-DD | |
date_to | date | Date to as YYYY-MM-DD |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
421 | The requested download contains no records |
422 | Invalid date from, please provide in the format YYYY-MM-DD |
423 | Invalid date to, please provide in the format YYYY-MM-DD |
424 | Date From occurs ahead of Date To, please check dates are in the correct order |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get a list of Campaigns and use the results to then request more specific information about individual sends using these requests:
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
campaign_id | integer | Internal Campaign ID | |
campaign_code | string | Campaign Code | |
campaign_description | string | Your Campaign description | |
date_from | date | Date from as YYYY-MM-DD | |
date_to | date | Date to as YYYY-MM-DD | |
campaign_count | integer | Max. results to return, no limit if blank |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No Campaigns detected |
421 | Invalid date from, please provide in the format YYYY-mm-dd |
422 | Invalid date to, please provide in the format YYYY-mm-dd |
423 | Invalid Campaign count, please provide a positive integer |
490 | Account is disabled, API access denied |
Response Details
{
0: {
campaign_id: integer,Internal Campaign ID
campaign_code: string,Campaign Code
campaign_description: string,
campaign_date: date,Delivery date as YYYY-MM-DD HH:MM:SS
social_share_url: string,
thumbnails: {Collection of thumbnail URLs
small: string,
medium: string,
large: string
}
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get a summarised view of all related Campaign metrics using either Campaign ID or Campaign Code.
Use the results to then request more specific information about individual metrics and data using these requests:
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
campaign_id | string | Internal Campaign ID | * Provide one only |
campaign_code | string | Campaign Code | * Provide one only |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Campaign not detected |
421 | Only Campaign ID OR Campaign Code required |
422 | Either Campaign ID or Campaign Code must be provided |
490 | Account is disabled, API access denied |
Response Details
{
0: {
campaign_id: integer,Internal Campaign ID
campaign_code: string,Campaign Code
campaign_description: string,
campaign_date: date,Delivery date as YYYY-MM-DD HH:MM:SS
email_spooler_split_subject: string,Subject - will be "N/A" for Split Test Campaigns
tags: string,CSV string of Spotlight Tags
stats: { 18 items} High-level Campaign metrics
sent: {
value: integer,
percentage: float
}
processing: {
value: integer,
percentage: float
}
delivered: {
value: integer,
percentage: float
}
hard_bounce: {
value: integer,
percentage: float
}
soft_bounce: {
value: integer,
percentage: float
}
undeliverable: {
value: integer,
percentage: float
}
returned_mail: {
value: integer,
percentage: float
}
opens: {
value: integer,
percentage: float
}
total_opens: {
value: integer
}
clicks: {
value: integer,
percentage: float
}
total_clicks: {
value: integer
}
cto_rate: {
value: integer,
percentage: float
}
not_clicked: {
value: integer,
percentage: float
}
spam_reports: {
value: integer,
percentage: float
}
auto_cleansed: {
value: integer,
percentage: float
}
opt_outs: {
value: integer,
percentage: float
}
viewed_online: {
value: integer,
percentage: float
}
conversions: {
value: integer,
percentage: float
}
}
splits: { 8 items} Information for each individual Split (only present for Split Test Campaigns)
email_spooler_split_test_group: string,Split Test group [A,B,C,D,E or REMAINDER]
email_spooler_split_from_address: string,
email_spooler_split_subject: string,
email_spooler_split_percentage: float,
template_id: integer,
template_api_identifier: string,
template_description: string,
stats: { 11 items} High-level Campaign Split
sent: {
value: integer,
percentage: float
}
processing: {
value: integer,
percentage: float
}
delivered: {
value: integer,
percentage: float
}
hard_bounce: {
value: integer,
percentage: float
}
soft_bounce: {
value: integer,
percentage: float
}
opens: {
value: integer,
percentage: float
}
clicks: {
value: integer,
percentage: float
}
opt_outs: {
value: integer,
percentage: float
}
viewed_online: {
value: integer,
percentage: float
}
conversion_count: {
value: integer,
percentage: float
}
conversion_value: {
value: integer,
percentage: float
}
}
}...
links: { 4 items} A collection of link objects in the following format
id: integer,Our internal ID for the Campaign link
url: string,Destination URL for the link click
value: integer,Number of link clicks
percentage: float
}...
lists: { 4 items} A collection of Lists used with the Campaign
list_id: integer,Internal List ID
list_api_identifier: string,List API identifier
list_description: string,List description
list_selected_users: integerNumber of selected Users
}...
conversions: { 5 items} Conversion statistics for the entire Campaign
conversions: string,Total number of Conversions
conversions_unique: string,Number of Users registering a Conversion
conversions_revenue: integer,Total Conversions revenue
conversions_average_value: integer,Average value of Conversions
conversions_revenue_per_email: integerRevenue generated per email sent
}...
optout_categories: { 4 items} Exit survey results from opt-outs
category: string,Exit survey result category
description: string,Exit survey answer description
percentage: integer,Percentage of total opt-outs
value: integerTotal number of opt-outs
}...
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Update existing Campaign details using the 'campaign_id' or 'campaign_code' parameter.
Please note that tags should be seperated by commas.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
campaign_id | string | Internal Campaign ID | * Provide one only |
campaign_code | string | Campaign Code | * Provide one only |
campaign_description | string | Unique Campaign description | |
campaign_tags | string | Tags used for organising content |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Campaign not detected |
421 | Only Campaign ID OR Campaign Code required |
422 | Either Campaign ID or Campaign Code must be provided |
423 | Either Campaign Description or Campaign Tags must be provided |
424 | Campaign description must be unique |
490 | Account is disabled, API access denied |
Response Details
{
campaign_id: integer,Internal Campaign ID
campaign_code: string,Campaign Code
campaign_description: string,
campaign_tags: stringCSV string of Spotlight Tags
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Pass a Campaign ID or Campaign Code to download metrics data for an invidiual Campaign.
Optionally set a date range is required in order to limit the amount of data returned in each request.
Use the export_type parameter to get access to specific data relating to the Campaign.
Valid requests return a compressed ZIP archive in order to reduce transfer times of larger files. Use the optional 'filename' parameter to override the default naming convention of the zip file.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
campaign_id | integer | Internal Campaign ID | * Provide one only |
campaign_code | string | Campaign Code | * Provide one only |
filename | string | Preferred filename | |
export_type | string |
[sent, audit, delivered, hard, soft, returned, opens, clicks, optout, complaints, tracked_replies, cleansed, email_clients, social_shares, clicks_info, clicks_summary, conversions, location, viewed_online, link_scanner, split_test_metrics, cancelled_emails]
|
|
date_from | date | Date from as YYYY-MM-DD only valid for [hard, soft, opt-out, cleansed, complaints] | |
date_to | date | Date to as YYYY-MM-DD only valid for [hard, soft, opt-out, cleansed, complaints] | |
include_split_info | string | Include Split Test info [Y, N], only valid for [audit] |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Campaign could not be located |
421 | Only Campaign ID OR Campaign Code required |
422 | Either Campaign ID or Campaign Code must be provided |
423 | Export type is not valid [sent, audit, delivered, hard, soft, returned, opens, clicks, optout, complaints, tracked_replies, cleansed, email_clients, social_shares, clicks_info, clicks_summary, conversions, location, viewed_online, link_scanner, split_test_metrics, cancelled_emails] |
424 | Your requested download does not contain any records |
425 | Preferred filename is invalid; alpha-numeric, underscores and dashes only |
426 | Date selection is not valid for this export type |
427 | Invalid Date From, please provide in the format YYYY-MM-DD |
428 | Invalid Date To, please provide in the format YYYY-MM-DD |
429 | Date From occurs ahead of Date To, please check your dates are in the correct order |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Compare high-level performance metrics of email Campaigns.
Optionally specify a date range, a maximum number of results or filter by Email Profile to restrict the amount of data to be returned.
If no filter options are specified the 30 most recent Campaigns will be returned.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
date_from | date | Date from as YYYY-MM-DD | |
date_to | date | Date to as YYYY-MM-DD | |
campaign_count | integer | Max. results to return, no limit if blank | |
email_profile_api_identifier | string | Filter by Email Profile API identifier |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No Campaigns detected |
421 | Invalid date from, please provide in the format YYYY-MM-DD |
422 | Invalid date to, please provide in the format YYYY-MM-DD |
423 | Invalid Campaign count, please provide a positive integer |
424 | The Email Profile API identifier is not valid |
490 | Account is disabled, API access denied |
Response Details
{
summary: {An array containing User Tags in the following format
campaign_count: integer,Number of Campaigns included in the comparison
first_date: date,Date of the first Campaign in YYYY-MM-DD
latest_date: date,Date of the latest Campaign in YYYY-MM-DD
stats: { 15 items} An array containing analysis stats for all selected Campaigns
sent: {
value: integer,
percentage: float
}
processing: {
value: integer,
percentage: float
}
delivered: {
value: integer,
percentage: float
}
hard_bounce: {
value: integer,
percentage: float
}
soft_bounce: {
value: integer,
percentage: float
}
undeliverable: {
value: integer,
percentage: float
}
returned_mail: {
value: integer,
percentage: float
}
opens: {
value: integer,
percentage: float
}
clicks: {
value: integer,
percentage: float
}
cto_rate: {
percentage: float
}
not_clicked: {
value: integer,
percentage: float
}
spam_reports: {
value: integer,
percentage: float
}
auto_cleansed: {
value: integer,
percentage: float
}
opt_outs: {
value: integer,
percentage: float
}
viewed_online: {
value: integer,
percentage: float
}
}
}
campaigns: {An array containing multiple Campaign objects in this format
campaign_id: integer,Internal Campaign ID
campaign_description: string,Your Campaign description
campaign_date: date,Scheduled delivery date as YYYY-MM-DD HH:MM:SS
stats: { 15 items} An array containing analysis stats for the Campaign
sent: {
value: integer,
percentage: float
}
processing: {
value: integer,
percentage: float
}
delivered: {
value: integer,
percentage: float
}
hard_bounce: {
value: integer,
percentage: float
}
soft_bounce: {
value: integer,
percentage: float
}
undeliverable: {
value: integer,
percentage: float
}
returned_mail: {
value: integer,
percentage: float
}
opens: {
value: integer,
percentage: float
}
clicks: {
value: integer,
percentage: float
}
cto_rate: {
percentage: float
}
not_clicked: {
value: integer,
percentage: float
}
spam_reports: {
value: integer,
percentage: float
}
auto_cleansed: {
value: integer,
percentage: float
}
opt_outs: {
value: integer,
percentage: float
}
viewed_online: {
value: integer,
percentage: float
}
}
}
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
This request requires at least one Email Template and one List containing active Users to have been created in order to be able to schedule delivery for sending a Campaign.
Campaigns can be sent to multiple Lists and can be specified by separating List API identifiers using a comma within the list_api_identifier parameter.
Valid requests return an internal Campaign ID which can then be used to track and report on the Campaign once delivery has started.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
template_api_identifier | string | Template API Identifier | * Required |
list_api_identifier | string | Separate using commas | * Required |
suppression_lists | string | Separate API Identifiers using commas | |
campaign_code | string | Unique Campaign Code | * Required |
campaign_label_api_identifier | string | Campaign Label API Identifier | |
campaign_description | string | Unique Campaign Description | * Required |
campaign_date | datetime | Delivery date & time as YYYY-MM-DD HH:MM:SS | |
throttle_rate | integer | Throttle the rate at which emails are delivered | |
intelligent_sending_delay | integer | Set a delay before dormant users are queued [60,120,180,240,300] | |
use_delivery_windows | string | Restrict Email delivery attempts to configured windows. [Y,N] | |
list_user_selection | string | Choose when Lists are analysed for Active Users. [BUILD_WHEN_QUEUED,BUILD_AT_DELIVERY] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Template not found |
421 | Invalid date from, please provide in the format YYYY-MM-DD |
422 | Invalid date to, please provide in the format YYYY-MM-DD |
423 | Delivery date is required |
424 | The Email Profile API identifier is not valid |
425 | Campaign description must be provided |
426 | Campaign description must be unique |
427 | One or more of the List API identifiers are invalid, please check and try again |
428 | Campaign Code is required |
429 | Campaign Code must be unique |
430 | Template contains critical errors Campaign cannot be queued |
431 | Campaign frequency rules exceeded |
432 | Invalid throttle rate specified |
433 | One or more of the Suppression List API identifiers are invalid, please check and try again |
434 | Template is still pending validation. Campaign cannot be queued |
435 | One or more of the List API identifiers is not available based on the Data Retention Policy. |
436 | One or more of the Suppression List API identifiers is not available based on the Data Retention Policy. |
437 | Template contains Double Opt-in merge tag. Campaign cannot be queued. |
438 | Insufficient Credit on account campaign cannot be queued. |
439 | Campaign scheduler process is currently busy, please try again shortly. |
440 | Campaign Label API Identifer is required. |
441 | Campaign Label API Identifier is not valid. |
442 | Campaign Labels are disabled for this account. |
443 | Campaign Label API Identifier is disabled. |
444 | Delivery Windows are not enabled. |
445 | Invalid user selection option - Valid options are [BUILD_WHEN_QUEUED,BUILD_AT_DELIVERY] |
490 | Account is disabled, API access denied |
Response Details
{
queued: boolean,Whether the Campaign was successfully queued
campaign_id: integer,ID of queued Campaign if successful
error_message: stringAdditional feedback if the Campaign can't be queued
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Request to reschedule the delivery time of a future Campaign. Once delivery has started the Campaign cannot be rescheduled.
Campaign settings cannot be changed until the Campaign has been fully built and queued for delivery.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
campaign_id | string | Internal Campaign ID | * Provide one only |
campaign_code | string | Campaign Code | * Provide one only |
campaign_reschedule_date | datetime | Delivery date & time as YYYY-MM-DD HH:MM:SS | |
throttle_rate | integer | Throttle the rate at which emails are delivered | |
use_delivery_windows | string | Restrict Email delivery attempts to configured windows. [Y,N] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Campaign not detected |
421 | Only Campaign ID OR Campaign Code required |
422 | Either Campaign ID or Campaign Code must be provided |
424 | Campaign is already being delivered |
426 | Valid Throttle Rate must be provided |
428 | Invalid Campaign reschedule date, please provide in the format YYYY-MM-DD HH:MM:SS |
429 | Delivery Windows are not enabled. |
490 | Account is disabled, API access denied |
Response Details
{
rescheduled: boolean,Whether the Campaign was successfully rescheduled
campaign_id: integerInternal Campaign ID
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Request the cancellation of a Campaign Queued for delivery. Once delivery has started the Campaign cannot be cancelled.
Cancellation cannot be requested until the Campaign has been fully built and Queued for delivery.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
campaign_id | string | Internal Campaign ID | * Provide one only |
campaign_code | string | Campaign Code | * Provide one only |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Campaign not detected |
421 | Only Campaign ID OR Campaign Code required |
422 | Either Campaign ID or Campaign Code must be provided |
423 | Campaign is still being built and queued |
424 | Campaign is already being delivered |
490 | Account is disabled, API access denied |
Response Details
{
campaign_id: integer,Internal Campaign ID
campaign_code: string,Campaign Code
campaign_description: string,
cancelled: booleanWhether the Campaign was successfully cancelled
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
This request requires at least one Email Template and one List containing active Users to have been created in order to be able to schedule delivery for sending a Split Test Campaign.
Split Test Campaigns can be sent to multiple Lists and can be specified by separating List API identifiers using a comma within the list_api_identifier parameter.
Valid requests return an internal Campaign ID which can then be used to track and report on the Campaign once delivery has started.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
campaign_code | string | Unique Campaign Code | * Required |
campaign_description | string | Unique Campaign description | * Required |
list_api_identifier | string | Separate using commas | * Required |
split_delivery_times | string | Per-split delivery times [N,Y] | * Required |
campaign_date | datetime | Delivery date & time for all Splits as YYYY-MM-DD HH:MM:SS | |
throttle_rate | integer | Throttle the rate at which emails are delivered | * Required |
winning_split_size | integer | Winning Split percentage | |
winning_split_selection | string |
[OPENS, CLICKS, CONVERSIONS_COUNT, CONVERSION_VALUE, NO_WINNER]
|
|
winning_split_selection_period | string | Select winner after period e.g. 1 HOUR or 3 DAY | |
split_1_api_identifier | string | Split 1 - Template API Identifier | * Required |
split_1_subject | string | Split 1 - Subject Line | |
split_1_delivery | datetime | Split 1 - Delivery date & time as YYYY-MM-DD HH:MM:SS | |
split_2_api_identifier | string | Split 2 - Template API Identifier | * Required |
split_2_subject | string | Split 2 - Subject Line | |
split_2_delivery | datetime | Split 2 - Delivery date & time as YYYY-MM-DD HH:MM:SS | |
split_3_api_identifier | string | Split 3 - Template API Identifier | |
split_3_subject | string | Split 3 - Subject Line | |
split_3_delivery | datetime | Split 3 - Delivery date & time as YYYY-MM-DD HH:MM:SS | |
split_4_api_identifier | string | Split 4 - Template API Identifier | |
split_4_subject | string | Split 4 - Subject Line | |
split_4_delivery | datetime | Split 4 - Delivery date & time as YYYY-MM-DD HH:MM:SS | |
split_5_api_identifier | string | Split 5 - Template API Identifier | |
split_5_subject | string | Split 5 - Subject Line | |
split_5_delivery | datetime | Split 5 - Delivery date & time as YYYY-MM-DD HH:MM:SS |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
421 | Campaign description must be provided |
422 | Campaign description must be unique |
423 | List API identifier must be provided |
424 | One or more of the List API identifiers are invalid, please check and try again |
425 | Per-split delivery times must be Y or N |
426 | campaign_date cannot be set when using per-split delivery times, please use split_N_delivery |
427 | campaign_date must be provided |
428 | Invalid delivery date & time, please provide in the format YYYY-MM-DD HH:MM:SS |
429 | campaign_date cannot be set when using per-split delivery times, please use split_N_delivery |
430 | winning_split_selection should be one of [OPENS, CLICKS, CONVERSIONS_COUNT, CONVERSION_VALUE, NO_WINNER] |
431 | winning_split_size cannot be provided with winning_split_selection set to NO_WINNER |
432 | winning_split_selection_period cannot be provided with winning_split_selection set to NO_WINNER |
433 | winning_split_size must be between 10 and 90 |
434 | winning_split_selection_period must be in a valid format e.g. 3 HOUR or 2 DAY |
435 | Template not found for API identifier on Split #N |
436 | Per-split delivery date & time not valid for Split #N, please provide in the format YYYY-MM-DD HH:MM:SS |
437 | Details need to be provided for Split #1 and Split #2 |
438 | Campaign Code must be provided |
439 | Campaign Code must be unique |
440 | Per split delivery date provided for split N, option not allowed when split_delivery_times = N |
441 | Campaign frequency rules exceeded |
442 | Invalid throttle rate specified |
443 | One or more of the List API identifiers is not available based on the Data Retention Policy. |
444 | Template for split #N contains Double Opt-in merge tag. Campaign cannot be queued |
445 | Template for split #N contains critical errors. Campaign cannot be queued |
446 | Template for split #N is still pending validation. Campaign cannot be queued |
447 | The Device & Location Identification setting on each splits Email Profile must match |
490 | Account is disabled, API access denied |
Response Details
{
queued: boolean,Whether the Campaign was successfully queued
campaign_id: integer,ID of queued Campaign if successful
error_message: stringAdditional feedback if the Campaign can't be queued
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Access User engagement data for click and open activity.
Report on specific Campaigns using either Campaign ID or Campaign Code or specify a date range that spans a maximum of 31 days.
Valid requests return a compressed ZIP archive in order to reduce transfer times of larger files. Use the optional 'filename' parameter to override the default naming convention of the zip file.
Please Note: Workflow Emails are not included, use this request to access Workflow Email engagement data.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
campaign_code | string | Campaign Code | |
campaign_id | string | Internal Campaign ID | |
date_from | datetime | Date from as YYYY-MM-DD HH:MM:SS | |
date_to | datetime | Date to as YYYY-MM-DD HH:MM:SS | |
type | string |
[CLICKS, CLICKS_SUMMARY, CLICKS_LINKS, OPENS]
|
|
include_contacts_data | string | Include User Profile & Custom Fields [Y, N] | |
include_extended_data | string | Include extended Campaign meta data [Y, N] |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No engaged Users could be located using the currently selected criteria |
421 | Invalid date from, please provide in the format YYYY-MM-DD HH:MM:SS |
422 | Invalid date to, please provide in the format YYYY-MM-DD HH:MM:SS |
423 | Date From occurs ahead of Date To, please check your dates are in the correct order |
424 | Invalid type specified - needs to be OPENS, CLICKS, CLICKS_SUMMARY or CLICKS_LINKS |
425 | Date range is greater than 31 days, please adjust accordingly |
426 | The Account API identifier is not valid |
427 | Preferred filename is invalid; alpha-numeric, underscores and dashes only |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Access User engagement data for a specified period, the maximum period that can be downloaded per request is 24 Hours.
The engagement feed data can be downloaded for the last 30 days.
Valid requests return a compressed ZIP archive in order to reduce transfer times of larger files. Use the optional 'filename' parameter to override the default naming convention of the zip file.
The engagement data feed file contains the following information:
- Unique Event ID
- Event Date & Time
- Type of Event (Open, Click, Opt-out, Auto-cleanse)
- Users Email Address
- Users Reference Code
- Event Data encoded using JSON
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
date_from | datetime | Date from as YYYY-MM-DD HH:MM:SS | |
date_to | datetime | Date to as YYYY-MM-DD HH:MM:SS | |
filename | string | Preferred filename |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No engaged Users could be located using the currently selected criteria |
421 | Invalid date from, please provide in the format YYYY-MM-DD HH:MM:SS |
422 | Invalid date to, please provide in the format YYYY-MM-DD HH:MM:SS |
423 | Date From occurs ahead of Date To, please check your dates are in the correct order |
425 | Maximum permitted reporting period is 24 Hours |
427 | Preferred filename is invalid; alpha-numeric, underscores and dashes only |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Access individual Email Profile details using either 'email_profile_name' or 'email_profile_api_identifier' parameters.
To return a complete list of all Email Profiles leave optional parameters blank.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_profile_name | string | Email Profile name | |
email_profile_api_identifier | string | Email Profile API Identifier |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
404 | No Email Profiles found |
490 | Account is disabled, API access denied |
Response Details
{
email_profile_name: string,Email Profile Name
email_profile_api_identifier: string,Email Profile API Identifier
virtual_mta: string,Virtual MTA
from_name: string,From Name
from_address: string,From Email Address
reply_name: string,Reply Name
reply_address: string,Reply Email Address
reply_autoresponder_template_id: string,Template ID of Autoresponder
to_name_mask: string,To Name Mask
click_tracking_domain: string,Tracking Domain
auto_tag_web_metrics: string,Auto-tag Web Metrics
conversion_tracking: string,Conversion Tracking
conversion_tracking_key: string,Conversion Tracking Key
auto_tag_custom_parameters: string,Auto-tag Custom Parameters
reply_tracking: string,Reply Tracking
inbound_forwarding_address: string,Inbound Forwarding Address
exit_survey: string,Include Exit Survey
feedback_link: string,Include Feedback Link
optout_enforced: string,Enforce Opt-out tag
optout_email_content_html: string,HTML Opt-out content
optout_email_content_text: string,Text Opt-out content
optout_level: string,Opt-out Level
custom_optout_page: stringCustom Opt-out Landing Page
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Create new Email Profiles or updating existing using the 'email_profile_name' or 'email_profile_api_identifier' parameters.
When using the 'email_profile_api_identifier' parameter please note that when the value is not matched to an existing Email Profile a new item will be created.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_profile_name | string | Email Profile Name | * Required on create |
email_profile_api_identifier | string | Email Profile API Identifier | * Required |
email_profile_active | string | Email Profile Active [Y,N] | |
from_name | string | From Name | * Required on create |
from_address | string | From Email Address | * Required on create |
reply_name | string | Reply Name | * Required on create |
reply_address | string | Reply Email Address | * Required on create |
to_name_mask | string | To Name Mask | |
virtual_mta | string | Virtual MTA | |
click_tracking_domain | string | Tracking Domain | |
auto_tag_web_metrics | string | [DISABLED, GOOGLE_ANALYTICS] | |
auto_tag_custom_parameters | string | Auto-tag Custom Parameters | |
conversion_tracking | string | Conversion Tracking [Y,N] | |
conversion_tracking_key | string | Conversion Tracking Key | |
reply_tracking | string | Reply Tracking [Y,N] | |
inbound_forwarding_address | string | Inbound Forwarding Address | |
optout_enforced | string | Enforce Opt-out Tag [ENFORCED,OPTIONAL] | |
optout_email_content_html | string | HTML Opt-out Content | |
optout_email_content_text | string | Text Opt-out Content | |
optout_level | string | Opt-out Level [GLOBAL,LIST] | |
custom_optout_page | string | Custom Opt-out Landing Page | |
exit_survey | string | Include Exit Survey [Y,N] | |
feedback_link | string | Include Feedback Link [Y,N] | |
email_profile_type | string | Mail type [ALL, MARKETING, TRANSACTIONAL] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
421 | Email Profile API Identifier not provided |
422 | Email Profile Name not provided |
423 | Email Profile Name cannot be blank |
424 | Email Profile Name must be unique |
425 | From Name not provided |
426 | From Name cannot be blank |
427 | From Email Address not provided |
428 | From Email Address cannot be blank |
429 | From Email Address is not a valid email address |
430 | Reply Name not provided |
431 | Reply Name cannot be blank |
432 | Reply Email Address not provided |
433 | Reply Email Address cannot be blank |
434 | Reply Email Address is not a valid email address |
435 | Tracking Domain cannot be blank |
436 | Tracking Domain is not permitted |
437 | Conversion Tracking must be either Y or N |
438 | Conversion Tracking Key cannot be blank |
439 | Precedence Bulk Header must be either Y or N |
440 | Recipient Valid Since Header must be either Y or N |
441 | Auto Tag Web Metrics must be either DISABLED or GOOGLE_ANALYTICS |
443 | Opt-out preference Level must be either GLOBAL or LIST |
444 | Opt-out Enforced must be either ENFORCED or OPTIONAL |
445 | Primary content opt-out link tags malformed or missing |
446 | Alternative content opt-out link tags malformed or missing |
447 | Reply Email Address must be a genuine email address on a different domain to the From Email Address |
448 | Reply Email Address cannot be the same as the From Email Address used in other Email Profiles |
449 | Inbound forwarding - remote email address is not valid |
450 | Invalid Virtual MTA specified, please check and try again |
451 | No default Virtual MTA configured, please specify a Virtual MTA to be used |
452 | Tracking Domain authentication details are invalid |
453 | Send Domain authentication details are invalid |
454 | From Email Address is not permitted |
455 | Virtual MTA is not permitted |
456 | Exit Survey must be either Y or N |
457 | Feedback Link must be either Y or N |
458 | Inbound Forwarding Address cannot be used - [Error Description] |
459 | Email Profile Active must be either Y or N |
460 | Inbound Forwarding - Unable to remove Application-level Forwarding Address |
490 | Account is disabled, API access denied |
Response Details
{
email_profile_name: string,Email Profile Name
email_profile_api_identifier: string,Email Profile API Identifier
virtual_mta: string,Virtual MTA
from_name: string,From Name
from_address: string,From Email Address
reply_name: string,Reply Name
reply_address: string,Reply Email Address
reply_autoresponder_template_id: string,Template ID of Autoresponder
to_name_mask: string,To Name Mask
click_tracking_domain: string,Tracking Domain
auto_tag_web_metrics: string,Auto-tag Web Metrics
conversion_tracking: string,Conversion Tracking
conversion_tracking_key: string,Conversion Tracking Key
auto_tag_custom_parameters: string,Auto-tag Custom Parameters
reply_tracking: string,Reply Tracking
inbound_forwarding_address: string,Inbound Forwarding Address
exit_survey: string,Include Exit Survey
feedback_link: string,Include Feedback Link
optout_enforced: string,Enforce Opt-out tag
optout_email_content_html: string,HTML Opt-out content
optout_email_content_text: string,Text Opt-out content
optout_level: string,Opt-out Level
custom_optout_page: stringCustom Opt-out Landing Page
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Pass a valid 'email_profile_api_identifier' to delete an existing Email Profile.
Email Profiles can only be deleted where they have not been used to send email either through Campaigns or Workflows.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_profile_api_identifier | string | Email Profile API Identifier |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Email Profile not found |
421 | Email Profile API Identifier not provided |
422 | Cannot delete Email Profile as it has been used to send emails |
490 | Account is disabled, API access denied |
Response Details
{
success: booleanTrue when the Email Profile has been deleted
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Import Users for suppression within an Email Profile Suppression using the 'email_profile_api_identifier' parameter.
Adding users to the Suppression List will also create a new User if the Email address has not previously been added using a List or API.
Faster Imports
Try zipping CSV file uploads to speed up import processing time.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_profile_api_identifier | string | API identifier | * Required |
import_action | string | Import Action - ADD or REMOVE | * Required |
import_file | file | CSV file of Users | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Email Profile not found |
421 | No Email Profile API Identifier specified |
422 | Import File not found |
423 | import_action is required (ADD or REMOVE) |
430 | Email Profile Suppression is not enabled |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Check if a User is suppressed by an Email Profile using the 'email_profile_api_identifier' parameter.
Users can be searched for by email address or reference code.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_profile_api_identifier | string | API identifier | * Required |
email_address | string | Email address | * Provide one only |
reference_code | string | Unique Reference Code | * Provide one only |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Email Profile Suppression not found |
421 | No Email Profile API Identifier specified |
422 | User not found |
423 | Email address or reference code is required |
424 | Only ONE of email address or reference code is required |
425 | Email address not valid |
426 | Email Profile not found |
430 | Email Profile Suppression is not enabled |
490 | Account is disabled, API access denied |
Response Details
{
email_profile_api_identifier: string,Email Profile API Identifier
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
global_opt_out: string,Global Suppression active [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
global_opt_out_source: string,[ADMIN, API, AUTOCLEANSED, IMPORT, UNSUBSCRIPTION]
profile_suppression_date: date,In the format YYYY-MM-DD HH:MM:SS
profile_suppression_source: string[IMPORT, CAMPAIGN, WORKFLOW]
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Pass an Email Profile API identifier to download all suppressed Users.
Describe the columns required for the CSV file export using the 'field_map_api_identifier' parameter - more info on Field Maps can be found here.
A date range can optionally be provided to allow incremental data downloads for more effecient processing when integrating with other applications.
Valid requests return a compressed ZIP archive in order to reduce transfer times of larger files. Use the optional 'filename' parameter to override the default naming convention of the zip file.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_profile_api_identifier | string | API identifier | * Required |
field_map_api_identifier | string | Field Map API Identifier | * Required |
filename | string | Preferred filename | |
date_from | date | Date from as YYYY-MM-DD | |
date_to | date | Date to as YYYY-MM-DD |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Email Profile not found |
421 | No Email Profile API Identifier specified |
423 | Field Map API identifier is required when requesting exports |
424 | Unknown Field Map API Identifier |
425 | Invalid date from, please provide in the format YYYY-MM-DD |
426 | Invalid date to, please provide in the format YYYY-MM-DD |
427 | Date From occurs ahead of Date To, please check your dates are in the correct order |
428 | Preferred filename is invalid; alpha-numeric, underscores and dashes only |
430 | Email Profile Suppression is not enabled |
431 | The requested download contains no Users |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Suppress a User within an Email Profile by email address.
New Users can be created with the /users/add_or_update endpoint.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_profile_api_identifier | string | API identifier | * Required |
email_address | string | Email address | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
421 | No Email Profile API Identifier specified |
422 | Email Profile not found |
423 | No Email Address Provided |
430 | Email Profile Suppression is not enabled |
490 | Account is disabled, API access denied |
Response Details
{
email_profile_api_identifier: string,Email Profile API Identifier
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
global_opt_out: string,Global Suppression active [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
global_opt_out_source: string,[ADMIN, API, AUTOCLEANSED, IMPORT, UNSUBSCRIPTION]
profile_suppression_date: date,In the format YYYY-MM-DD HH:MM:SS
profile_suppression_source: string[IMPORT, CAMPAIGN, WORKFLOW]
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Check if a User is suppressed by an Email Profile Suppression using the 'email_profile_api_identifier' parameter.
Users are matched on email address.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_profile_api_identifier | string | API identifier | * Required |
email_address | string | Email address | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Email Profile Suppression not found |
421 | No Email Profile API Identifier specified |
422 | User not found |
423 | Email address not provided |
424 | Email Profile not found |
430 | Email Profile Suppression is not enabled |
490 | Account is disabled, API access denied |
Response Details
{
status: stringRequest result [DELETED, FAILED]
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get a list of Field Maps and related API identifers. Use the results to then request more specific information about individual Field Maps.
All system and custom Field Maps with API Identifiers are returned by the request.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
490 | Account is disabled, API access denied |
Response Details
{
0: {
field_map_api_identifier: string,Email Profile Name
field_map_name: stringEmail Profile API Identifier
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get a complete view of how an individual Field Map is configured by passing the API identifier.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
field_map_api_identifier | string | Field Map API Identifier | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Field Map not found |
490 | Account is disabled, API access denied |
Response Details
{
field_map_name: string,Field Map Name
field_map_api_identifier: string,Field Map API Identifier
include_headers: string,Ignore first row [Y or N]
field_delimeter: string,Field delimiter [COMMA or PIPE]
field_map: {
id: string,Field ID
description: string,Field Description
length: string,Maximum Field length
info: string,Additional Field Information
example: string,
field_index: integerField Position
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get a complete view of how an individual Field Map is configured by passing the API identifier.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
field_map_api_identifier | string | Field Map API Identifier | * Required |
field_map_name | string | Field Map Description | * Required |
include_headers | string | [Y, N] | |
field_delimeter | string | [COMMA, PIPE] | |
field_map | string | CSV String of Fields | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
421 | Field Map API Identifier is required |
422 | Field Map API Identifier is reserved for system use |
423 | Field Map API Identifier already being used |
424 | Field delimiter must be COMMA or PIPE |
425 | Include Headers must be Y or N |
426 | Field Map must be a CSV string with at least one field |
427 | Field Map contains invalid field name [FIELD_NAME] |
428 | Field Map contains field [FIELD_NAME] multiple times |
429 | Field Map name is required |
430 | Field Map name must be unique |
490 | Account is disabled, API access denied |
Response Details
{
field_map_name: string,Field Map Name
field_map_api_identifier: string,Field Map API Identifier
include_headers: string,Ignore first row [Y or N]
field_delimeter: string,Field delimiter [COMMA or PIPE]
field_map: {
id: string,Field ID
description: string,Field Description
length: string,Maximum Field length
info: string,Additional Field Information
example: string,
field_index: integerField Position
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Pass a Form API ID to download session data for a form.
Optionally set a date range in order to limit the data returned in each request.
Valid requests return a compressed ZIP archive in order to reduce transfer times of larger files. Use the optional 'filename' parameter to override the default naming convention of the zip file.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
form_api_identifier | string | Form API Identifier | * Required |
date_from | date | Date from as YYYY-MM-DD only | |
date_to | date | Date to as YYYY-MM-DD only | |
export_type | string |
[SESSIONS, SUBMITTED]
|
|
filename | string | Preferred filename |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Form not found |
421 | Invalid date from, please provide in the format YYYY-MM-DD |
422 | Invalid date to, please provide in the format YYYY-MM-DD |
423 | Invalid export type, please specify SESSIONS or SUBMITTED |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get the details of a List then use the results to then update the details or download related data using additional List endpoints.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
list_api_identifier | string | API identifier | |
list_description | string | Unique description | |
list_source_tag | string | Source Tag | |
list_status | string | [VISIBLE, HIDDEN, ALL] | |
include_expired | string | [Y,N] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | List not found |
420 | No search parameter specified |
421 | Too many parameters - only one search parameter should be specified per request |
422 | Invalid List Status provided, must be either VISIBLE, HIDDEN or ALL |
490 | Account is disabled, API access denied |
Response Details
{
0: {
list_id: integer,
list_api_identifier: string,
list_description: string,
list_status: string,
list_source_tag: string,
list_created_date: datetime,YYYY-MM-DD HH:MM:SS
list_modified_date: datetime,YYYY-MM-DD HH:MM:SS
list_last_used_date: datetime,YYYY-MM-DD HH:MM:SS
list_total_users: integer,
list_opt_outs: integer,
list_global_opt_outs: integer,
list_active_users: integer,Total number of Active Users
list_campaign_analysis_count: integer,# of most recent Campaigns used to generate list_campaign_analysis data
list_tags: string,Tags used for organising content
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get Field Name Labels.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
490 | Account is disabled, API access denied |
Response Details
{
custom_field_1: String,Custom Field #1
custom_field_2: String,Custom Field #2
custom_field_3: String,Custom Field #3
custom_field_4: String,Custom Field #4
custom_field_5: String,Custom Field #5
custom_field_6: String,Custom Field #6
custom_field_7: String,Custom Field #7
custom_field_8: String,Custom Field #8
custom_field_9: String,Custom Field #9
custom_field_10: String,Custom Field #10
custom_field_11: String,Custom Field #11
custom_field_12: String,Custom Field #12
custom_field_13: String,Custom Field #13
custom_field_14: String,Custom Field #14
custom_field_15: String,Custom Field #15
custom_field_16: String,Custom Field #16
custom_field_17: String,Custom Field #17
custom_field_18: String,Custom Field #18
custom_field_19: String,Custom Field #19
custom_field_20: String,Custom Field #20
custom_field_21: String,Custom Field #21
custom_field_22: String,Custom Field #22
custom_field_23: String,Custom Field #23
custom_field_24: String,Custom Field #24
custom_field_25: String,Custom Field #25
custom_field_26: String,Custom Field #26
custom_field_27: String,Custom Field #27
custom_field_28: String,Custom Field #28
custom_field_29: String,Custom Field #29
custom_field_30: StringCustom Field #30
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Set Field Name Labels.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
custom_field_1 | string | Custom Field #1 | |
custom_field_2 | string | Custom Field #2 | |
custom_field_3 | string | Custom Field #3 | |
custom_field_4 | string | Custom Field #4 | |
custom_field_5 | string | Custom Field #5 | |
custom_field_6 | string | Custom Field #6 | |
custom_field_7 | string | Custom Field #7 | |
custom_field_8 | string | Custom Field #8 | |
custom_field_9 | string | Custom Field #9 | |
custom_field_10 | string | Custom Field #10 | |
custom_field_11 | string | Custom Field #11 | |
custom_field_12 | string | Custom Field #12 | |
custom_field_13 | string | Custom Field #13 | |
custom_field_14 | string | Custom Field #14 | |
custom_field_15 | string | Custom Field #15 | |
custom_field_16 | string | Custom Field #16 | |
custom_field_17 | string | Custom Field #17 | |
custom_field_18 | string | Custom Field #18 | |
custom_field_19 | string | Custom Field #19 | |
custom_field_20 | string | Custom Field #20 | |
custom_field_21 | string | Custom Field #21 | |
custom_field_22 | string | Custom Field #22 | |
custom_field_23 | string | Custom Field #23 | |
custom_field_24 | string | Custom Field #24 | |
custom_field_25 | string | Custom Field #25 | |
custom_field_26 | string | Custom Field #26 | |
custom_field_27 | string | Custom Field #27 | |
custom_field_28 | string | Custom Field #28 | |
custom_field_29 | string | Custom Field #29 | |
custom_field_30 | string | Custom Field #30 |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
490 | Account is disabled, API access denied |
Response Details
{
custom_field_1: String,Custom Field #1
custom_field_2: String,Custom Field #2
custom_field_3: String,Custom Field #3
custom_field_4: String,Custom Field #4
custom_field_5: String,Custom Field #5
custom_field_6: String,Custom Field #6
custom_field_7: String,Custom Field #7
custom_field_8: String,Custom Field #8
custom_field_9: String,Custom Field #9
custom_field_10: String,Custom Field #10
custom_field_11: String,Custom Field #11
custom_field_12: String,Custom Field #12
custom_field_13: String,Custom Field #13
custom_field_14: String,Custom Field #14
custom_field_15: String,Custom Field #15
custom_field_16: String,Custom Field #16
custom_field_17: String,Custom Field #17
custom_field_18: String,Custom Field #18
custom_field_19: String,Custom Field #19
custom_field_20: String,Custom Field #20
custom_field_21: String,Custom Field #21
custom_field_22: String,Custom Field #22
custom_field_23: String,Custom Field #23
custom_field_24: String,Custom Field #24
custom_field_25: String,Custom Field #25
custom_field_26: String,Custom Field #26
custom_field_27: String,Custom Field #27
custom_field_28: String,Custom Field #28
custom_field_29: String,Custom Field #29
custom_field_30: StringCustom Field #30
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Create new Lists or updating existing using the 'list_api_identifier' parameter.
When using the 'list_api_identifier' parameter please note that when the value is not matched to an existing List a new item will be created.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
list_api_identifier | string | List API identifier | * Required |
list_description | string | Description | * Required |
list_source_tag | string | Campaign analysis tag | |
list_usage_type | string | [UNLIMITED, LIMITED] | |
list_usage_limit | integer | Max. usage threshold | |
list_status | string | [ACTIVE, ARCHIVED] | |
list_tags | string | Tags used for organising content |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No API identifier specified |
421 | Description is required |
422 | Description already in use |
423 | Source Tag is required |
424 | Usage Type must be either UNLIMITED or LIMITED |
425 | When list_usage_type is LIMITED limit is required |
426 | Status must be either ACTIVE or ARCHIVED |
427 | List no longer available due to Data Retention Policy |
490 | Account is disabled, API access denied |
Response Details
{
0: {
action: string,[CREATED, UPDATED]
list_id: integer,
list_api_identifier: string,
list_description: string,
list_source_tag: string,
list_usage_type: string,[UNLIMITED, LIMITED]
list_usage_limit: integer,
list_status: string,[ACTIVE, ARCHIVED]
list_tags: string
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Import Users onto a List and set opt-in as active. Lists are identified using the 'list_api_identifier' parameter.
The default processing behaviour for Users that are found to already exist on the List is to honour their current preference. e.g. If they were previously set to opt-out and they are imported they will remain that way unless you set the 'import_resubscribe' flag in the request to 'Y'.
Describe the columns of the uploaded CSV file using the 'field_map_api_identifier' parameter - more info on Field Maps can be found here.
To import Users onto the Seed List set the API identifier to 'SEED_LIST'.
Faster Imports
Try zipping CSV file uploads to speed up import processing time.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
list_id | string | Internal ID of the list | * Provide one only |
list_api_identifier | string | API identifier of the List | * Provide one only |
field_map_api_identifier | string | Field Map API Identifier | * Required |
import_resubscribe | string | Force opt-in preference - Y or N | * Required |
run_automation | string | Run Automation Triggers - Y or N | * Required |
import_file | file | CSV file of Users | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | List identifier not matched to an existing List |
421 | No List API Identifier specified |
422 | Import File not found |
423 | import_resubscribe is required (Y or N) |
424 | Field Map API Identifier is required |
425 | Unknown Field Map API Identifier |
426 | Cannot use GLOBAL_SUPPRESSION here |
427 | List no longer available due to Data Retention Policy |
428 | List contains no data |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Import Users onto a List and set the preference as opt-out so they will no longer receive an email when the List is used. Lists are identified using the 'list_api_identifier' parameter.
The default processing behaviour for Users that do not already exist on the List is to ignore the records. This can be overriden by setting the 'import_create_nonexistent' parameter to 'Y', when this is done non-existent Users will be created and then opt-out will be set instantly.
Describe the columns of the uploaded CSV file using the 'field_map_api_identifier' parameter - more info on Field Maps can be found here.
To import Users onto the Global Suppression List to stop Users from receiving any further emails regardless of what Lists they are on, set the API identifier to 'GLOBAL_SUPPRESSION'.
Faster Imports
Try zipping CSV file uploads to speed up import processing time.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
list_id | string | Internal ID of the list | * Provide one only |
list_api_identifier | string | API identifier of the List | * Provide one only |
field_map_api_identifier | string | Field Map API Identifier | * Required |
import_create_nonexistent | string | Create non-existent Users - Y or N | * Required |
import_file | file | CSV import file | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | List not found |
421 | No List API Identifier specified |
422 | Unknown Field Map API Identifier |
423 | import_create_nonexistent is required (Y or N) |
424 | Field Map API Identifier is required |
425 | Unknown Field Map API Identifier |
426 | Reserved list API identifier SEED_LIST cannot be used here |
427 | List no longer available due to Data Retention Policy |
428 | List contains no data |
490 | Account is disabled, API access denied |
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Set the preference for a User on a specified List. Preference can be set to opt-in or opt-out.
When set to opt-in the User will receive an email each time the List is used to send a Campaign.
Users that are set to opt-out will receive no further emails when the List is used to send a Campaign.
Specify the details of the User and the List using email address (or reference code) and a List API identifier respectively.
Where a User does exist on the specified List they will be added automatically and the preference set accordingly.
To add Users to the Seed List use the API identifier "SEED_LIST".
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Provide one only |
reference_code | string | Reference code | * Provide one only |
list_api_identifier | string | List API identifier | * Required |
subscribed | string | Opt-in preference active [Y or N] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
420 | Either email address or reference code must be provided |
421 | Only ONE of email address or reference code is required |
422 | Email address not valid |
423 | List API identifier is not valid |
424 | Invalid opt-in preference must Y or N] |
429 | List no longer available due to Data Retention Policy |
480 | Users email address is on the Realtime Block List |
481 | Users email domain is on the Realtime Block List |
482 | Users email address is on the Application Level Block List |
483 | Users email domain is on the Application Level Block List |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique Reference Code
global_opt_out: string,Global Suppression from all emails [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
list_api_identifier: string,List API identifier
list_description: string,List name
subscribed: string,Opt-in preference active [Y,N]
subscribe_date: date,In the format YYYY-MM-DD HH:MM:SS
optout_date: dateIn the format YYYY-MM-DD HH:MM:SS
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Pass a List API identifier to download Users from the specified List and tailor the output using the 'export_type' parameter.
Describe the columns required for the CSV file export using the 'field_map_api_identifier' parameter - more info on Field Maps can be found here.
The reserved API identifier "SEED_LIST" can be used to pull the Users from the Seed List.
Valid requests return a compressed ZIP archive in order to reduce transfer times of larger files. Use the optional 'filename' parameter to override the default naming convention of the zip file.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
list_id | string | Internal ID of the list | * Provide one only |
list_api_identifier | string | API identifier of the List | * Provide one only |
field_map_api_identifier | string | Field Map API Identifier | * Required |
filename | string | Preferred filename | |
export_type | string |
[ALL, SUBSCRIBED, OPTOUT, LIST_GLOBAL, LIST_INACTIVE]
|
* Required |
include_system_fields | string | Include extended fields | |
include_engagement_fields | string | Include Engagement fields |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | List not found |
421 | No List ID or API Identifier specified |
422 | export_type must be either ALL, SUBSCRIBED or OPTOUT |
423 | Field Map API identifier is required when requesting exports |
424 | Unknown Field Map API Identifier |
428 | Preferred filename is invalid; alpha-numeric, underscores and dashes only |
429 | include_system_fields must be either Y or N when provided |
430 | List no longer available due to Data Retention Policy |
431 | The requested download contains no Users |
432 | include_engagement_fields must be either Y or N when provided |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
This request is hard-coded to export only from the Global Suppression list and you can tailor the output using the 'export_type' parameter.
Describe the columns required for the CSV file export using the 'field_map_api_identifier' parameter - more info on Field Maps can be found here.
A date range can optionally be provided to allow incremental data downloads for more effecient processing when integrating with other applications.
Valid requests return a compressed ZIP archive in order to reduce transfer times of larger files. Use the optional 'filename' parameter to override the default naming convention of the zip file.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
field_map_api_identifier | string | Field Map API Identifier | * Required |
filename | string | Preferred filename | |
export_type | string |
[ALL, API, AUTOCLEANSED, FBL, IMPORT, ADMIN or UNSUBSCRIPTION]
|
* Required |
date_from | date | Date from as YYYY-MM-DD | |
date_to | date | Date to as YYYY-MM-DD |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | List not found |
422 | export_type must be either ALL, API, AUTOCLEANSED, FBL, IMPORT, ADMIN or UNSUBSCRIPTION |
423 | Field Map API identifier is required when requesting exports |
424 | Unknown Field Map API Identifier |
425 | Invalid date from, please provide in the format YYYY-MM-DD |
426 | Invalid date to, please provide in the format YYYY-MM-DD |
427 | Date From occurs ahead of Date To, please check your dates are in the correct order |
428 | Preferred filename is invalid; alpha-numeric, underscores and dashes only |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Import requests return a reference code and this request can then be used to check the status of individual imports.
When imports are complete the log is populated wtih high-level summary metrics to inform of the number of rows processed, Users created, Users updated, errors detected etc.
If any invalid records are detected a more detailed CSV report can be downloaded via /lists/import_error_report.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
list_api_identifier | string | List API Identifier | * Provide one only |
import_reference | string | Import Reference | * Provide one only |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No Imports Found |
421 | Only List API Identifier or Import Reference is required |
422 | Either List API Identifier or Import Reference is required |
423 | Unknown List API Identifier provided |
490 | Account is disabled, API access denied |
Response Details
{
0: {
import_type: string,[opt-in, opt-out]
import_reference: string,Import Reference
import_date: date,Date of import as YYYY-MM-DD HH:MM:SS
field_map_api_identifier: string,Field Map API Identifier
list_description: string,List Description
list_api_identifier: string,List API Identifier
import_status: string,Import Status [UPLOADED, PROCESSING, IMPORTED, FAILED, PARTIAL]
import_feedback: string,Import Reference
import_progress_percentage: integer,Import Progress (%)
uploaded_records: integer,Number of records uploaded
valid_records: integer,Number of valid records
invalid_records: integer,Number of invalid records
new_users: integer,Number of new Users created
updated_users: integer,Number of Users updated
list_optins: integer,Number of List opt-ins performed
optout_resets: integer,Number of List opt-outs reset
tags_applied: integer,Number of Tags applied
list_optouts: integer,Number of List opt-outs performed
global_optouts: integerNumber of Global Suppressions
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
When one or more rows of an import file cannot be processed an error report in CSV format is available for download containing a list of line numbers and email addresses that could not be imported.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
import_reference | string | Import Reference | * Required |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Import not found |
420 | Import Reference must be provided |
421 | Error report not yet available, import still being processed |
422 | No import errors detected |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Add a User to the Seed List using either email address or reference code.
Where a match is made the User will be added to the list, if the User does not exist it will need to be created using the /users/add_or_update endpoint.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Provide one only |
reference_code | string | Reference Code | * Provide one only |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
421 | Either email address or reference code must be provided |
422 | Only ONE of email address or reference code is required |
423 | Email address not valid |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
status: stringSeed List Member, true or false
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Remove a User to the Seed List using either email address or reference code.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Provide one only |
reference_code | string | Reference Code | * Provide one only |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
421 | Either email address or reference code must be provided |
422 | Only ONE of email address or reference code is required |
423 | Email address not valid |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
status: stringSeed List Member, true or false
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Removes all Users from the Seed List.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
490 | Account is disabled, API access denied |
Response Details
{
status: stringSeed List status returns "CLEARED"
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get full details of an account Login using email address.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
login_email_address | string | Email address used to log in | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Login could not be located |
420 | Email address not provided |
421 | Email address not a valid format |
490 | Account is disabled, API access denied |
Response Details
{
login_email_address: string,Email address used to log in
login_first_name: string,First name of the user
login_last_name: string,Last name of the user
login_type: string,User Type
login_2fa_enabled: string,Two Factor Authentication Enabled
permission_account_settings_logins: string,Account Settings & Logins Management
permission_system_monitor_access: string,Access to the System Monitor feature
permission_list_management: string,Create, Edit, Upload & Download Lists
permission_list_related: string,Related List Features
permission_forms_management: string,Create, Edit & Upload Forms
permission_forms_integrations: string,Access to external Forms integrations
permission_templates_design: string,Create, Edit & Upload Templates
permission_templates_source: string,Drag & Drop HTML Source
permission_templates_related: string,Related Template Features
permission_library_images_assets: string,Image Library Management
permission_library_designs: string,Library Design Management
permission_campaign_reports: string,Campgin Reporting Access
permission_campaign_create: string,Send Campaigns
permission_campaign_related: string,Related Campaign Features
permission_campaign_downloads: string,Exporting Campaign Data
permission_automation_management: string,Create & Edit Workflows
permission_automation_launch: string,Launch Workflows
permission_automation_downloads: string,Exporting Workflow Data
login_2fa_tokens: {Array of 2FA Trusted Device Tokens
login_2fa_token_description: string,Description
login_2fa_token_status: string,[ACTIVE, REMOVED, EXPIRED]
login_2fa_token_expiry: datetime,Expiry date
user_agent: string,User Agent
ip_address: stringIP Address
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Create new or update existing Logins and specify permissions to control access once logged into the solution.
It is recommend that Logins are created through the UI as there are extended explanations for each of the available permissions.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
login_email_address | string | Email address | * Required |
login_first_name | string | First name | * Required |
login_last_name | string | Last name | |
login_password | string | Use letters and numbers | * Required |
login_type | string | User type [ADMIN,USER] | * Required |
permission_account_settings_logins | string | Account Settings & Logins Management [Y,N] | |
permission_system_monitor_access | string | Access to the System Monitor feature [Y,N] | |
permission_list_managment | string | Create, Edit, Upload & Download Lists [Y,N] | |
permission_list_related | string | Related List Features [Y,N] | |
permission_forms_management | string | Create, Edit & Upload Forms [Y,N] | |
permission_forms_integrations | string | Access to external Forms integrations [Y,N] | |
permission_templates_design | string | Create, Edit & Upload Templates [Y,N] | |
permission_templates_source | string | Drag & Drop HTML Source [Y,N] | |
permission_templates_related | string | Related Template Features [Y,N] | |
permission_library_images_assets | string | Image Library Management [Y,N] | |
permission_library_designs | string | Library Design Management [Y,N] | |
permission_campaign_reports | string | Campagin Reporting Access [FULL,READONLY] | |
permission_campaign_create | string | Send Campaigns [Y,N] | |
permission_campaign_related | string | Related Campaign Features [Y,N] | |
permission_campaign_downloads | string | Exporting Campaign Data [FULL,READONLY,DISABLED] | |
permission_automation_management | string | Create & Edit Workflows [FULL,READONLY,HIDDEN] | |
permission_automation_launch | string | Launch Workflows [Y,N] | |
permission_automation_downloads | string | Exporting Workflow Data [FULL,RESPONSE,DISABLED] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Email address not provided |
421 | Email address not a valid format |
423 | Email address already in use. |
424 | Name must be provided. |
425 | Type must be ADMIN or USER |
426 | Password is required |
427 | Permission not a valid format |
428 | Password does not fit the current password policy, please try a more secure password |
490 | Account is disabled, API access denied |
Response Details
{
login_email_address: string,Email address used to log in
login_first_name: string,First name of the user
login_last_name: string,Last name of the user
login_type: string,User Type
permission_account_settings_logins: string,Account Settings & Logins Management
permission_system_monitor_access: string,Access to the System Monitor feature
permission_list_management: string,Create, Edit, Upload & Download Lists
permission_list_related: string,Related List Features
permission_forms_management: string,Create, Edit & Upload Forms
permission_forms_integrations: string,Access to external Forms integrations
permission_templates_design: string,Create, Edit & Upload Templates
permission_templates_source: string,Drag & Drop HTML Source
permission_templates_related: string,Related Template Features
permission_library_images_assets: string,Image Library Management
permission_library_designs: string,Library Design Management
permission_campaign_reports: string,Campgin Reporting Access
permission_campaign_create: string,Send Campaigns
permission_campaign_related: string,Related Campaign Features
permission_campaign_downloads: string,Exporting Campaign Data
permission_automation_management: string,Create & Edit Workflows
permission_automation_launch: string,Launch Workflows
permission_automation_downloads: stringExporting Workflow Data
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Force a permanent deletion of a Login. Specify the email address and when a match is found the person will no longer be able to access the solution and their Login record will be completely deleted.
Deleted Logins cannot be restored.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
login_email_address | string | Email address used to log in | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Email address not provided |
421 | Email address not a valid format |
404 | Login cannot be found |
490 | Account is disabled, API access denied |
Response Details
{
success: booleanTrue when Login has been deleted
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
List all monitored Domains showing Domain Details, Authentication status and Blacklistings.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
domain_type | string | [ALL, TRACKING, SENDING] | |
authentication_status | string | [ALL, VERIFIED, ISSUES] | |
blacklisted | string | [ALL, NOT_LISTED, LISTED] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Domain Type needs to be [ALL, NOT_LISTED, LISTED] |
421 | Authentication Status needs to be [ALL, VERIFIED, ISSUES] |
422 | Blacklisted needs to be set to [ALL, NOT_LISTED, LISTED] |
490 | Account is disabled, API access denied |
Response Details
{
0: {An array of Domain objects in the following format
domain_name: string,Domain Name
domain_type: string,Type of Domain [TRACKING, SENDING]
domain_authenticated: string,Domain Authentication [VERIFIED, ISSUES]
domain_dmarc_status: string,Domain DMARC Status [NONE, VERIFIED, ISSUES]
domain_last_tested: date,Date and Time of Last Authentication Validation
domain_blacklisted: string,Domain found on a Blocklist [NOT_LISTED, LISTED]
domain_blacklist_count: integerNumber of current Blacklistings
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get a list of the 200 most recent Templates by passing no additional parameters or search for specific Templates using the API identifier or description parameters.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
template_api_identifier | string | Template API identifier | |
template_description | string | Template description |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No Templates detected |
490 | Account is disabled, API access denied |
Response Details
{
0: {An array of Template objects in the following format
template_id: integer,Internal Template ID
template_api_identifier: string,Template API identifier
template_description: integer,Template description
date_modified: date,Delivery date as YYYY-MM-DD HH:MM:SS
template_content_type: stringTemplate Content Type [UPLOADED, EMAIL_DESIGNER]
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Pass a Template API identifier to access full details in relation to content, validation, testing and all related assets.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
template_api_identifier | string | Template API identifier | * Provide one only |
template_id | string | Template ID identifier | * Provide one only |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Template not detected |
421 | Template API identifier or Template ID is required |
490 | Account is disabled, API access denied |
Response Details
{
template_id: integer,Internal Template ID
template_api_identifier: string,Template API identifier
template_description: string,Description
template_subject: string,Subject line
template_validation_status: string,Validation Status [PENDING, INVALID, VALID]
template_content_type: string,Template Content Type [UPLOADED, EMAIL_DESIGNER]
email_profile: {An array containing Email Profile details
email_profile_id: integer,Internal Email Profile ID
email_profile_api_identifier: date,Email Profile API identifier
email_profile_name: string,Email Profile name
from_name: string,From name
from_address: stringFrom email address
}
tags: string,CSV string of Spotlight Tags
links: {An array containing link verification results
status: string,Validation status [BUSY,VALIDATED]
urls: {An array containing link objects in the following format
0: {
link_id: integer,Internal link ID
link_url: string,Destination URL for link clicks
validation_required: string,Link validation processed (merged links cannot be validated) [Y,N]
validation: {
valid: string,Link validated [TRUE,FALSE]
http_code: integer,HTTP response code received
content_type: string,Type of content
server_location: stringServer checked
}
}...
}
}
images: {An array containing image verification results
status: string,Validation status [BUSY,VALIDATED]
files: {An array containing image objects in the following format
0: {
image_id: integer,Internal image ID
image_file: string,Image file base name
image_url: string,Image hosted with template [HOSTED,REMOTE]
url: string,Destination URL of the image
validation_performed: string,Link validation performed (merged links cannot be validated) [Y,N]
validation: {Validation results
valid: string,Image validated [TRUE,FALSE]
http_code: integer,HTTP response code received
content_type: string,Type of content
server_location: stringServer checked
}
}...
}
}
primary_content_type: string,Primary email content type
primary_content: string,Primary email content
alternative_content_type: string,Alternative email content type
alternative_content: string,Alternative email content
thumbnails: {An collection of template thumbnail images
small: string,Thumbnail URL (small)
medium: string,Thumbnail URL (medium)
large: stringThumbnail URL (large)
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Create new Templates or update existing using the 'template_api_identifier' parameter.
When using the 'template_api_identifier' parameter please note that when the value is not matched to an existing Template a new item will be created.
Multiple Images
Images need to be zipped. Avoid uploading lots indiviual images using multiple requests.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
template_api_identifier | string | Template API identifier | * Required |
template_description | string | Unique description | * Required |
template_subject | string | Subject line | * Required |
email_profile_api_identifier | string | Email Profile API identifier | * Required |
tags | string | Tags used for organising content | |
primary_content_type | string | Primary content type [HTML,TEXT] | |
primary_file | file | HTML file | * Required |
css_file | file | CSS files to be in-lined | |
alternative_file | file | Text-only version | |
image_archive | file | ZIP file of images | |
html_tidy | string | Run HTML tidy [TRUE,FALSE] | |
generate_alternative | string | Auto-generate text-only content [TRUE,FALSE] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
421 | Template API identifier is required |
422 | Subject line missing |
423 | Template description is required |
424 | Template description needs to be unique |
425 | Email Profile API identifier is required |
426 | Email Profile API identifier is not valid |
427 | Primary content type must be HTML or TEXT |
428 | Primary content file upload missing |
429 | Primary content file is blank |
430 | CSS file is blank |
431 | Alternative content file is blank |
432 | HTML tidy option should be TRUE or FALSE |
433 | Auto-generate text-only content should be TRUE or FALSE |
490 | Account is disabled, API access denied |
Response Details
{
template_id: integer,Internal Template ID
template_api_identifier: string,Template API identifier
template_description: string,Description
template_subject: string,Subject line
template_validation_status: string,Validation Status [PENDING, INVALID, VALID]
template_content_type: string,Template Content Type [UPLOADED, EMAIL_DESIGNER]
email_profile: {An array containing Email Profile details
email_profile_id: integer,Internal Email Profile ID
email_profile_api_identifier: date,Email Profile API identifier
email_profile_name: string,Email Profile name
from_name: string,From name
from_address: stringFrom email address
}
tags: string,CSV string of Spotlight Tags
links: {An array containing link verification results
status: string,Validation status [BUSY,VALIDATED]
urls: {An array containing link objects in the following format
0: {
link_id: integer,Internal link ID
link_url: string,Destination URL for link clicks
validation_required: string,Link validation processed (merged links cannot be validated) [Y,N]
validation: {
valid: string,Link validated [TRUE,FALSE]
http_code: integer,HTTP response code received
content_type: string,Type of content
server_location: stringServer checked
}
}...
}
}
images: {An array containing image verification results
status: string,Validation status [BUSY,VALIDATED]
files: {An array containing image objects in the following format
0: {
image_id: integer,Internal image ID
image_file: string,Image file base name
image_url: string,Image hosted with template [HOSTED,REMOTE]
url: string,Destination URL of the image
validation_performed: string,Link validation performed (merged links cannot be validated) [Y,N]
validation: {Validation results
valid: string,Image validated [TRUE,FALSE]
http_code: integer,HTTP response code received
content_type: string,Type of content
server_location: stringServer checked
}
}...
}
}
primary_content_type: string,Primary email content type
primary_content: string,Primary email content
alternative_content_type: string,Alternative email content type
alternative_content: string,Alternative email content
thumbnails: {An collection of template thumbnail images
small: string,Thumbnail URL (small)
medium: string,Thumbnail URL (medium)
large: stringThumbnail URL (large)
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Provide a Template API Identifier and a zipped file of image assets to overwrite existing images or add to the Template's image library.
For Templates that use the Email Designer, this endpoint will add or update images in the image library. For Templates that do not use the Email Designer this endpoint will only overwrite existing images for matching filenames.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
template_api_identifier | string | Template API identifier | * Required |
image_assets | file | Zip file containing images | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Template not found |
421 | Template API identifier is required |
422 | Image assets are missing from your request |
423 | Image assets need to be provided in a zip file |
424 | No assets detected |
425 | Anti-virus scan detected a problem with the file |
426 | No image assets detected in zip file |
490 | Account is disabled, API access denied |
Response Details
{
template_id: integer,Internal Template ID
template_api_identifier: string,Template API identifier
template_description: string,Description
images: {An array containing image verification results
status: string,Validation status [BUSY,VALIDATED]
files: {An array containing image objects in the following format
0: {
image_id: integer,Internal image ID
image_file: string,Image file base name
image_url: string,Image hosted with template [HOSTED,REMOTE]
url: string,Destination URL of the image
validation_performed: string,Link validation performed (merged links cannot be validated) [Y,N]
validation: {Validation results
valid: string,Image validated [TRUE,FALSE]
http_code: integer,HTTP response code received
content_type: string,Type of content
server_location: stringServer checked
}
}...
}
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Send Inbox Tests directly to Test Users by specifying a comma delimted list of email addresses.
Existing Test Users will be matched on email address and where a match cannot be made a new Test User will automatically be created.
Where Templates have primary and alternative content Inbox Tests will be split and each Test User will receive two emails. One for the primary content and one for the alternative content. This allows the Template to be proofed in a more efficient way.
Check the junk folder if Inbox Tests do not arrive and also view the Inbox Tests page on the related Template for more specific information about delivery status.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
template_api_identifier | string | Template API identifier | * Required |
test_email_recipients | string | Comma delimited email addresses | * Required |
test_email_prefix | string |
[TEST, PROOF, NONE]
|
|
test_email_feedback_mode | string |
[FEEDBACK, APPROVAL, NONE]
|
|
test_email_comments | string | Inbox Test comments |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Template not detected |
421 | Template API identifier is required |
422 | Test User email address(es) must be provided |
423 | Invalid email address(es) provided |
424 | Invalid feedback mode supplied, must be either FEEDBACK, APPROVAL or NONE |
425 | Invalid prefix supplied, must be either TEST, PROOF or NONE |
426 | Insufficient Transaction credits applied to this account, tests cannot be sent. |
490 | Account is disabled, API access denied |
Response Details
{
queued: boolean,Inbox Test queue status
error_message: stringQueue failure feedback
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Download the contents of a template by using it's Template API Identifier or Template ID.
A choice of download options are availble - ALL, HTML, HTML_COMPATIBLE, TEXT and IMAGES.
Generates an application/zip, text/html or text/plain file depending on download type.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
template_api_identifier | string | Template API identifier | * Provide one only |
template_id | string | Template ID identifier | * Provide one only |
download_type | string |
[ALL, HTML, HTML_COMPATIBLE, TEXT, IMAGES]
|
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Template not detected |
421 | Template API identifier or Template ID is required |
422 | Invalid download type, must be ALL, HTML, HTML_COMPATIBLE, TEXT or IMAGES |
423 | HTML_COMPATIBLE is only available for templates created in the email designer |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Get full Test User details using either email address or reference code.
Where a match is made all User Profile & Custom Field values are returned along with a summary of the emails that have been sent to them.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Provide one only |
reference_code | string | Reference Code | * Provide one only |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | Test User not found |
421 | Either email address or reference code must be provided |
422 | Only ONE of email address or reference code is required |
423 | Email address not valid |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
title: string,
first_name: string,
last_name: string,
company_name: string,
address_line_1: string,
address_line_2: string,
address_line_3: string,
address_line_4: string,
city: string,
post_code: string,
country: string,Two character ISO country code
mobile: string,
telephone: string,
dob: date,Date of Birth [YYYY-MM-DD]
gender: string,[MALE, FEMALE, M, F or blank]
date_created: date,In the format YYYY-MM-DD HH:MM:SS
date_created_source: string,Source of User creation [ADMIN, API, IMPORT, PREF_CENTRE]
date_modified: date,In the format YYYY-MM-DD HH:MM:SS
date_modified_source: string,Source when last modified [ADMIN, API, IMPORT]
email_verification_status: string,Email Verification using Double Opt-in [VERIFICATION_NOT_ATTEMPTED, PENDING,CONFIRMED,UNCONFIRMED,EXPIRED,CANCELLED]
global_opt_out: string,Global Suppression active [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
global_opt_out_source: string,[ADMIN, API, AUTOCLEANSED, IMPORT, UNSUBSCRIPTION]
1: string,
2: string,
3: string,
4: string,
5: string,
6: string,
7: string,
8: string,
9: string,
10: string,
11: string,
12: string,
13: string,
14: string,
15: string,
16: string,
17: string,
18: string,
19: string,
20: string,
21: string,
22: string,
23: string,
24: string,
25: string,
26: string,
27: string,
28: string,
29: string,
30: string
}
tags: {An array containing multiple profiling tags in the following format
0: {
tag: string,Free text User Tag
applied: dateDate applied as YYYY-MM-DD HH:MM:SS
}...
}
engagement_summary: { 9 items}
open_count: integer,Email view count
first_open: date,
latest_open: date,
click_count: integer,Total number of clicks
first_click: date,
latest_click: date,
unsubscribe_count: integer,Opt-out clicks
first_unsubscribe: date,
latest_unsubscribe: date
}
campaign_summary: { 15 items} Key metrics across all Campaigns and Workflows
sent: {
value: integer
}
processing: {
value: integer,
percentage: float
}
delivered: {
value: integer,
percentage: float
}
hard_bounce: {
value: integer,
percentage: float
}
soft_bounce: {
value: integer,
percentage: float
}
undeliverable: {
value: integer,
percentage: float
}
returned_mail: {
value: integer,
percentage: float
}
opens: {
value: integer,
percentage: float
}
clicks: {
value: integer,
percentage: float
}
cto_rate: {
percentage: float
}
not_clicked: {
value: integer,
percentage: float
}
spam_reports: {
value: integer,
percentage: float
}
auto_cleansed: {
value: integer,
percentage: float
}
opt_outs: {
value: integer,
percentage: float
}
viewed_online: {
value: integer,
percentage: float
}
}
campaigns: {An array containing multiple campaign objects as follows
0: {
campaign_id: integer,Internal Campaign ID
campaign_description: string,Campaign description
campaign_date: date,Scheduled delivery date as YYYY-MM-DD HH:MM:SS
email_status: string,Delivery status [QUEUED,DELIVERED,HARD_BOUNCE,SOFT_BOUNCE]
result_code: integer,SMTP response code for the message
message: string,Response message from remote server
mail_server: string,Recipient mail server details
open_count: integer,Open count
first_open: date,In the format YYYY-MM-DD HH:MM:SS
latest_open: date,In the format YYYY-MM-DD HH:MM:SS
click_count: integer,Number of times clicked
first_click: date,In the format YYYY-MM-DD HH:MM:SS
latest_click: date,In the format YYYY-MM-DD HH:MM:SS
unsubscribe_count: integer,Number of times opted-out
first_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
latest_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
spam_report: date,Received date in the format YYYY-MM-DD HH:MM:SS
location: {
country: string,Two character ISO country code
description: string
}
email_client: {Email app used to view the email
client: string,Client name
platform: string,Operating system
type: stringClassification [WEB, DESKTOP, MOBILE]
}
conversions: {
conversion_date: date,In the format YYYY-MM-DD HH:MM:SS
conversion_value: floatConversion value
}
}...
}
workflows: {An array containing multiple workflow objects as follows
0: {
journey_id: integer,Internal Workflow Journey ID
journey_email_id: integer,Internal Workflow Journey Email ID
template_description: string,Template Description
delivery_date: date,Workflow email delivery date as YYYY-MM-DD HH:MM:SS
email_status: string,Delivery status [QUEUED,DELIVERED,HARD_BOUNCE,SOFT_BOUNCE]
result_code: integer,SMTP response code for the message
message: string,Response message from remote server
mail_server: string,Recipient mail server details
open_count: integer,Open count
first_open: date,In the format YYYY-MM-DD HH:MM:SS
latest_open: date,In the format YYYY-MM-DD HH:MM:SS
click_count: integer,Number of times clicked
first_click: date,In the format YYYY-MM-DD HH:MM:SS
latest_click: date,In the format YYYY-MM-DD HH:MM:SS
unsubscribe_count: integer,Number of times opted-out
first_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
latest_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
spam_report: date,Received date in the format YYYY-MM-DD HH:MM:SS
location: {
country: string,Two character ISO country code
description: string
}
email_client: {Email app used to view the email
client: string,Client name
platform: string,Operating system
type: stringClassification [WEB, DESKTOP, MOBILE]
}
}...
}
lists: {An array containing multiple list objects as follows
0: {
list_id: integer,Internal list ID
list_api_identifier: string,List API identifier
list_description: string,
list_source_tag: string,List Source Tag
subscribed: string,Opt-in preference active [Y,N]
subscribe_date: date,List opt-in date
optout_date: dateList opt-out date
}...
}
email_client_summary: {Summary of email apps detected for User
0: {
email_client: string,Account name
count: integer,View Count
percentage: float,Percentage Used
mobile: booleanClassification [WEB, DESKTOP, MOBILE]
}...
}
location_summary: {Summary of locations detected for User
0: {
country_code: string,Two digit ISO country code
country_name: string,
count: integer,View Count
percentage: floatPercentage
}...
}
email_confirmation_status: string,Email Address has been Verified by double opt-in
email_confirmation_requests: {An array containing multiple double optin requests as follows
status: string,Confirmation Status
date_sent: date,Date confirmation email sent
date_confirmed: date,Date verification link clicked
type: string,Source of Double Opt-in request
ip_address: string,Confirmation IP address
user_agent: stringConfirmation User Agent
}
}
preference_centre: {An array containing multiple double optin requests as follows
type: string,Type of Form Submission
date: date,Date form submitted
preference_centre: string,Preference Centre Name
ip_address: string,Submission IP address
user_agent: stringSubmission User Agent
}
}
email_address_history: {An array containing Email Address changes for the User
old_email_address: string,The previous Email Address
new_email_address: string,The new Emal Address
change_source: string,Source of the change ADMIN or API
change_date: dateDate Email Address changed
}
}
consent: {An array containing consent submissions for the User
consent_id: string,Internal Consent ID
consent_status: string,The status [PROVIDED, REVOKED]
consent_type: string,The type of Consent [DATA, MARKETING]
consent_source: string,The Consent source [FORM_SUBMISSION, API]
consent_source_id: string,Internal source ID
consent_count: integer,Number of times Consent has been recorded
consent_code: string,Unique Consent Code
consent_description: string,Consent description
consent_date: date,Date consent given
consent_ip_address: string,Consent IP Address
consent_user_agent: stringConsent User Agent String
}
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Create new or update existing Test User record.
Test Users are unique on email address and where a match to an existing Test User is made the details of that record will be updated.
Reference Code is optional but when specified for creating new Test Users it needs to be unique.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email Address | * Required |
reference_code | string | Reference Code | |
title | string | ||
first_name | string | ||
last_name | string | ||
company_name | string | ||
address_line_1 | string | ||
address_line_2 | string | ||
address_line_3 | string | ||
address_line_4 | string | ||
city | string | ||
post_code | string | ||
country | string | Two digit ISO country code | |
mobile | string | 11 digits or 12 digits including country code | |
telephone | string | ||
variable_data_1 | string | ||
variable_data_2 | string | ||
variable_data_3 | string | ||
variable_data_4 | string | ||
variable_data_5 | string | ||
variable_data_6 | string | ||
variable_data_7 | string | ||
variable_data_8 | string | ||
variable_data_9 | string | ||
variable_data_10 | string | ||
variable_data_11 | string | ||
variable_data_12 | string | ||
variable_data_13 | string | ||
variable_data_14 | string | ||
variable_data_15 | string | ||
variable_data_16 | string | ||
variable_data_17 | string | ||
variable_data_18 | string | ||
variable_data_19 | string | ||
variable_data_20 | string | ||
variable_data_21 | string | ||
variable_data_22 | string | ||
variable_data_23 | string | ||
variable_data_24 | string | ||
variable_data_25 | string | ||
variable_data_26 | string | ||
variable_data_27 | string | ||
variable_data_28 | string | ||
variable_data_29 | string | ||
variable_data_30 | string |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
420 | Email address not provided |
421 | Email address not a valid format |
422 | Reference code is already in use |
423 | Country code is not valid |
424 | Mobile number can only be numerics, 11 digits or 12 including country code |
425 | Global Suppression is not Y or N |
426 | Global Suppression flag already set, this cannot be reset via the API |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
title: string,
first_name: string,
last_name: string,
company_name: string,
address_line_1: string,
address_line_2: string,
address_line_3: string,
address_line_4: string,
city: string,
post_code: string,
country: string,Two character ISO country code
mobile: string,
telephone: string,
dob: date,Date of Birth [YYYY-MM-DD]
gender: string,[MALE, FEMALE, M, F or blank]
date_created: date,In the format YYYY-MM-DD HH:MM:SS
date_created_source: string,Source of User creation [ADMIN, API, IMPORT, PREF_CENTRE]
date_modified: date,In the format YYYY-MM-DD HH:MM:SS
date_modified_source: string,Source when last modified [ADMIN, API, IMPORT]
email_verification_status: string,Email Verification using Double Opt-in [VERIFICATION_NOT_ATTEMPTED, PENDING,CONFIRMED,UNCONFIRMED,EXPIRED,CANCELLED]
global_opt_out: string,Global Suppression active [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
global_opt_out_source: string,[ADMIN, API, AUTOCLEANSED, IMPORT, UNSUBSCRIPTION]
1: string,
2: string,
3: string,
4: string,
5: string,
6: string,
7: string,
8: string,
9: string,
10: string,
11: string,
12: string,
13: string,
14: string,
15: string,
16: string,
17: string,
18: string,
19: string,
20: string,
21: string,
22: string,
23: string,
24: string,
25: string,
26: string,
27: string,
28: string,
29: string,
30: string
}
tags: {An array containing multiple profiling tags in the following format
0: {
tag: string,Free text User Tag
applied: dateDate applied as YYYY-MM-DD HH:MM:SS
}...
}
engagement_summary: { 9 items}
open_count: integer,Email view count
first_open: date,
latest_open: date,
click_count: integer,Total number of clicks
first_click: date,
latest_click: date,
unsubscribe_count: integer,Opt-out clicks
first_unsubscribe: date,
latest_unsubscribe: date
}
campaign_summary: { 15 items} Key metrics across all Campaigns and Workflows
sent: {
value: integer
}
processing: {
value: integer,
percentage: float
}
delivered: {
value: integer,
percentage: float
}
hard_bounce: {
value: integer,
percentage: float
}
soft_bounce: {
value: integer,
percentage: float
}
undeliverable: {
value: integer,
percentage: float
}
returned_mail: {
value: integer,
percentage: float
}
opens: {
value: integer,
percentage: float
}
clicks: {
value: integer,
percentage: float
}
cto_rate: {
percentage: float
}
not_clicked: {
value: integer,
percentage: float
}
spam_reports: {
value: integer,
percentage: float
}
auto_cleansed: {
value: integer,
percentage: float
}
opt_outs: {
value: integer,
percentage: float
}
viewed_online: {
value: integer,
percentage: float
}
}
campaigns: {An array containing multiple campaign objects as follows
0: {
campaign_id: integer,Internal Campaign ID
campaign_description: string,Campaign description
campaign_date: date,Scheduled delivery date as YYYY-MM-DD HH:MM:SS
email_status: string,Delivery status [QUEUED,DELIVERED,HARD_BOUNCE,SOFT_BOUNCE]
result_code: integer,SMTP response code for the message
message: string,Response message from remote server
mail_server: string,Recipient mail server details
open_count: integer,Open count
first_open: date,In the format YYYY-MM-DD HH:MM:SS
latest_open: date,In the format YYYY-MM-DD HH:MM:SS
click_count: integer,Number of times clicked
first_click: date,In the format YYYY-MM-DD HH:MM:SS
latest_click: date,In the format YYYY-MM-DD HH:MM:SS
unsubscribe_count: integer,Number of times opted-out
first_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
latest_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
spam_report: date,Received date in the format YYYY-MM-DD HH:MM:SS
location: {
country: string,Two character ISO country code
description: string
}
email_client: {Email app used to view the email
client: string,Client name
platform: string,Operating system
type: stringClassification [WEB, DESKTOP, MOBILE]
}
conversions: {
conversion_date: date,In the format YYYY-MM-DD HH:MM:SS
conversion_value: floatConversion value
}
}...
}
workflows: {An array containing multiple workflow objects as follows
0: {
journey_id: integer,Internal Workflow Journey ID
journey_email_id: integer,Internal Workflow Journey Email ID
template_description: string,Template Description
delivery_date: date,Workflow email delivery date as YYYY-MM-DD HH:MM:SS
email_status: string,Delivery status [QUEUED,DELIVERED,HARD_BOUNCE,SOFT_BOUNCE]
result_code: integer,SMTP response code for the message
message: string,Response message from remote server
mail_server: string,Recipient mail server details
open_count: integer,Open count
first_open: date,In the format YYYY-MM-DD HH:MM:SS
latest_open: date,In the format YYYY-MM-DD HH:MM:SS
click_count: integer,Number of times clicked
first_click: date,In the format YYYY-MM-DD HH:MM:SS
latest_click: date,In the format YYYY-MM-DD HH:MM:SS
unsubscribe_count: integer,Number of times opted-out
first_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
latest_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
spam_report: date,Received date in the format YYYY-MM-DD HH:MM:SS
location: {
country: string,Two character ISO country code
description: string
}
email_client: {Email app used to view the email
client: string,Client name
platform: string,Operating system
type: stringClassification [WEB, DESKTOP, MOBILE]
}
}...
}
lists: {An array containing multiple list objects as follows
0: {
list_id: integer,Internal list ID
list_api_identifier: string,List API identifier
list_description: string,
list_source_tag: string,List Source Tag
subscribed: string,Opt-in preference active [Y,N]
subscribe_date: date,List opt-in date
optout_date: dateList opt-out date
}...
}
email_client_summary: {Summary of email apps detected for User
0: {
email_client: string,Account name
count: integer,View Count
percentage: float,Percentage Used
mobile: booleanClassification [WEB, DESKTOP, MOBILE]
}...
}
location_summary: {Summary of locations detected for User
0: {
country_code: string,Two digit ISO country code
country_name: string,
count: integer,View Count
percentage: floatPercentage
}...
}
email_confirmation_status: string,Email Address has been Verified by double opt-in
email_confirmation_requests: {An array containing multiple double optin requests as follows
status: string,Confirmation Status
date_sent: date,Date confirmation email sent
date_confirmed: date,Date verification link clicked
type: string,Source of Double Opt-in request
ip_address: string,Confirmation IP address
user_agent: stringConfirmation User Agent
}
}
preference_centre: {An array containing multiple double optin requests as follows
type: string,Type of Form Submission
date: date,Date form submitted
preference_centre: string,Preference Centre Name
ip_address: string,Submission IP address
user_agent: stringSubmission User Agent
}
}
email_address_history: {An array containing Email Address changes for the User
old_email_address: string,The previous Email Address
new_email_address: string,The new Emal Address
change_source: string,Source of the change ADMIN or API
change_date: dateDate Email Address changed
}
}
consent: {An array containing consent submissions for the User
consent_id: string,Internal Consent ID
consent_status: string,The status [PROVIDED, REVOKED]
consent_type: string,The type of Consent [DATA, MARKETING]
consent_source: string,The Consent source [FORM_SUBMISSION, API]
consent_source_id: string,Internal source ID
consent_count: integer,Number of times Consent has been recorded
consent_code: string,Unique Consent Code
consent_description: string,Consent description
consent_date: date,Date consent given
consent_ip_address: string,Consent IP Address
consent_user_agent: stringConsent User Agent String
}
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Load the details of an individual User by passing either their email address or unique reference code.
All User Profile & Custom Fields are returned along with an activity feed that contains extended information relating to email preferences, consent, emails received, engagement summary etc.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Provide one only |
reference_code | string | Unique Reference Code | * Provide one only |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
420 | Email address or reference code is required |
421 | Only ONE of email address or reference code is required |
422 | Email address not valid |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
title: string,
first_name: string,
last_name: string,
company_name: string,
address_line_1: string,
address_line_2: string,
address_line_3: string,
address_line_4: string,
city: string,
post_code: string,
country: string,Two character ISO country code
mobile: string,
telephone: string,
dob: date,Date of Birth [YYYY-MM-DD]
gender: string,[MALE, FEMALE, M, F or blank]
date_created: date,In the format YYYY-MM-DD HH:MM:SS
date_created_source: string,Source of User creation [ADMIN, API, IMPORT, PREF_CENTRE]
date_modified: date,In the format YYYY-MM-DD HH:MM:SS
date_modified_source: string,Source when last modified [ADMIN, API, IMPORT]
email_verification_status: string,Email Verification using Double Opt-in [VERIFICATION_NOT_ATTEMPTED, PENDING,CONFIRMED,UNCONFIRMED,EXPIRED,CANCELLED]
global_opt_out: string,Global Suppression active [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
global_opt_out_source: string,[ADMIN, API, AUTOCLEANSED, IMPORT, UNSUBSCRIPTION]
1: string,
2: string,
3: string,
4: string,
5: string,
6: string,
7: string,
8: string,
9: string,
10: string,
11: string,
12: string,
13: string,
14: string,
15: string,
16: string,
17: string,
18: string,
19: string,
20: string,
21: string,
22: string,
23: string,
24: string,
25: string,
26: string,
27: string,
28: string,
29: string,
30: string
}
tags: {An array containing multiple profiling tags in the following format
0: {
tag: string,Free text User Tag
applied: dateDate applied as YYYY-MM-DD HH:MM:SS
}...
}
engagement_summary: { 9 items}
open_count: integer,Email view count
first_open: date,
latest_open: date,
click_count: integer,Total number of clicks
first_click: date,
latest_click: date,
unsubscribe_count: integer,Opt-out clicks
first_unsubscribe: date,
latest_unsubscribe: date
}
campaign_summary: { 15 items} Key metrics across all Campaigns and Workflows
sent: {
value: integer
}
processing: {
value: integer,
percentage: float
}
delivered: {
value: integer,
percentage: float
}
hard_bounce: {
value: integer,
percentage: float
}
soft_bounce: {
value: integer,
percentage: float
}
undeliverable: {
value: integer,
percentage: float
}
returned_mail: {
value: integer,
percentage: float
}
opens: {
value: integer,
percentage: float
}
clicks: {
value: integer,
percentage: float
}
cto_rate: {
percentage: float
}
not_clicked: {
value: integer,
percentage: float
}
spam_reports: {
value: integer,
percentage: float
}
auto_cleansed: {
value: integer,
percentage: float
}
opt_outs: {
value: integer,
percentage: float
}
viewed_online: {
value: integer,
percentage: float
}
}
campaigns: {An array containing multiple campaign objects as follows
0: {
campaign_id: integer,Internal Campaign ID
campaign_description: string,Campaign description
campaign_date: date,Scheduled delivery date as YYYY-MM-DD HH:MM:SS
email_status: string,Delivery status [QUEUED,DELIVERED,HARD_BOUNCE,SOFT_BOUNCE]
result_code: integer,SMTP response code for the message
message: string,Response message from remote server
mail_server: string,Recipient mail server details
open_count: integer,Open count
first_open: date,In the format YYYY-MM-DD HH:MM:SS
latest_open: date,In the format YYYY-MM-DD HH:MM:SS
click_count: integer,Number of times clicked
first_click: date,In the format YYYY-MM-DD HH:MM:SS
latest_click: date,In the format YYYY-MM-DD HH:MM:SS
unsubscribe_count: integer,Number of times opted-out
first_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
latest_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
spam_report: date,Received date in the format YYYY-MM-DD HH:MM:SS
location: {
country: string,Two character ISO country code
description: string
}
email_client: {Email app used to view the email
client: string,Client name
platform: string,Operating system
type: stringClassification [WEB, DESKTOP, MOBILE]
}
conversions: {
conversion_date: date,In the format YYYY-MM-DD HH:MM:SS
conversion_value: floatConversion value
}
}...
}
workflows: {An array containing multiple workflow objects as follows
0: {
journey_id: integer,Internal Workflow Journey ID
journey_email_id: integer,Internal Workflow Journey Email ID
template_description: string,Template Description
delivery_date: date,Workflow email delivery date as YYYY-MM-DD HH:MM:SS
email_status: string,Delivery status [QUEUED,DELIVERED,HARD_BOUNCE,SOFT_BOUNCE]
result_code: integer,SMTP response code for the message
message: string,Response message from remote server
mail_server: string,Recipient mail server details
open_count: integer,Open count
first_open: date,In the format YYYY-MM-DD HH:MM:SS
latest_open: date,In the format YYYY-MM-DD HH:MM:SS
click_count: integer,Number of times clicked
first_click: date,In the format YYYY-MM-DD HH:MM:SS
latest_click: date,In the format YYYY-MM-DD HH:MM:SS
unsubscribe_count: integer,Number of times opted-out
first_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
latest_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
spam_report: date,Received date in the format YYYY-MM-DD HH:MM:SS
location: {
country: string,Two character ISO country code
description: string
}
email_client: {Email app used to view the email
client: string,Client name
platform: string,Operating system
type: stringClassification [WEB, DESKTOP, MOBILE]
}
}...
}
lists: {An array containing multiple list objects as follows
0: {
list_id: integer,Internal list ID
list_api_identifier: string,List API identifier
list_description: string,
list_source_tag: string,List Source Tag
subscribed: string,Opt-in preference active [Y,N]
subscribe_date: date,List opt-in date
optout_date: dateList opt-out date
}...
}
email_client_summary: {Summary of email apps detected for User
0: {
email_client: string,Account name
count: integer,View Count
percentage: float,Percentage Used
mobile: booleanClassification [WEB, DESKTOP, MOBILE]
}...
}
location_summary: {Summary of locations detected for User
0: {
country_code: string,Two digit ISO country code
country_name: string,
count: integer,View Count
percentage: floatPercentage
}...
}
email_confirmation_status: string,Email Address has been Verified by double opt-in
email_confirmation_requests: {An array containing multiple double optin requests as follows
status: string,Confirmation Status
date_sent: date,Date confirmation email sent
date_confirmed: date,Date verification link clicked
type: string,Source of Double Opt-in request
ip_address: string,Confirmation IP address
user_agent: stringConfirmation User Agent
}
}
preference_centre: {An array containing multiple double optin requests as follows
type: string,Type of Form Submission
date: date,Date form submitted
preference_centre: string,Preference Centre Name
ip_address: string,Submission IP address
user_agent: stringSubmission User Agent
}
}
email_address_history: {An array containing Email Address changes for the User
old_email_address: string,The previous Email Address
new_email_address: string,The new Emal Address
change_source: string,Source of the change ADMIN or API
change_date: dateDate Email Address changed
}
}
consent: {An array containing consent submissions for the User
consent_id: string,Internal Consent ID
consent_status: string,The status [PROVIDED, REVOKED]
consent_type: string,The type of Consent [DATA, MARKETING]
consent_source: string,The Consent source [FORM_SUBMISSION, API]
consent_source_id: string,Internal source ID
consent_count: integer,Number of times Consent has been recorded
consent_code: string,Unique Consent Code
consent_description: string,Consent description
consent_date: date,Date consent given
consent_ip_address: string,Consent IP Address
consent_user_agent: stringConsent User Agent String
}
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Generate an export of all Users for this Account.
Exports provided as a CSV file using the Field Map API Identifier to specify the fields to be exported.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
export_type | string |
[ALL, EXCLUDE_GLOBAL]
|
* Required |
field_map_api_identifier | string | Field Map API Identifier | * Required |
filename | string | Preferred filename |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No users present in export |
421 | Preferred filename is invalid; alpha-numeric, underscores and dashes only |
422 | Export type is not valid [ALL, EXCLUDE_GLOBAL] |
423 | Field Map API Identifier is required |
424 | Unknown Field Map API Identifier |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Create new Users or updating existing using through matching on email address.
Reference code is not required but when optionally provided it needs to be unique.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Required |
reference_code | string | Unique Reference Code | |
title | string | ||
first_name | string | ||
last_name | string | ||
company_name | string | ||
address_line_1 | string | ||
address_line_2 | string | ||
address_line_3 | string | ||
address_line_4 | string | ||
city | string | ||
post_code | string | ||
country | string | Two digit ISO country code | |
mobile | string | 11 digits or 12 digits including country code | |
telephone | string | ||
dob | string | Date of Birth [YYYY-MM-DD] | |
gender | string | Gender [MALE, FEMALE, M, F or blank] | |
global_opt_out | string | Global Suppression flag [Y or N] | |
consent_code | string | Unique Consent Code | |
consent_description | string | Consent description | |
consent_type | string | Type of consent given [DATA, MARKETING] | |
consent_list_api_identifier | string | [MARKETING] Consent List API Identifier | |
consent_ip_address | string | Optional Consent IP Address | |
consent_user_agent | string | Optional Consent User Agent String | |
variable_data_1 | string | ||
variable_data_2 | string | ||
variable_data_3 | string | ||
variable_data_4 | string | ||
variable_data_5 | string | ||
variable_data_6 | string | ||
variable_data_7 | string | ||
variable_data_8 | string | ||
variable_data_9 | string | ||
variable_data_10 | string | ||
variable_data_11 | string | ||
variable_data_12 | string | ||
variable_data_13 | string | ||
variable_data_14 | string | ||
variable_data_15 | string | ||
variable_data_16 | string | ||
variable_data_17 | string | ||
variable_data_18 | string | ||
variable_data_19 | string | ||
variable_data_20 | string | ||
variable_data_21 | string | ||
variable_data_22 | string | ||
variable_data_23 | string | ||
variable_data_24 | string | ||
variable_data_25 | string | ||
variable_data_26 | string | ||
variable_data_27 | string | ||
variable_data_28 | string | ||
variable_data_29 | string | ||
variable_data_30 | string |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
421 | Email address not provided |
422 | Email address not a valid format |
423 | Reference code is already in use |
424 | Country code is not valid |
425 | Mobile number can only be numerics, 11 digits or 12 including country code |
426 | Global Suppression is not Y or N |
427 | Gender should be MALE, FEMALE, M, F or blank |
428 | Invalid date of birth, please provide in the format YYYY-MM-DD |
430 | User could not be created due to User Record Limit |
440 | Consent type is required |
441 | Consent description is required |
442 | Consent type must be [DATA] or [MARKETING] |
443 | Marketing Consent List API Identifier must be provided |
444 | List no longer available due to Data Retention Policy |
445 | List API Identifier is not valid |
447 | List API Identifier requires Marketing consent |
480 | Users email address is on the Realtime Block List |
481 | Users email domain is on the Realtime Block List |
482 | Users email address is on the Application Level Block List |
483 | Users email domain is on the Application Level Block List |
484 | Matching hashed email address found on the Realtime Block List |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
title: string,
first_name: string,
last_name: string,
company_name: string,
address_line_1: string,
address_line_2: string,
address_line_3: string,
address_line_4: string,
city: string,
post_code: string,
country: string,Two character ISO country code
mobile: string,
telephone: string,
dob: date,Date of Birth [YYYY-MM-DD]
gender: string,[MALE, FEMALE, M, F or blank]
date_created: date,In the format YYYY-MM-DD HH:MM:SS
date_created_source: string,Source of User creation [ADMIN, API, IMPORT, PREF_CENTRE]
date_modified: date,In the format YYYY-MM-DD HH:MM:SS
date_modified_source: string,Source when last modified [ADMIN, API, IMPORT]
email_verification_status: string,Email Verification using Double Opt-in [VERIFICATION_NOT_ATTEMPTED, PENDING,CONFIRMED,UNCONFIRMED,EXPIRED,CANCELLED]
global_opt_out: string,Global Suppression active [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
global_opt_out_source: string,[ADMIN, API, AUTOCLEANSED, IMPORT, UNSUBSCRIPTION]
1: string,
2: string,
3: string,
4: string,
5: string,
6: string,
7: string,
8: string,
9: string,
10: string,
11: string,
12: string,
13: string,
14: string,
15: string,
16: string,
17: string,
18: string,
19: string,
20: string,
21: string,
22: string,
23: string,
24: string,
25: string,
26: string,
27: string,
28: string,
29: string,
30: string
}
tags: {An array containing multiple profiling tags in the following format
0: {
tag: string,Free text User Tag
applied: dateDate applied as YYYY-MM-DD HH:MM:SS
}...
}
engagement_summary: { 9 items}
open_count: integer,Email view count
first_open: date,
latest_open: date,
click_count: integer,Total number of clicks
first_click: date,
latest_click: date,
unsubscribe_count: integer,Opt-out clicks
first_unsubscribe: date,
latest_unsubscribe: date
}
campaign_summary: { 15 items} Key metrics across all Campaigns and Workflows
sent: {
value: integer
}
processing: {
value: integer,
percentage: float
}
delivered: {
value: integer,
percentage: float
}
hard_bounce: {
value: integer,
percentage: float
}
soft_bounce: {
value: integer,
percentage: float
}
undeliverable: {
value: integer,
percentage: float
}
returned_mail: {
value: integer,
percentage: float
}
opens: {
value: integer,
percentage: float
}
clicks: {
value: integer,
percentage: float
}
cto_rate: {
percentage: float
}
not_clicked: {
value: integer,
percentage: float
}
spam_reports: {
value: integer,
percentage: float
}
auto_cleansed: {
value: integer,
percentage: float
}
opt_outs: {
value: integer,
percentage: float
}
viewed_online: {
value: integer,
percentage: float
}
}
campaigns: {An array containing multiple campaign objects as follows
0: {
campaign_id: integer,Internal Campaign ID
campaign_description: string,Campaign description
campaign_date: date,Scheduled delivery date as YYYY-MM-DD HH:MM:SS
email_status: string,Delivery status [QUEUED,DELIVERED,HARD_BOUNCE,SOFT_BOUNCE]
result_code: integer,SMTP response code for the message
message: string,Response message from remote server
mail_server: string,Recipient mail server details
open_count: integer,Open count
first_open: date,In the format YYYY-MM-DD HH:MM:SS
latest_open: date,In the format YYYY-MM-DD HH:MM:SS
click_count: integer,Number of times clicked
first_click: date,In the format YYYY-MM-DD HH:MM:SS
latest_click: date,In the format YYYY-MM-DD HH:MM:SS
unsubscribe_count: integer,Number of times opted-out
first_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
latest_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
spam_report: date,Received date in the format YYYY-MM-DD HH:MM:SS
location: {
country: string,Two character ISO country code
description: string
}
email_client: {Email app used to view the email
client: string,Client name
platform: string,Operating system
type: stringClassification [WEB, DESKTOP, MOBILE]
}
conversions: {
conversion_date: date,In the format YYYY-MM-DD HH:MM:SS
conversion_value: floatConversion value
}
}...
}
workflows: {An array containing multiple workflow objects as follows
0: {
journey_id: integer,Internal Workflow Journey ID
journey_email_id: integer,Internal Workflow Journey Email ID
template_description: string,Template Description
delivery_date: date,Workflow email delivery date as YYYY-MM-DD HH:MM:SS
email_status: string,Delivery status [QUEUED,DELIVERED,HARD_BOUNCE,SOFT_BOUNCE]
result_code: integer,SMTP response code for the message
message: string,Response message from remote server
mail_server: string,Recipient mail server details
open_count: integer,Open count
first_open: date,In the format YYYY-MM-DD HH:MM:SS
latest_open: date,In the format YYYY-MM-DD HH:MM:SS
click_count: integer,Number of times clicked
first_click: date,In the format YYYY-MM-DD HH:MM:SS
latest_click: date,In the format YYYY-MM-DD HH:MM:SS
unsubscribe_count: integer,Number of times opted-out
first_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
latest_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
spam_report: date,Received date in the format YYYY-MM-DD HH:MM:SS
location: {
country: string,Two character ISO country code
description: string
}
email_client: {Email app used to view the email
client: string,Client name
platform: string,Operating system
type: stringClassification [WEB, DESKTOP, MOBILE]
}
}...
}
lists: {An array containing multiple list objects as follows
0: {
list_id: integer,Internal list ID
list_api_identifier: string,List API identifier
list_description: string,
list_source_tag: string,List Source Tag
subscribed: string,Opt-in preference active [Y,N]
subscribe_date: date,List opt-in date
optout_date: dateList opt-out date
}...
}
email_client_summary: {Summary of email apps detected for User
0: {
email_client: string,Account name
count: integer,View Count
percentage: float,Percentage Used
mobile: booleanClassification [WEB, DESKTOP, MOBILE]
}...
}
location_summary: {Summary of locations detected for User
0: {
country_code: string,Two digit ISO country code
country_name: string,
count: integer,View Count
percentage: floatPercentage
}...
}
email_confirmation_status: string,Email Address has been Verified by double opt-in
email_confirmation_requests: {An array containing multiple double optin requests as follows
status: string,Confirmation Status
date_sent: date,Date confirmation email sent
date_confirmed: date,Date verification link clicked
type: string,Source of Double Opt-in request
ip_address: string,Confirmation IP address
user_agent: stringConfirmation User Agent
}
}
preference_centre: {An array containing multiple double optin requests as follows
type: string,Type of Form Submission
date: date,Date form submitted
preference_centre: string,Preference Centre Name
ip_address: string,Submission IP address
user_agent: stringSubmission User Agent
}
}
email_address_history: {An array containing Email Address changes for the User
old_email_address: string,The previous Email Address
new_email_address: string,The new Emal Address
change_source: string,Source of the change ADMIN or API
change_date: dateDate Email Address changed
}
}
consent: {An array containing consent submissions for the User
consent_id: string,Internal Consent ID
consent_status: string,The status [PROVIDED, REVOKED]
consent_type: string,The type of Consent [DATA, MARKETING]
consent_source: string,The Consent source [FORM_SUBMISSION, API]
consent_source_id: string,Internal source ID
consent_count: integer,Number of times Consent has been recorded
consent_code: string,Unique Consent Code
consent_description: string,Consent description
consent_date: date,Date consent given
consent_ip_address: string,Consent IP Address
consent_user_agent: stringConsent User Agent String
}
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Change the email address of an existing individual User.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Current email address | * Required |
new_email_address | string | New email address | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
405 | New email address is already in use |
421 | Email address not provided |
422 | Email address not a valid format |
423 | New email address not provided |
424 | New email address not a valid format |
425 | Current and new email addresses must be different |
430 | Not allowed when duplicate email storage is enabled |
431 | More than one User found with a matching email address |
490 | Account is disabled, API access denied |
Response Details
{
success: boolean"True", when action complete
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Update an existing Users Global Suppression preference. Provide a Campaign code or ID to link the subscription action to a specific Campaign or provide a Journey ID to tie it to a particular Workflow email.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Required |
global_opt_out | string | Global Suppression flag [Y or N] | * Required |
campaign_id | string | Campaign ID | |
campaign_code | string | Campaign Code | |
journey_email_id | string | Workflow Journey Email ID |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
421 | Email address not provided |
422 | Email address not a valid format |
426 | Global Suppression is not Y or N |
427 | Specified campaign not found |
428 | User does not belong to the specified campaign |
429 | User was not sent specified Workflow Email |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
title: string,
first_name: string,
last_name: string,
company_name: string,
address_line_1: string,
address_line_2: string,
address_line_3: string,
address_line_4: string,
city: string,
post_code: string,
country: string,Two character ISO country code
mobile: string,
telephone: string,
dob: date,Date of Birth [YYYY-MM-DD]
gender: string,[MALE, FEMALE, M, F or blank]
date_created: date,In the format YYYY-MM-DD HH:MM:SS
date_created_source: string,Source of User creation [ADMIN, API, IMPORT, PREF_CENTRE]
date_modified: date,In the format YYYY-MM-DD HH:MM:SS
date_modified_source: string,Source when last modified [ADMIN, API, IMPORT]
email_verification_status: string,Email Verification using Double Opt-in [VERIFICATION_NOT_ATTEMPTED, PENDING,CONFIRMED,UNCONFIRMED,EXPIRED,CANCELLED]
global_opt_out: string,Global Suppression active [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
global_opt_out_source: string,[ADMIN, API, AUTOCLEANSED, IMPORT, UNSUBSCRIPTION]
1: string,
2: string,
3: string,
4: string,
5: string,
6: string,
7: string,
8: string,
9: string,
10: string,
11: string,
12: string,
13: string,
14: string,
15: string,
16: string,
17: string,
18: string,
19: string,
20: string,
21: string,
22: string,
23: string,
24: string,
25: string,
26: string,
27: string,
28: string,
29: string,
30: string
}
tags: {An array containing multiple profiling tags in the following format
0: {
tag: string,Free text User Tag
applied: dateDate applied as YYYY-MM-DD HH:MM:SS
}...
}
engagement_summary: { 9 items}
open_count: integer,Email view count
first_open: date,
latest_open: date,
click_count: integer,Total number of clicks
first_click: date,
latest_click: date,
unsubscribe_count: integer,Opt-out clicks
first_unsubscribe: date,
latest_unsubscribe: date
}
campaign_summary: { 15 items} Key metrics across all Campaigns and Workflows
sent: {
value: integer
}
processing: {
value: integer,
percentage: float
}
delivered: {
value: integer,
percentage: float
}
hard_bounce: {
value: integer,
percentage: float
}
soft_bounce: {
value: integer,
percentage: float
}
undeliverable: {
value: integer,
percentage: float
}
returned_mail: {
value: integer,
percentage: float
}
opens: {
value: integer,
percentage: float
}
clicks: {
value: integer,
percentage: float
}
cto_rate: {
percentage: float
}
not_clicked: {
value: integer,
percentage: float
}
spam_reports: {
value: integer,
percentage: float
}
auto_cleansed: {
value: integer,
percentage: float
}
opt_outs: {
value: integer,
percentage: float
}
viewed_online: {
value: integer,
percentage: float
}
}
campaigns: {An array containing multiple campaign objects as follows
0: {
campaign_id: integer,Internal Campaign ID
campaign_description: string,Campaign description
campaign_date: date,Scheduled delivery date as YYYY-MM-DD HH:MM:SS
email_status: string,Delivery status [QUEUED,DELIVERED,HARD_BOUNCE,SOFT_BOUNCE]
result_code: integer,SMTP response code for the message
message: string,Response message from remote server
mail_server: string,Recipient mail server details
open_count: integer,Open count
first_open: date,In the format YYYY-MM-DD HH:MM:SS
latest_open: date,In the format YYYY-MM-DD HH:MM:SS
click_count: integer,Number of times clicked
first_click: date,In the format YYYY-MM-DD HH:MM:SS
latest_click: date,In the format YYYY-MM-DD HH:MM:SS
unsubscribe_count: integer,Number of times opted-out
first_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
latest_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
spam_report: date,Received date in the format YYYY-MM-DD HH:MM:SS
location: {
country: string,Two character ISO country code
description: string
}
email_client: {Email app used to view the email
client: string,Client name
platform: string,Operating system
type: stringClassification [WEB, DESKTOP, MOBILE]
}
conversions: {
conversion_date: date,In the format YYYY-MM-DD HH:MM:SS
conversion_value: floatConversion value
}
}...
}
workflows: {An array containing multiple workflow objects as follows
0: {
journey_id: integer,Internal Workflow Journey ID
journey_email_id: integer,Internal Workflow Journey Email ID
template_description: string,Template Description
delivery_date: date,Workflow email delivery date as YYYY-MM-DD HH:MM:SS
email_status: string,Delivery status [QUEUED,DELIVERED,HARD_BOUNCE,SOFT_BOUNCE]
result_code: integer,SMTP response code for the message
message: string,Response message from remote server
mail_server: string,Recipient mail server details
open_count: integer,Open count
first_open: date,In the format YYYY-MM-DD HH:MM:SS
latest_open: date,In the format YYYY-MM-DD HH:MM:SS
click_count: integer,Number of times clicked
first_click: date,In the format YYYY-MM-DD HH:MM:SS
latest_click: date,In the format YYYY-MM-DD HH:MM:SS
unsubscribe_count: integer,Number of times opted-out
first_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
latest_unsubscribe: date,In the format YYYY-MM-DD HH:MM:SS
spam_report: date,Received date in the format YYYY-MM-DD HH:MM:SS
location: {
country: string,Two character ISO country code
description: string
}
email_client: {Email app used to view the email
client: string,Client name
platform: string,Operating system
type: stringClassification [WEB, DESKTOP, MOBILE]
}
}...
}
lists: {An array containing multiple list objects as follows
0: {
list_id: integer,Internal list ID
list_api_identifier: string,List API identifier
list_description: string,
list_source_tag: string,List Source Tag
subscribed: string,Opt-in preference active [Y,N]
subscribe_date: date,List opt-in date
optout_date: dateList opt-out date
}...
}
email_client_summary: {Summary of email apps detected for User
0: {
email_client: string,Account name
count: integer,View Count
percentage: float,Percentage Used
mobile: booleanClassification [WEB, DESKTOP, MOBILE]
}...
}
location_summary: {Summary of locations detected for User
0: {
country_code: string,Two digit ISO country code
country_name: string,
count: integer,View Count
percentage: floatPercentage
}...
}
email_confirmation_status: string,Email Address has been Verified by double opt-in
email_confirmation_requests: {An array containing multiple double optin requests as follows
status: string,Confirmation Status
date_sent: date,Date confirmation email sent
date_confirmed: date,Date verification link clicked
type: string,Source of Double Opt-in request
ip_address: string,Confirmation IP address
user_agent: stringConfirmation User Agent
}
}
preference_centre: {An array containing multiple double optin requests as follows
type: string,Type of Form Submission
date: date,Date form submitted
preference_centre: string,Preference Centre Name
ip_address: string,Submission IP address
user_agent: stringSubmission User Agent
}
}
email_address_history: {An array containing Email Address changes for the User
old_email_address: string,The previous Email Address
new_email_address: string,The new Emal Address
change_source: string,Source of the change ADMIN or API
change_date: dateDate Email Address changed
}
}
consent: {An array containing consent submissions for the User
consent_id: string,Internal Consent ID
consent_status: string,The status [PROVIDED, REVOKED]
consent_type: string,The type of Consent [DATA, MARKETING]
consent_source: string,The Consent source [FORM_SUBMISSION, API]
consent_source_id: string,Internal source ID
consent_count: integer,Number of times Consent has been recorded
consent_code: string,Unique Consent Code
consent_description: string,Consent description
consent_date: date,Date consent given
consent_ip_address: string,Consent IP Address
consent_user_agent: stringConsent User Agent String
}
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Subscribe a User to a List using a valid email address or reference code and a valid list API identifier. Provide a Campaign code or ID to link the subscription action to a specific Campaign or provide a Journey ID to tie it to a particular Workflow email.
If the User does not already belong to the List, they will be added. If the User already exists on the List, their subscription details will be updated.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Provide one only |
reference_code | string | Unique Reference Code | * Provide one only |
list_api_identifier | string | List API identifier | * Required |
campaign_id | string | Campaign ID | |
campaign_code | string | Campaign Code | |
journey_email_id | string | Workflow Journey Email ID | |
subscribed | string | Opt-in preference active [Y or N] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
420 | Email address or reference code is required |
421 | Only ONE of email address or reference code is required |
422 | Email address not valid |
423 | List API identifier is not valid |
424 | Subscribed flag not valid [Y, N] |
425 | Specified campaign not found |
426 | User was not sent specified Campaign |
427 | User not on List relating to the specified Campaign |
428 | User was not sent specified Workflow Email |
429 | List no longer available due to Data Retention Policy |
480 | Users email address is on the Realtime Block List |
481 | Users email domain is on the Realtime Block List |
482 | Users email address is on the Application Level Block List |
483 | Users email domain is on the Application Level Block List |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
global_opt_out: string,Global Suppression is active [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
list_api_identifier: string,List API identifier
list_description: string,List name
subscribed: string,Opt-in preference active [Y,N]
subscribe_date: date,In the format YYYY-MM-DD HH:MM:SS
optout_date: dateIn the format YYYY-MM-DD HH:MM:SS
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Set the Email Preferences for a User for Lists, Global Suppression or both.
If the User does not already belong to the List, they will be added. If the User already exists on the List, their Email Preferences will be updated.
The JSON array passed over in list_preferences should be formatted in the following way (List identifier, Opt-In Preference):
{"list_identifier_1":"Y","list_identifier_2":"N"}
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Provide one only |
reference_code | string | Unique Reference Code | * Provide one only |
list_preferences | string | List Preference | |
global_opt_out | string | Global Suppression flag [Y or N] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
420 | Email address or reference code is required |
421 | Only ONE of email address or reference code is required |
422 | Email address not valid |
423 | List preferences must be valid JSON |
424 | List preferences or global supression flag must be provided |
425 | List preferences must contain 1 or more lists unless Global Suppression is specified |
426 | List API identifier is not valid |
427 | Subscribed flag not valid on list LIST_NAME [Y, N] |
428 | Global suppression flag not valid [Y, N] |
429 | List no longer available due to Data Retention Policy |
480 | Users email address is on the Realtime Block List |
481 | Users email domain is on the Realtime Block List |
482 | Users email address is on the Application Level Block List |
483 | Users email domain is on the Application Level Block List |
490 | Account is disabled, API access denied |
Response Details
{
user_id: integer,Internal User ID
email_address: string,Unique email address
reference_code: string,Unique reference code
global_opt_out: string,Global Suppression is active [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
list_api_identifier: string,List API identifier
list_description: string,List name
subscribed: string,Opt-in preference active [Y,N]
subscribe_date: date,In the format YYYY-MM-DD HH:MM:SS
optout_date: dateIn the format YYYY-MM-DD HH:MM:SS
}
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Export Users on the Global Suppression List. The column layout of the exported file is specified using the Field Map API identifier. A date range can optionally provided to allow incremental updates to other systems.
This function will return the file within a compressed ZIP archive to minimise transfer times for large files.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
field_map_api_identifier | string | Field Map API Identifier | * Required |
export_type | string |
[ALL, API, AUTOCLEANSED, FBL, IMPORT, ADMIN or UNSUBSCRIPTION]
|
* Required |
date_from | date | Date from as YYYY-MM-DD | |
date_to | date | Date to as YYYY-MM-DD |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | List not found |
422 | export_type must be either ALL, API, AUTOCLEANSED, FBL, IMPORT, ADMIN or UNSUBSCRIPTION |
423 | Field Map API identifier is required when requesting exports |
424 | Unknown Import Format API Identifier |
425 | Invalid date from, please provide in the format YYYY-MM-DD |
426 | Invalid date to, please provide in the format YYYY-MM-DD |
427 | Date From occurs ahead of Date To, please check your dates are in the correct order |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Assign or remove User Tags associated one at a time for individual Users.
When assigning User Tags, if the an existing match is not found then the User Tag will be created and assigned to the User instantly.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Required |
action | string | Action [ADD, REMOVE] | * Required |
user_tag | string | Free-format text | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
422 | Email Address must be provided |
423 | Tag must be provided |
424 | Action must be either ADD or REMOVE |
425 | Tag not found |
404 | User not found |
490 | Account is disabled, API access denied |
Response Details
{
success: boolean"True", when action complete
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Individuals have the right to request that some or all of the data stored about them is removed.
Use the "Anonymise" option to permanently delete the User and all related data. An anonymous hash of the email address will be added to the Realtime Block List.
Use the "Blank" option to permanently delete the User and all related data. The email address will added to the Realtime Block List.
Use the 'Delete' option to permanently delete the User and all related data without any data being added to the Realtime Block List.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Required |
action | string | Action [ANONYMISE, BLANK, DELETE] | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
421 | Email Address must be provided |
422 | Email address not a valid format |
423 | Action must be either ANONYMISE, BLANK or DELETE |
404 | User not found |
490 | Account is disabled, API access denied |
Response Details
{
success: boolean"True", when action complete
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Identify recently updated User records within a specified period, the maximum period that can be downloaded per request is 24 Hours or 10,000 Users.
If the period is not provided the last 10,000 users will be returned.
Optionally filter the Users by modification source to capture updates from the API or a Preference Centre.
Valid requests return a JSON array containing the core user details, updated User data can be requested using the /users/details API endpoint.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
date_from | datetime | Date from as YYYY-MM-DD HH:MM:SS | |
date_to | datetime | Date to as YYYY-MM-DD HH:MM:SS | |
modified_source | string |
[ALL,ADMIN,IMPORT,API,PREF_CENTRE]
|
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No updated Users could be located using the currently selected criteria |
421 | Invalid date from, please provide in the format YYYY-MM-DD HH:MM:SS |
422 | Invalid date to, please provide in the format YYYY-MM-DD HH:MM:SS |
423 | Date From occurs ahead of Date To, please check your dates are in the correct order |
425 | Maximum permitted reporting period is 24 Hours |
426 | Response would contain more than 10,000 users request a shorter period or filter by source |
427 | Modified source is not valid is should be one of [ALL,ADMIN,IMPORT,API,PREF_CENTRE] |
428 | Both date from and date to are required when selecting by period |
431 | The requested download contains no Users |
490 | Account is disabled, API access denied |
Response Details
{
0: {
user_id: integer,Internal User ID
email_address: string,Unique Email address
reference_code: string,Unique Reference Code
date_modified: datetime,Date Last Updated
date_modified_source: stringDate Last Updated
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Download a list of Users that have verified their Email Address using a Preference Centre or Double Opt-in Workflow action.
Valid requests return a compressed ZIP archive in order to reduce transfer times of larger files. Use the optional 'filename' parameter to override the default naming convention of the zip file.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
filename | string | Preferred filename |
Response Type
application/zip
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No verified users could be located |
421 | Preferred filename is invalid; alpha-numeric, underscores and dashes only |
490 | Account is disabled, API access denied |
Response Details
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Show Email Verification attempts created by a Preference Centre or Workflow Double Opt-in action, the maximum period that can be downloaded per request is 30 Days.
If the period is not provided the last 10,000 requests will be returned.
Valid requests return a JSON array.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
date_from | datetime | Date from as YYYY-MM-DD HH:MM:SS | |
date_to | datetime | Date to as YYYY-MM-DD HH:MM:SS | |
filename | string | Preferred filename |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | No verification attempts could be located using the currently selected criteria |
421 | Invalid date from, please provide in the format YYYY-MM-DD HH:MM:SS |
422 | Invalid date to, please provide in the format YYYY-MM-DD HH:MM:SS |
423 | Date From occurs ahead of Date To, please check your dates are in the correct order |
425 | Maximum permitted reporting period is 30 days |
426 | Both date from and date to are required when selecting by period |
490 | Account is disabled, API access denied |
Response Details
{
0: {
user_id: integer,Internal User ID
email_address: string,Unique Email address
reference_code: string,Unique Reference Code
date_modified: datetime,Date Last Updated
date_modified_source: stringDate Last Updated
}...
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Record Data Processing or Marketing Consent for a User.
A unique Consent Code is required to identify the source of the consent.
To record Marketing consent include a List API Identifier representing the List to subscribe the User to.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Provide one only |
reference_code | string | Unique Reference Code | * Provide one only |
consent_code | string | Unique Consent Code | * Required |
consent_description | string | Consent description | * Required |
consent_type | string | Type of consent given [DATA, MARKETING] | * Required |
consent_list_api_identifier | string | [MARKETING] Consent List API Identifier | |
consent_ip_address | string | Optional Consent IP Address | |
consent_user_agent | string | Optional Consent User Agent String | |
global_opt_out | string | Global Suppression flag [Y or N] |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
420 | Email address or reference code is required |
421 | Only ONE of email address or reference code is required |
422 | Email address not valid |
426 | Global Suppression is not Y or N |
440 | Consent type is required |
441 | Consent description is required |
442 | Consent type must be [DATA] or [MARKETING] |
443 | Marketing Consent List API Identifier must be provided |
444 | List no longer available due to Data Retention Policy |
445 | List API Identifier is not valid |
446 | Consent Code is required |
447 | List API Identifier requires Marketing consent |
490 | Account is disabled, API access denied |
Response Details
{
consent_id: string,Internal Consent ID
consent_status: string,The status [PROVIDED, REVOKED]
consent_type: string,The type of Consent [DATA, MARKETING]
consent_source: string,The Consent source [FORM_SUBMISSION, API]
consent_source_id: string,Internal source ID
consent_count: integer,Number of times Consent has been recorded
consent_code: string,Unique Consent Code
consent_description: string,Consent description
consent_date: date,Date consent given
consent_ip_address: string,Consent IP Address
consent_user_agent: string,Consent User Agent String
global_opt_out: string,Global Suppression active [Y,N]
global_opt_out_date: date,In the format YYYY-MM-DD HH:MM:SS
global_opt_out_source: string[ADMIN, API, AUTOCLEANSED, IMPORT, UNSUBSCRIPTION]
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.
Usage Notes
Pass a valid 'consent_code' to remove matching Consent records from a User.
Parameters
Name | Data Type | Description | |
---|---|---|---|
api_id | string | Secure API ID | * Required |
api_key | string | Secure API key | * Required |
email_address | string | Email address | * Provide one only |
reference_code | string | Unique Reference Code | * Provide one only |
consent_code | string | Unique Consent Code | * Required |
consent_type | string | Type of consent given [DATA, MARKETING] | * Required |
Response Type
application/json
Status Codes
HTTP Code | Reason |
---|---|
400 | Bad request received |
403 | Insecure request received. Switch to HTTPS and try again |
404 | User not found |
420 | Email address or reference code is required |
421 | Only ONE of email address or reference code is required |
422 | Email address not valid |
423 | Consent code is required |
424 | Consent type is required |
425 | Consent type must be [DATA] or [MARKETING] |
426 | Matching Consent not found |
490 | Account is disabled, API access denied |
Response Details
{
success: boolean"True", when action complete
}
Manual Testing Disabled
Manual testing of API Endpoints using the explorer is only available when logged in.