NAV
json

Vision6 REST API

Welcome to the Vision6 REST API documentation.

The REST API supports transactional methods that can be used to trigger time-sensitive and critical communications. Examples are welcome packs, invoices (as attachments), statements, payment confirmations and password resets.

This API has:

If you're migrating from the JSON-RPC API then we suggest reading our Migration Guide.

Getting Started

Prior knowledge of programming with REST APIs is recommended before using Vision6 REST API. If you need assistance with your integration, please contact our support team who can help with any technical questions. Full Vision6 documentation is also available at https://support.vision6.com.au.

To prepare for sending emails you will need:

Resources and Endpoints

Collections, instances and endpoints are used to explain how to use the REST API.

Collection

A collection is a paginated resource with zero or more instances.

Collections have pluralised names such as /v1/lists, /v1/messages and /v1/transactional-groups.

Instance

An instance is a representation of an entity in the product or a container for a set of related data.

Instances are located at a collection resource followed by an id and have singular names such as /v1/messages/7847, /v1/lists/14/contacts/497 and /v1/messages/45/content.

Endpoint

An endpoint can list or act upon a resource.

Authentication

HTTP Headers:

Authorization: Bearer NzFiYTM4ZTEwMjcwZTcyZWIzZTA0NmY3NjE3MTIyMjM1Y2NlMmNlNWEyM

Authentication is required to ensure that platform data is secure for all requests. Bearer tokens are used to receive access tokens.

If an invalid Authorization value is provided an error will be emitted.

API Keys / Access Tokens

REST compatible API keys can be used as access tokens when sending requests. REST compatible API keys do not have expiry dates.

When creating new API keys only select the minimum access level required. Each endpoint within this documentation has a minimum access level required to complete a request. For more information on access levels, visit Users & Account Access Levels.

To validate that API keys are compatible with the REST API you can send a request to the API Root. If a 200 response is received then the API key is valid.

Wildcards

Wildcard Replacement with JSON Contact Fields Sample:

Your invite code is <a href="https://example.com/?code=%%event_code%%">%%event_code%%</a>.

Your invite code is <a href="https://example.com/?code=SUMMER-FESTIVAL">SUMMER-FESTIVAL</a>.

{
    "email": "henry@example.com",
    "event_code": "SUMMER-FESTIVAL"
}

Wildcards allow for key/value replacements within text. Wildcards are used to insert personalised or dynamic content into the templates.

The format for wildcards is %%wildcard_key%%. Wildcard key characters are required to be lowercase, alphanumeric or underscores.

Values that accept wildcards are:

Fallback Text

Wildcard Fallback Values with JSON Contact Fields Sample:

Dear %%first_name**Valued Customer%%!

Dear Valued Customer!

{
    "email": "frank@example.com",
    "first_name": ""
}

Fallback text replaces empty or not present values. For example, a contact may have an empty first name, so the fallback text is shown instead.

The format for wildcard fallbacks is %%wildcard_key**fallback text%%. Wildcard key characters are required to be lowercase, alphanumeric or underscores. Fallback text can be plain text.

It is recommended for fallbacks to be used only for short text. For more advanced requirements Conditional Wildcards should be used.

Conditional Wildcards

Conditional Wildcards with JSON Contact Fields Sample:

%%ticket_purchased:CONTAINS:vip%%
    <p>You are a VIP member.</p>
%%ticket_purchased:ELSE%%
    <p>Welcome to the event.</p>
%%ticket_purchased:END%%

%%customer_type:INCLUDES:business:OR:purchases:GREATERTHAN:3%%
    <p>We have the best promotion for you.</p>
%%customer_type:ELSEIF:purchases:GREATERTHAN:1%%
    <p>We have a promotion for you.</p>
%%customer_type:ELSE%%
    <p>Here are a selection of products you may like.</p>
%%customer_type:END%%

{
    "email": "ron@example.com",
    "ticket_purchased": "vip",
    "customer_type": "single",
    "purchases": 3
}

To make it easier to send templates with personalised content we provide conditional wildcards. Conditional wildcards allow for basic programmatic conditionals to be written within content. The wildcards that are available are based on recipient wildcards, attachments and existing contact fields.

Conditional wildcards, allow you to personalise content of an email based on certain data in a list field (or conditions) for a contact. Conditional wildcards allow for basic programmatic conditionals to be written within content. The wildcards that are available are based on recipient wildcards, attachments and existing contact fields.

Values that accept conditional wildcards are:

For more information on using conditional wildcards visit Advanced Conditional Wildcards.

Filters

Search by Contact Field:

GET /v1/lists/432/contacts?email=vincent@example.com

Search for Contacts with Multiple Conditions:

GET /v1/lists/432/contacts?source:ne=promo&city:in=brisbane,sydney

Resource payloads can be modified to return a filtered list of instances by providing query filters.

All values must match the field's type. i.e, you cannot supply a date value to an integer field.

Operator Description
= Return results that match the value.
Example: /v1/lists?name=Black%20Friday
:ne Return results that do not match the value.
Example: /v1/lists/45/contacts?promotion:ne=christmas
:in Return results that match the values in an array.
Example: /v1/messages?id:in=106,107

Ranges

Paginate Contacts by a Number Field:

GET /v1/lists/174/contacts?external_user_id:in=12000..&limit=100

Search Contacts that are Older than a Date:

GET /v1/lists/2974/contacts?creation_date:in=..2020-03-24T04:47:58Z

We allow resources to be filtered by values ranges with the combination of :in and .. operators. Values types are limited to integer, date and datetime.

Resource payloads are limited by the limit parameter.

Operator Range Description
:in=[start]..[end] Between Return results between the [start] and [end] values.
Example: /v1/messages?id:in=1..6
:in=[start].. Greater Than Return results that are greater than the [start] value.
Example: /v1/list/45/contacts?amount:in=50..
:in=..[end] Less Than Return results that are less than the [end] value.
Example: /v1/list/45/contacts?id:in=..10
:in=[start]..[end],
[start]..[end]		 Multiple Ranges Return results between multiple comma separated ranges.
Example: /v1/messages?id:in=1..6,100..120

Pagination

Using pagination you can avoid returning a large number of results by limiting them to a specific number.

Limits

Endpoint with Limits:

GET /v1/messages?limit=10

You can use the limit parameter to limit the number of results. By default, the limit is set to 100 but can be updated to return a maximum of 1,000 results.

This will limit the returned results to 10.

Offsetting

Endpoint with Limit and Offset:

GET /v1/messages?limit=10&offset=30

The offset parameter is used to paginate resources.

The example provided will offset the collection by 30, therefore returning the 31st to 40th collection objects.

Ordering

Collections are ordered by creation_time (descending) instance values by default. Additional order parameters are not supported.

Dates and Times

We support the following ISO 8601 formatted dates and times. These apply to both requests and responses.

The formats are:

Type Field Type Format Example
Timestamp timestamp YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS+0000 2020-04-05T23:46:02Z or 2020-04-05T10:00:00+1000
Datetime datetime YYYY-MM-DDTHH:MM:SS 2020-04-05T23:46:02
Date date YYYY-MM-DD 2020-04-05

All timestamps by default are in UTC. Datetime fields do not perform timezone alterations on request or response data.

API Discoverability

The goal of the API is to be extremely flexible and self discoverable. Every resource has a _links property detailing the location of that resource, parents or other instances. You can use these links to navigate through the API without knowledge of specific endpoints.

Expansions

Response with expanded children:

{
    "id": 3178,
    "name": "Customer List",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "/v1/lists/3178?expand=contacts"
        },
        "contacts": {
            "href": "/v1/lists/3178/contacts"
        }
    },
    "_embedded": {
        "contacts": {
            "offset": 0,
            "limit": 100,
            "size": 1,
            "_links": {
                "self": {
                    "href": "/v1/lists/3178/contacts"
                }
            },
            "_embedded": {
                "contacts": [
                    {
                        "id": 347,
                        "list_id": 3178,
                        "creation_time": "2020-04-05T23:46:02Z",
                        "last_modified_time": "2020-04-05T23:46:02Z",
                        "email": "john@example.com",
                        "mobile": "0400000000",
                        "subscribed": {
                            "email": true,
                            "mobile": true
                        },
                        "blocked": {
                            "email": false,
                            "mobile": false
                        },
                        "account_key": "hUIUyiu879",
                        "reply_to": "support@example.com",
                        "_links": {
                            "self": {
                                "href": "/v1/lists/3178/contacts/347"
                            },
                            "list": {
                                "href": "/v1/lists/3178"
                            }
                        }
                    }
                ]
            }
        }
    }
}

To allow for linked resources to be returned in responses we support expansions. By expanding responses more data can be returned and fewer API requests are required.

Expansion can be done via the expand query string parameter.

Rate Limiting

The API limits are:

We suggest that requests are to be sent from a single IP address, per account, at any time.

When sending a high number of requests we recommend monitoring concurrent requests to ensure that limits are not exceeded.

Automation Triggers

Automations allow you to send email or SMS messages based on various triggers. The following triggers are completed for the listed actions. For an overview on automations, along with a full list of triggers, visit our support article.

Standard Automations

Action/s Trigger
Create Contacts When a Contact is created from the REST API
Update Contacts When a Contact is updated from the REST API

Advanced Automations

Action/s Trigger
Create Contacts REST API Contact Created
Update Contacts REST API Contact Updated

API Root

Our API root provides access to all linked resources and access token details from the root url.

The Root Object

Example Object

{
    "access_token_scope": "report.view,contact.create",
    "access_token_creation_time": "2020-06-30T00:03:18Z",
    "access_token_expiry_time": null,
    "_links": {
        "self": {
            "href": "/v1/"
        },
        "lists": {
            "href": "/v1/lists"
        },
        "folders": {
            "href": "/v1/folders"
        },
        "messages": {
            "href": "/v1/messages"
        },
        "message_sender_defaults": {
            "href": "/v1/message-sender-defaults"
        },
        "reports": {
            "href": "/v1/reports"
        },
        "transactional_groups": {
            "href": "/v1/transactional-groups"
        },
        "transactional_sends": {
            "href": "/v1/transactional-sends"
        }
    }
}

Attributes

Field Description
access_token_scope string A comma separated list of scopes available.
Example: report.view,contact.create
access_token_creation_time string, timestamp The access token's creation time.
Example: 2020-04-05T23:46:02Z
access_token_expiry_time string, timestamp, nullable The access token's expiry time.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to top-level resources: lists, folders, messages, message_sender_defaults (Get message sender defaults), reports, transactional_groups, and transactional_sends. Message previews (/v1/message-previews) are available only when the account has the message preview feature enabled.

Get API Root

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "access_token_scope": "report.view,contact.create",
    "access_token_creation_time": "2020-06-30T00:03:18Z",
    "access_token_expiry_time": null,
    "_links": {
        "self": {
            "href": "/v1/"
        },
        "lists": {
            "href": "/v1/lists"
        },
        "folders": {
            "href": "/v1/folders"
        },
        "messages": {
            "href": "/v1/messages"
        },
        "message_sender_defaults": {
            "href": "/v1/message-sender-defaults"
        },
        "reports": {
            "href": "/v1/reports"
        },
        "transactional_groups": {
            "href": "/v1/transactional-groups"
        },
        "transactional_sends": {
            "href": "/v1/transactional-sends"
        }
    }
}

Returns all linked resources and access token details from the root url.

Endpoint

GET /v1/

Minimum API Key Access Level: Report Access

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Lists

A list is a collection of contacts. In Vision6, every list belongs in a list folder (see Folder type under Folders). Creating a list through this API always requires a folder_id for that folder. Responses include a folder link in _links when the backend returns a non-empty folder_id (the normal case).

You can create, rename, move, and delete lists with the REST endpoints below. You can also create lists via the JSON-RPC API or via the platform.

The List Object

Example List

{
    "id": 3178,
    "name": "Customer List",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "allow_send_to_duplicates": false,
    "on_register_address": [],
    "on_unsubscribe_address": [],
    "on_update_address": ["notifications@example.com"],
    "is_gdpr_compliant": false,
    "_links": {
        "self": {
            "href": "/v1/lists/3178"
        },
        "folder": {
            "href": "/v1/folders/12"
        },
        "contacts": {
            "href": "/v1/lists/3178/contacts"
        },
        "fields": {
            "href": "/v1/lists/3178/fields"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the instance.
Example: 3178
name string, nullable The instance's name.
Example: Customer List
creation_time string, timestamp The instance's creation time.
Example: 2020-04-05T23:46:02Z
last_modified_time string, timestamp The instance's last modified time.
Example: 2020-04-05T23:46:02Z
allow_send_to_duplicates boolean Allow sends to duplicate email or mobile addresses.
Example: false
on_register_address array of strings Addresses to notify when a contact is added.
Example: ["alerts@example.com"]
on_unsubscribe_address array of strings Addresses to notify when a contact unsubscribes.
Example: []
on_update_address array of strings Addresses to notify when a contact is updated.
Example: ["notifications@example.com"]
is_gdpr_compliant boolean Whether the list is marked as GDPR compliant.
Example: false
_links object Self discoverable links: self, contacts, fields, and folder pointing at the list’s folder when folder_id is present in the response (expected for normal lists; see Folders).

Get Lists

Get one or more lists with the following endpoints.

Get all Lists

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "offset": 0,
    "limit": 100,
    "size": 1,
    "_links": {
        "self": {
            "href": "/v1/lists"
        }
    },
    "_embedded": {
        "lists": [
            {
                "id": 3178,
                "name": "Customer List",
                "creation_time": "2020-04-05T23:46:02Z",
                "last_modified_time": "2020-04-05T23:46:02Z",
                "allow_send_to_duplicates": false,
                "on_register_address": [],
                "on_unsubscribe_address": [],
                "on_update_address": ["notifications@example.com"],
                "is_gdpr_compliant": false,
                "_links": {
                    "self": {
                        "href": "/v1/lists/3178"
                    },
                    "folder": {
                        "href": "/v1/folders/12"
                    },
                    "contacts": {
                        "href": "/v1/lists/3178/contacts"
                    },
                    "fields": {
                        "href": "/v1/lists/3178/fields"
                    }
                }
            }
        ]
    }
}

Returns a collection of your lists.

Endpoint

GET /v1/lists{?offset,limit,id,name,creation_time,last_modified_time,fields}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
offset integer, optional Pagination offset. See Offsetting.
Example: 0
limit integer, optional Page size (default 100, maximum 1,000). See Limits.
Example: 50
id integer, optional Filter IDs by number filters.
Example: 7
name string, optional Filter names by string filters.
Example: Customer List
creation_time string, timestamp, optional Filter creation times by date and time filters.
Example: 2019-12-20T04:12:00Z
last_modified_time string, timestamp, optional Filter last modified times by date and time filters.
Example: 2019-12-20T04:12:00Z
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • name
  • creation_time
  • last_modified_time
  • allow_send_to_duplicates
  • on_register_address
  • on_unsubscribe_address
  • on_update_address
  • is_gdpr_compliant
  • folder — include the folder link in _links when the list has a non-empty folder_id (see Folders).
Example: id,name

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Get a List

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 3178,
    "name": "Customer List",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "allow_send_to_duplicates": false,
    "on_register_address": [],
    "on_unsubscribe_address": [],
    "on_update_address": ["notifications@example.com"],
    "is_gdpr_compliant": false,
    "_links": {
        "self": {
            "href": "/v1/lists/3178"
        },
        "folder": {
            "href": "/v1/folders/12"
        },
        "contacts": {
            "href": "/v1/lists/3178/contacts"
        },
        "fields": {
            "href": "/v1/lists/3178/fields"
        }
    }
}

Returns the list with the given ID.

Endpoint

GET /v1/lists/{id}{?expand,fields}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
id integer, required Unique identifier for the instance.
Example: 89
expand string, optional Expand the response via one or more links. Multiple values can be grouped by commas. Values include:
  • contacts - Emit a collection of contacts linked to the list.
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • name
  • creation_time
  • last_modified_time
  • allow_send_to_duplicates
  • on_register_address
  • on_unsubscribe_address
  • on_update_address
  • is_gdpr_compliant
  • folder — include the folder link in _links when the list has a non-empty folder_id (see Folders).
Example: id,name

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Create a list

Create a new list with a display name and a target folder. The folder must be a list folder in your account (see Folder type under Folders).

Create a list

{
    "name": "Spring newsletter",
    "folder_id": 12,
    "allow_send_to_duplicates": false,
    "on_register_address": ["alerts@example.com"],
    "on_unsubscribe_address": [],
    "on_update_address": ["notifications@example.com"],
    "is_gdpr_compliant": false
}

HTTP Response

201 Created
content-type: application/json; charset=UTF-8

{
    "id": 3201,
    "name": "Spring newsletter",
    "creation_time": "2020-04-06T10:15:00Z",
    "last_modified_time": "2020-04-06T10:15:00Z",
    "allow_send_to_duplicates": false,
    "on_register_address": ["alerts@example.com"],
    "on_unsubscribe_address": [],
    "on_update_address": ["notifications@example.com"],
    "is_gdpr_compliant": false,
    "_links": {
        "self": {
            "href": "/v1/lists/3201"
        },
        "folder": {
            "href": "/v1/folders/12"
        },
        "contacts": {
            "href": "/v1/lists/3201/contacts"
        },
        "fields": {
            "href": "/v1/lists/3201/fields"
        }
    }
}

The response includes a Location header pointing to the new list when supported by the server.

Endpoint

POST /v1/lists

Minimum API Key Access Level: Standard Access

Attributes

Field Description
name string, required Name of the list.
Example: Spring newsletter
folder_id integer, required Id of the list folder to create the list in.
Example: 12
allow_send_to_duplicates boolean, optional Allow sends to duplicate email or mobile addresses.
on_register_address array of strings, optional Notify these addresses when a contact is added. Must be a JSON array of email addresses, not a comma-separated string. An empty array [] clears the setting.
on_unsubscribe_address array of strings, optional Notify these addresses when a contact unsubscribes. Must be a JSON array of email addresses, not a comma-separated string. An empty array [] clears the setting.
on_update_address array of strings, optional Notify these addresses when a contact is updated. Must be a JSON array of email addresses, not a comma-separated string. An empty array [] clears the setting.
is_gdpr_compliant boolean, optional Mark the list as GDPR compliant.

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
validation_error
Type: validation_errorStatus: 422		 The payload failed validation (for example missing name or folder_id, invalid folder, or backend rules). Details are returned in the error body when provided.
invalid_array
Type: validation_errorStatus: 422		 An address field was not a JSON array (for example a comma-separated string). Developer Message:
Must be an array
invalid_email_address
Type: validation_errorStatus: 422		 An element of on_register_address, on_unsubscribe_address, or on_update_address was not a valid email. The error field names the address property. Developer Message:
Must be a valid email address

Update a list

Update a list’s name and/or the folder it lives in.

Update a list

{
    "name": "Spring newsletter (2026)",
    "folder_id": 14,
    "allow_send_to_duplicates": true,
    "on_update_address": ["ops@example.com"]
}

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 3201,
    "name": "Spring newsletter (2026)",
    "creation_time": "2020-04-06T10:15:00Z",
    "last_modified_time": "2020-04-06T11:02:00Z",
    "allow_send_to_duplicates": true,
    "on_register_address": ["alerts@example.com"],
    "on_unsubscribe_address": [],
    "on_update_address": ["ops@example.com"],
    "is_gdpr_compliant": false,
    "_links": {
        "self": {
            "href": "/v1/lists/3201"
        },
        "folder": {
            "href": "/v1/folders/14"
        },
        "contacts": {
            "href": "/v1/lists/3201/contacts"
        },
        "fields": {
            "href": "/v1/lists/3201/fields"
        }
    }
}

Endpoint

PATCH /v1/lists/{id}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
id integer, required List to update.
Example: 3201

Attributes

Field Description
name string, optional New name for the list. When present, must be non-empty (not an empty string or whitespace-only). Omit name when you only want to move the list to another folder.
folder_id integer, optional Id of another list folder to move the list into.
allow_send_to_duplicates boolean, optional Allow sends to duplicate email or mobile addresses.
on_register_address array of strings, optional Notify these addresses when a contact is added. Must be a JSON array of email addresses, not a comma-separated string. An empty array [] clears the setting.
on_unsubscribe_address array of strings, optional Notify these addresses when a contact unsubscribes. Must be a JSON array of email addresses, not a comma-separated string. An empty array [] clears the setting.
on_update_address array of strings, optional Notify these addresses when a contact is updated. Must be a JSON array of email addresses, not a comma-separated string. An empty array [] clears the setting.
is_gdpr_compliant boolean, optional Mark the list as GDPR compliant.

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
invalid_request
Type: invalid_requestStatus: 400		 Message:
Cannot modify or delete this list
Developer Message:
List is a system list which cannot be modified. (System or non-mutable lists.)
not_found
Type: not_foundStatus: 404		 The list does not exist or is not visible for this account.
validation_error
Type: validation_errorStatus: 422		 Validation failed (for example empty or whitespace-only name when name is supplied); error details may reference a field name and message (see #list-errors in the error payload when present).
invalid_array
Type: validation_errorStatus: 422		 An address field was not a JSON array (for example a comma-separated string). Developer Message:
Must be an array
invalid_email_address
Type: validation_errorStatus: 422		 An element of on_register_address, on_unsubscribe_address, or on_update_address was not a valid email. The error field names the address property. Developer Message:
Must be a valid email address

Delete a list

Deletes a list and its contacts (subject to platform rules). This cannot be used on system lists.

HTTP Response

204 No Content
content-type: application/json; charset=UTF-8

A successful response returns 204 No Content with no JSON body.

Endpoint

DELETE /v1/lists/{id}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
id integer, required List to delete.
Example: 3201

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
invalid_request
Type: invalid_requestStatus: 400		 Message:
Cannot modify or delete this list
Developer Message:
List is a system list which cannot be modified.
not_found
Type: not_foundStatus: 404		 The list does not exist or is not visible for this account.

List Fields

A list field is the definition of a custom (or system) column on a list. It controls the label, data type, and behaviour of values stored against contacts in that list.

How those values appear on each contact record is described under List fields in the Contacts section (dynamic keys and types). This section documents the REST resource for creating, reading, updating, and deleting field definitions themselves.

For background on field types in the product UI, see our support article on list fields.

The list field object

Example list field

{
    "id": 42,
    "list_id": 3178,
    "label": "Company",
    "type": "text",
    "text_size": null,
    "row_size": null,
    "file_size": null,
    "date_format": null,
    "default_value": null,
    "drop_values": null,
    "drop_defaults": null,
    "date_default_type": null,
    "date_validation_type": null,
    "date_validation_from": null,
    "date_validation_to": null,
    "file_folder_id": null,
    "allowed_file_types": null,
    "is_mandatory": false,
    "is_shown_in_update": true,
    "is_shown_in_subscription": true,
    "is_shown_in_feedback": false,
    "_links": {
        "self": {
            "href": "/v1/lists/3178/fields/42"
        },
        "list": {
            "href": "/v1/lists/3178"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the field.
Example: 42
list_id integer Identifier of the list this field belongs to.
Example: 3178
label string Display name of the field.
Example: Company
type string Primary data type. Allowed values are listed under Field type below.
Example: text
text_size integer, nullable Maximum length for text-like fields when applicable.
row_size integer, nullable Number of rows for multi-line fields when applicable.
file_size integer, nullable Maximum upload size in bytes for file fields (type is file). Required when creating a file field. Maximum 15360000 (15 MB), matching the largest option in the product UI. Common values: 512000 (500KB), 1024000 (1MB), 2048000 (2MB), 5120000 (5MB), 10240000 (10MB), 15360000 (15MB). Each UI tier uses n * 1000 * 1024 bytes where n is 0.5, 1, 2, 5, 10, or 15.
date_format string, nullable How date/time values are shown. Allowed values are listed under Date format.
default_value string, nullable Default value for the field when applicable.
drop_values array, nullable Options for select, checkbox, and radio fields when applicable.
drop_defaults array, nullable Default selections for select, checkbox, and radio fields. An array of option strings that must appear in drop_values. Create and update persist and return those values (not [""]). Checkbox may include multiple defaults; select and radio typically one.
date_default_type string, nullable How the default date is determined. Allowed values are listed under Date default type.
date_validation_type string, nullable Date input validation mode. Allowed values are listed under Date validation type.
date_validation_from string, date, nullable Start of allowed date range when validation type is range. Uses date format.
date_validation_to string, date, nullable End of allowed date range when validation type is range. Uses date format.
file_folder_id integer, nullable Target folder for file uploads when applicable. Ids match folders returned by Get folders.
allowed_file_types array of strings, nullable Allowed file categories for file fields. Each element is one of the keys under Allowed file types.
is_mandatory boolean UI hint that the field should be required on forms (not a server-side enforcement flag for the API).
is_shown_in_update boolean Whether the field is shown on update profile forms.
is_shown_in_subscription boolean Whether the field is shown on subscribe forms.
is_shown_in_feedback boolean Whether the field is shown on feedback forms.
_links object self links to this field; list links to the parent list.

Field type

Values for type:

Field key Description
text Text
password Pass
select Select
checkbox Checkbox
radio Radio
textarea Textarea
html HTML Snippet
file File
numeric_decimal Numeric Decimal
numeric_currency Numeric Currency
dropdown_calendar Dropdown Calendar
dropdown_calendar_utc Dropdown Calendar (UTC)

File size

When type is file, set file_size to the maximum upload size in bytes. Values above 15360000 are rejected. The in-app field editor offers the same limits as these examples:

UI label file_size (bytes)
500KB 512000
1MB 1024000
2MB 2048000
5MB 5120000
10MB 10240000
15MB 15360000

Date format

Values for date_format:

Field key Description
date_only Date Only
time_12h 12 Hr
time_24h 24 Hr

Date default type

Values for date_default_type:

Field key Description
blank Blank
current Current
specific Specific

Date validation type

Values for date_validation_type:

Field key Description
past Past
future Future
range Range

Allowed file types

Values used as strings inside the allowed_file_types array:

Field key Description
images Images
documents Documents
spreadsheets Spreadsheets
movies Movies
other Other

Get list fields

Retrieve field definitions for a list using the endpoints below. Results are ordered by field id ascending. The default limit is 100 and the maximum is 1,000.

Get all list fields

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "offset": 0,
    "limit": 100,
    "size": 2,
    "_links": {
        "self": {
            "href": "/v1/lists/3178/fields"
        }
    },
    "_embedded": {
        "fields": [
            {
                "id": 12,
                "list_id": 3178,
                "label": "Email",
                "type": "text",
                "text_size": null,
                "row_size": null,
                "file_size": null,
                "date_format": null,
                "default_value": null,
                "drop_values": null,
                "drop_defaults": null,
                "date_default_type": null,
                "date_validation_type": null,
                "date_validation_from": null,
                "date_validation_to": null,
                "file_folder_id": null,
                "allowed_file_types": null,
                "is_mandatory": true,
                "is_shown_in_update": true,
                "is_shown_in_subscription": true,
                "is_shown_in_feedback": false,
                "_links": {
                    "self": {
                        "href": "/v1/lists/3178/fields/12"
                    },
                    "list": {
                        "href": "/v1/lists/3178"
                    }
                }
            },
            {
                "id": 42,
                "list_id": 3178,
                "label": "Company",
                "type": "text",
                "text_size": 255,
                "row_size": null,
                "file_size": null,
                "date_format": null,
                "default_value": null,
                "drop_values": null,
                "drop_defaults": null,
                "date_default_type": null,
                "date_validation_type": null,
                "date_validation_from": null,
                "date_validation_to": null,
                "file_folder_id": null,
                "allowed_file_types": null,
                "is_mandatory": false,
                "is_shown_in_update": true,
                "is_shown_in_subscription": true,
                "is_shown_in_feedback": false,
                "_links": {
                    "self": {
                        "href": "/v1/lists/3178/fields/42"
                    },
                    "list": {
                        "href": "/v1/lists/3178"
                    }
                }
            }
        ]
    }
}

Returns a collection of field definitions for the given list.

Endpoint

GET /v1/lists/{list_id}/fields{?offset,limit,id,label,type,text_size,row_size,file_size,date_format,default_value,drop_values,drop_defaults,date_default_type,date_validation_type,date_validation_from,date_validation_to,file_folder_id,allowed_file_types,is_mandatory,is_shown_in_update,is_shown_in_subscription,is_shown_in_feedback,fields}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
list_id integer, required Unique identifier of the list.
Example: 3178
offset integer, optional Pagination offset. See Offsetting.
Example: 0
limit integer, optional Page size (default 100, maximum 1,000). See Limits.
Example: 50
id integer, optional Filter by field id using Filters.
Example: 42
label string, optional Filter by label using Filters.
Example: Company
type string, optional Filter by primary type using Filters. Values are under Field type.
Example: text
text_size integer, optional Filter by text size using Filters.
row_size integer, optional Filter by row size using Filters.
file_size integer, optional Filter by file size using Filters.
date_format string, optional Filter by date format using Filters.
default_value string, optional Filter by default value using Filters.
drop_values array, optional Filter using Filters where supported for this field.
drop_defaults array, optional Filter using Filters where supported for this field.
date_default_type string, optional Filter by date default type using Filters.
date_validation_type string, optional Filter by date validation type using Filters.
date_validation_from string, date, optional Filter using Filters and date and time rules.
date_validation_to string, date, optional Filter using Filters and date and time rules.
file_folder_id integer, optional Filter by file folder id using Filters.
allowed_file_types array, optional Filter using Filters where supported for this field.
is_mandatory boolean, optional Filter by mandatory flag using Filters.
is_shown_in_update boolean, optional Filter using Filters.
is_shown_in_subscription boolean, optional Filter using Filters.
is_shown_in_feedback boolean, optional Filter using Filters.
fields string, optional Select the properties returned for each field. Multiple values can be separated by commas. Values include:
  • id
  • list_id
  • label
  • type
  • text_size
  • row_size
  • file_size
  • date_format
  • default_value
  • drop_values
  • drop_defaults
  • date_default_type
  • date_validation_type
  • date_validation_from
  • date_validation_to
  • file_folder_id
  • allowed_file_types
  • is_mandatory
  • is_shown_in_update
  • is_shown_in_subscription
  • is_shown_in_feedback
Example: id,label,type

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
not_found
Type: not_foundStatus: 404		 The list does not exist or is not visible for this account.

Get a list field

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 42,
    "list_id": 3178,
    "label": "Company",
    "type": "text",
    "text_size": 255,
    "row_size": null,
    "file_size": null,
    "date_format": null,
    "default_value": null,
    "drop_values": null,
    "drop_defaults": null,
    "date_default_type": null,
    "date_validation_type": null,
    "date_validation_from": null,
    "date_validation_to": null,
    "file_folder_id": null,
    "allowed_file_types": null,
    "is_mandatory": false,
    "is_shown_in_update": true,
    "is_shown_in_subscription": true,
    "is_shown_in_feedback": false,
    "_links": {
        "self": {
            "href": "/v1/lists/3178/fields/42"
        },
        "list": {
            "href": "/v1/lists/3178"
        }
    }
}

Returns the field with the given id on the list.

Endpoint

GET /v1/lists/{list_id}/fields/{id}{?fields}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
list_id integer, required Unique identifier of the list.
Example: 3178
id integer, required Unique identifier of the field.
Example: 42
fields string, optional Same values as Get all list fields.
Example: id,label,type

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
not_found
Type: not_foundStatus: 404		 The list or field does not exist or is not visible for this account.

Create a list field

Create a new field on a list. At minimum you must send label and type. Other properties follow The list field object and the constant tables above (null or omitted where not used).

Create a text field

{
    "label": "Company",
    "type": "text",
    "text_size": 255,
    "is_mandatory": false
}

HTTP Response

201 Created
content-type: application/json; charset=UTF-8

{
    "id": 42,
    "list_id": 3178,
    "label": "Company",
    "type": "text",
    "text_size": 255,
    "row_size": null,
    "file_size": null,
    "date_format": null,
    "default_value": null,
    "drop_values": null,
    "drop_defaults": null,
    "date_default_type": null,
    "date_validation_type": null,
    "date_validation_from": null,
    "date_validation_to": null,
    "file_folder_id": null,
    "allowed_file_types": null,
    "is_mandatory": false,
    "is_shown_in_update": true,
    "is_shown_in_subscription": true,
    "is_shown_in_feedback": false,
    "_links": {
        "self": {
            "href": "/v1/lists/3178/fields/42"
        },
        "list": {
            "href": "/v1/lists/3178"
        }
    }
}

Create a select field

{
    "label": "Preferred contact",
    "type": "select",
    "drop_values": ["Email", "Phone", "SMS"],
    "drop_defaults": ["Email"],
    "is_mandatory": false
}

HTTP Response

201 Created
content-type: application/json; charset=UTF-8

{
    "id": 55,
    "list_id": 3178,
    "label": "Preferred contact",
    "type": "select",
    "text_size": null,
    "row_size": null,
    "file_size": null,
    "date_format": null,
    "default_value": null,
    "drop_values": ["Email", "Phone", "SMS"],
    "drop_defaults": ["Email"],
    "date_default_type": null,
    "date_validation_type": null,
    "date_validation_from": null,
    "date_validation_to": null,
    "file_folder_id": null,
    "allowed_file_types": null,
    "is_mandatory": false,
    "is_shown_in_update": true,
    "is_shown_in_subscription": true,
    "is_shown_in_feedback": false,
    "_links": {
        "self": {
            "href": "/v1/lists/3178/fields/55"
        },
        "list": {
            "href": "/v1/lists/3178"
        }
    }
}

The response includes a Location header pointing to the new field when supported by the server.

Endpoint

POST /v1/lists/{list_id}/fields

Minimum API Key Access Level: Standard Access

Parameters

Field Description
list_id integer, required List to add the field to.
Example: 3178

Attributes

Field Description
label string, required Field name shown in the product and used to derive contact JSON keys (see List fields under Contacts).
type string, required Primary type; must be one of the keys under Field type.
text_size integer, optional Positive integer when applicable.
row_size integer, optional Positive integer when applicable.
file_size integer, optional Required for type file. Maximum upload size in bytes; see File size. Maximum 15360000 (15 MB).
date_format string, optional See Date format.
default_value string, optional Default value when applicable.
drop_values array, optional Option list for select, checkbox, and radio fields.
drop_defaults array, optional Default selections for select, checkbox, and radio. Each value must appear in drop_values. Persisted and returned on create and update (not [""]). Checkbox may include multiple defaults; select and radio typically one.
date_default_type string, optional See Date default type.
date_validation_type string, optional See Date validation type.
date_validation_from string, date, optional See The list field object.
date_validation_to string, date, optional See The list field object.
file_folder_id integer, optional File folder for uploads when applicable.
allowed_file_types array of strings, optional Subset of keys from Allowed file types.
is_mandatory boolean, optional Mandatory UI hint.
is_shown_in_update boolean, optional Show on update forms.
is_shown_in_subscription boolean, optional Show on subscribe forms.
is_shown_in_feedback boolean, optional Show on feedback forms.

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
invalid_request
Type: invalid_requestStatus: 400		 Message:
Cannot create, modify or delete fields in this list
Developer Message:
List is a system list which cannot be modified. (Sent when the list is not mutable.)
validation_error
Type: validation_errorStatus: 422		 Request or field payload failed validation (for example unknown type, invalid combination, or backend rule). Details are returned in the error body when provided.

Update a list field

Send a JSON body with the properties to change.

Update a list field

{
    "label": "Organisation",
    "is_mandatory": true
}

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 42,
    "list_id": 3178,
    "label": "Organisation",
    "type": "text",
    "text_size": 255,
    "row_size": null,
    "file_size": null,
    "date_format": null,
    "default_value": null,
    "drop_values": null,
    "drop_defaults": null,
    "date_default_type": null,
    "date_validation_type": null,
    "date_validation_from": null,
    "date_validation_to": null,
    "file_folder_id": null,
    "allowed_file_types": null,
    "is_mandatory": true,
    "is_shown_in_update": true,
    "is_shown_in_subscription": true,
    "is_shown_in_feedback": false,
    "_links": {
        "self": {
            "href": "/v1/lists/3178/fields/42"
        },
        "list": {
            "href": "/v1/lists/3178"
        }
    }
}

Endpoints

PATCH /v1/lists/{list_id}/fields/{id}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
list_id integer, required List that owns the field.
Example: 3178
id integer, required Field to update.
Example: 42

Attributes

Field Description

Attributes follow Create a list field. All properties in the request body are optional for an update except where the server requires specific fields for a given operation; send only the values you want to change (especially when using PATCH).

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
invalid_request
Type: invalid_requestStatus: 400		 Message:
Cannot create, modify or delete fields in this list
Developer Message:
List is a system list which cannot be modified.
not_found
Type: not_foundStatus: 404		 The list or field does not exist or is not visible for this account.
validation_error
Type: validation_errorStatus: 422		 Validation failed; error details may reference a field name and message.

Delete a list field

Deletes a single field definition from a list. This does not remove historical values from contact records in bulk; behaviour of existing data is governed by the platform.

HTTP Response

204 No Content
content-type: application/json; charset=UTF-8

A successful response returns 204 No Content with no JSON body.

Endpoint

DELETE /v1/lists/{list_id}/fields/{id}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
list_id integer, required List that owns the field.
Example: 3178
id integer, required Field to delete.
Example: 42

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
invalid_request
Type: invalid_requestStatus: 400		 Message:
Cannot create, modify or delete fields in this list
Developer Message:
List is a system list which cannot be modified.
not_found
Type: not_foundStatus: 404		 The list or field does not exist or is not visible for this account.

Folders

Folders group content in your account. Lists live in folders of type list, messages in folders of type message, and files live in folders of type file. Lists and messages are always stored under an appropriate folder in the product. The REST API exposes folders as a read-only resource so integrations can resolve folder ids (for example when creating a list, or file_folder_id on list fields) to names and metadata.

At this time, Folders cannot be created, renamed, or deleted through this API.

The folder object

Example folder

{
    "id": 1204,
    "name": "Uploads",
    "creation_time": "2020-04-05T23:46:02Z",
    "type": "file",
    "size": 18,
    "_links": {
        "self": {
            "href": "/v1/folders/1204"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the folder.
Example: 1204
name string, nullable The folder name.
Example: Uploads
creation_time string, timestamp When the folder was created.
Example: 2020-04-05T23:46:02Z
type string Folder category. Allowed values are listed under Folder type.
Example: file
size integer Number of items in the folder (for example lists or files), as reported by the platform.
Example: 18
_links object self links to this folder.

Folder type

Values for type:

Field key Description
list List
message Message
file File

Get folders

Retrieve folder metadata with the endpoints below. Collections are ordered by folder id ascending. The default limit is 100 and the maximum is 1,000.

Get all folders

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "offset": 0,
    "limit": 100,
    "size": 2,
    "_links": {
        "self": {
            "href": "/v1/folders"
        }
    },
    "_embedded": {
        "folders": [
            {
                "id": 1204,
                "name": "Uploads",
                "creation_time": "2020-04-05T23:46:02Z",
                "type": "file",
                "size": 18,
                "_links": {
                    "self": {
                        "href": "/v1/folders/1204"
                    }
                }
            },
            {
                "id": 3178,
                "name": "Customer lists",
                "creation_time": "2020-03-01T12:00:00Z",
                "type": "list",
                "size": 4,
                "_links": {
                    "self": {
                        "href": "/v1/folders/3178"
                    }
                }
            }
        ]
    }
}

Returns a collection of folders in your account.

Endpoint

GET /v1/folders{?offset,limit,id,name,creation_time,type,size,fields}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
offset integer, optional Pagination offset. See Offsetting.
Example: 0
limit integer, optional Page size (default 100, maximum 1,000). See Limits.
Example: 50
id integer, optional Filter by folder id using Filters.
Example: 1204
name string, optional Filter by name using Filters.
Example: Uploads
creation_time string, timestamp, optional Filter by creation time using date and time filters.
Example: 2019-12-20T04:12:00Z
type string, optional Filter by folder type using Filters. Values are under Folder type.
Example: file
size integer, optional Filter by item count using Filters.
Example: 10
fields string, optional Select the properties returned for each folder. Multiple values can be separated by commas. Values include:
  • id
  • name
  • creation_time
  • type
  • size
Example: id,name,type

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Get a folder

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 1204,
    "name": "Uploads",
    "creation_time": "2020-04-05T23:46:02Z",
    "type": "file",
    "size": 18,
    "_links": {
        "self": {
            "href": "/v1/folders/1204"
        }
    }
}

Returns the folder with the given id.

Endpoint

GET /v1/folders/{id}{?fields}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
id integer, required Unique identifier for the folder.
Example: 1204
fields string, optional Same values as Get all folders.
Example: id,name

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
not_found
Type: not_foundStatus: 404		 The folder does not exist or is not visible for this account.

Contacts

A contact is an individual in one of your lists.

Recommendations when managing contacts are:

List Fields

Example Contact with Additional Fields

{
    "id": 347,
    "list_id": 3178,
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "email": "john@example.com",
    "mobile": "0400000000",
    "blocked": {
        "email": false,
        "mobile": false
    },
    "subscribed": {
        "email": true,
        "mobile": true
    },
    "is_active": true,
    "double_opt_in": true,
    "double_opt_in_time": "2020-04-05T23:46:02Z",
    "account_key": "hUIUyiu879",
    "reply_to": "support@example.com",
    "_links": {
        "self": {
            "href": "/v1/lists/3178/contacts/347"
        },
        "list": {
            "href": "/v1/lists/3178"
        }
    }
}

Contact instances often contain additional fields, based on their list fields. These fields will be added to each instance automatically.

Field names will be converted to wildcard accepted keys with lowercase, alphanumeric and underscore characters. e.g, the name Reply-To will be converted to the key reply_to.

List fields can be searched using filters, however be sure to convert the field names to keys. e.g, Filter Account Key via the query ?account_key=hUIUyiu879.

For more information on list fields, visit our support article.

Field Types

These are the available list fields with value types and examples.

Field Description
Email string This field type is the email attribute within contact instances. Only one email field can be created within a list.
Example: richard@example.com
Mobile Phone string This field type is the mobile attribute within contact instances. Only one mobile phone field can be created within a list.
Example: 0422111333
Phone Number string Example: 0422333111
First Name string Example: Cameron
Last Name string Example: Johnston
Address Line string Example: 123 Example St, Brisbane, QLD
Suburb string Example: Brisbane
Postcode or ZIP Code string Example: 4000
Website Address / URL string Example: https://www.vision6.com.au
State string Example: Queensland
Gender string Example: Female
Country string Example: Australia
Industry string Example: Community & Sport
Date of Birth string, date Example: 1990-01-01
Unsubscribe Reason string Example: I no longer want to receive these emails
Unsubscribe Feedback string Example: My unsubscribe reason is...
Text Field string Example: Free Text!
Password Field string Example: passw0rd
Currency float Example: 123456.12
Number float Example: 45.124
Dropdown string Example: Selected Value
Date Picker string, date or datetime Example: 2020-04-01
Radio Buttons string Example: option1
Checkbox string Example: option1,option2
Comment Field string Example: This is a comment!
HTML Snippet string Example: <b>This is an HTML snippet!</b>
File Upload string Example: [file_url]

Reserved Field Names

If a field name is converted to one of the following keys, their value will be ignored.

The Contact Object

Example Contact

{
    "id": 347,
    "list_id": 3178,
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "email": "john@example.com",
    "mobile": "0400000000",
    "blocked": {
        "email": false,
        "mobile": false
    },
    "subscribed": {
        "email": true,
        "mobile": true
    },
    "is_active": true,
    "double_opt_in": true,
    "double_opt_in_time": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "/v1/lists/3178/contacts/347"
        },
        "list": {
            "href": "/v1/lists/3178"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the instance.
Example: 347
list_id integer The list id of the list that the contact is in.
Example: 3178
creation_time string, timestamp The instance's creation time.
Example: 2020-04-05T23:46:02Z
last_modified_time string, timestamp The instance's last modified time.
Example: 2020-04-05T23:46:02Z
email string, nullable The email of the contact.
Example: john@example.com
mobile string, nullable The mobile phone number of the contact.
Example: 0400000000
subscribed object The subscribed status of the contact.
subscribed.email boolean True if the contact's email is subscribed.
Example: true
subscribed.mobile boolean True is the contact's mobile phone number is subscribed.
Example: true
blocked object The blocked status of the contact.
blocked.email boolean True if the contact's email is blocked.
Example: false
blocked.mobile boolean True if the contact's mobile phone number is blocked.
Example: false
is_active boolean The active status of the contact.
Example: true
double_opt_in boolean Whether or not the contact has confirmed their subscription via email.

Updating the double opt in time via the API is handy when your contacts have already verified their email via another product.

How double opt ins can help your email sends can be found in Improve Deliverability & Open Rates With a Double Opt-In Process.
Example: true
double_opt_in_time timestamp, nullable The time that the contact confirmed their subscription via email.
Example: 2020-04-05T23:46:02Z
[list_fields] string, optional List fields are dynamically inserted with converted names to keys. Keys only use lowercase, alphanumeric or underscore characters. Values are to the field type.
Example: 03/06/20
_links object Self discoverable links to the current object are provided.

Get Contacts

Get all Contacts

Get all Contacts

GET /v1/lists/174/contacts

Filter by Creation Time

GET /v1/lists/174/contacts?creation_time:in=2019-12-20T04:12:00Z..

Filter by List Field

GET /v1/lists/174/contacts?landing_page=new_years

Filter by Multiple List Fields

GET /v1/lists/174/contacts?landing_page=new_years&country=AU

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "offset": 0,
    "limit": 100,
    "size": 1,
    "_links": {
        "self": {
            "href": "/v1/lists/3178/contacts"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 347,
                "list_id": 3178,
                "creation_time": "2020-04-05T23:46:02Z",
                "last_modified_time": "2020-04-05T23:46:02Z",
                "email": "john@example.com",
                "mobile": "0400000000",
                "blocked": {
                    "email": false,
                    "mobile": false
                },
                "subscribed": {
                    "email": true,
                    "mobile": true
                },
                "is_active": true,
                "double_opt_in": false,
                "double_opt_in_time": null,
                "_links": {
                    "self": {
                        "href": "/v1/lists/3178/contacts/347"
                    },
                    "list": {
                        "href": "/v1/lists/3178"
                    }
                }
            }
        ]
    }
}

Returns a collection of your contacts within a linked list.

Endpoint

GET /v1/lists/{list_id}/contacts{?id,email,mobile,creation_time,last_modified_time,is_active,double_opt_in,double_opt_in_time,[list_fields],fields}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
list_id integer, required Unique identifier for the linked list.
Example: 3178
id integer, optional Filter IDs by number filters.
Example: 347
email string, optional Filter email addresses by string filters.
Example: dan@example.com
mobile string, optional Filter mobile numbers by string filters.
Example: 0400000000
creation_time string, timestamp, optional Filter creation times by date and time filters.
Example: 2019-12-20T04:12:00Z
last_modified_time string, timestamp, optional Filter last modified times by date and time filters.
Example: 2019-12-20T04:12:00Z
is_active boolean, optional The active status of the contact.
Example: false
double_opt_in boolean, optional Whether or not the contact has confirmed their subscription via email.
Example: true
double_opt_in_time timestamp, optional The datetime of when the contact confirmed their subscription via email.
Example: 2020-04-06T08:21:00Z
[list_fields] string, optional List fields may be filtered when their names are converted keys. Keys only use lowercase, alphanumeric or underscore characters. Values are to match the field type.
Example: 03/06/20
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • list_id
  • creation_time
  • last_modified_time
  • email
  • mobile
  • subscribed
  • blocked
  • creation_time
  • last_modified_time
  • is_active
  • double_opt_in
  • double_opt_in_time
  • [list_fields]
Example: id,email,account_key

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Get a Contact

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 347,
    "list_id": 3178,
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "email": "john@example.com",
    "mobile": "0400000000",
    "blocked": {
        "email": false,
        "mobile": false
    },
    "subscribed": {
        "email": true,
        "mobile": true
    },
    "is_active": true,
    "double_opt_in": false,
    "double_opt_in_time": null,
    "_links": {
        "self": {
            "href": "/v1/lists/3178/contacts/347"
        },
        "list": {
            "href": "/v1/lists/3178"
        }
    }
}

Returns the contact with the given ID within a linked list.

Endpoint

GET /v1/lists/{list_id}/contacts/{id}{?fields}

Minimum API Key Access Level: Standard Access

Parameters

Field Description
list_id integer, required Unique identifier for the linked list.
Example: 3178
id integer, required Unique identifier for the instance.
Example: 347
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • list_id
  • creation_time
  • last_modified_time
  • email
  • mobile
  • subscribed
  • blocked
  • creation_time
  • last_modified_time
  • is_active
  • double_opt_in
  • double_opt_in_time
  • [list_fields]
Example: id,email

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Create Contacts

Create one or more contacts with the following endpoints.

Create Multiple Contacts

Create multiple contacts within a single request.

Create Multiple Contacts

{
    "contacts": [
        {
            "email": "scott@example.com",
            "account_key": "pwNtDm2h"
        },
        {
            "mobile": "0400000000",
            "subscribed": {
                "email": false,
                "mobile": true
            }
        }
    ]
}

HTTP Response

204 No Content
content-type: application/json; charset=UTF-8

Endpoint

POST /v1/lists/{list_id}/contacts{?remove_unsubscribers}

Minimum API Key Access Level: Standard Access

Attributes

Field Description
contacts array, required A collection of contact instances.
contacts.* object, required Each contact instance can use the attributes outlined in Create a Single Contact. A maximum of 1000 contact instances can be sent per request.

Parameters

Field Description
remove_unsubscribers string, optional This parameter provides the ability to not create contacts if they have an email and/or mobile field as an address within the unsubscriber list.

Defaults to none. Values include:
  • any - Do not create contact instances that have an email and/or mobile field that matches an address within the unsubscribers list for the account.
  • list - Do not create contact instances that have an email and/or mobile field that matches an address within the unsubscribers list for the requested list.
  • none - Create all contacts instances without checking for unsubscribers.
Example: any

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
field_email_not_in_list
Type: validation_errorStatus: 422		 Message:
The list does not contain an email type field
Developer Message:
An email address field is required on the list in order to save this field
field_mobile_not_in_list
Type: validation_errorStatus: 422		 Message:
The list does not contain a mobile phone type field
Developer Message:
A mobile phone address field is required on the list in order to save this field
no_subscribed_addresses
Type: validation_errorStatus: 422		 Message:
No contacts created
Developer Message:
No contacts were created due to the state of the remove_unsubscribers query parameter in the request.
list_not_mutable
Type: validation_errorStatus: 422		 Message:
Cannot create, modify or delete contacts in this list
Developer Message:
List is a system list which cannot be modified.

Create a Single Contact

Create with an Email Address

{
    "email": "mal@example.com",
    "mobile": "0400000000",
    "account_key": "pwNtDm2h"
}

Subscribe and mark as already verified their email via another product

{
    "email": "sam@example.com",
    "double_opt_in": true
}

HTTP Response

201 Created
content-type: application/json; charset=UTF-8

{
    "id": 347,
    "list_id": 3178,
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "email": "john@example.com",
    "mobile": "0400000000",
    "blocked": {
        "email": false,
        "mobile": false
    },
    "subscribed": {
        "email": true,
        "mobile": true
    },
    "is_active": true,
    "double_opt_in": false,
    "double_opt_in_time": null,
    "account_key": "pwNtDm2h",
    "_links": {
        "self": {
            "href": "/v1/lists/3178/contacts/347"
        },
        "list": {
            "href": "/v1/lists/3178"
        }
    }
}

Returns the new contact instance.

Endpoint

POST /v1/lists/{list_id}/contacts{?remove_unsubscribers}

Minimum API Key Access Level: Standard Access

Attributes

Field Description
email string, optional The email of the contact.
Example: john@example.com
mobile string, optional The mobile phone number of the contact.
Example: 0400000000
[list_fields] string, optional List fields can be submitted when their name is has been converted to only use lowercase, alphanumeric or underscore characters. Values must match the field type.
Example: 03/06/20
subscribed object, optional The subscribed status of the contact.
subscribed.email boolean, optional True if the contact's email is subscribed.
Example: true
subscribed.mobile boolean, optional True is the contact's mobile phone number is subscribed.
Example: true
is_active boolean, optional The active status of the contact.
Example: true
double_opt_in boolean, optional If set to true then double_opt_in_time will be updated to the current time.

Allowing a contact to be double opted in via the API is handy when your contacts have already verified their email via another product.

How double opt ins can help your email sends can be found in Improve Deliverability & Open Rates With a Double Opt-In Process.
Example: true

Parameters

Field Description
remove_unsubscribers string, optional This parameter provides the ability to not create contacts if they have an email and/or mobile field as an address within the unsubscriber list.

Defaults to none. Values include:
  • any - Do not create contact instances that have an email and/or mobile field that matches an address within the unsubscribers list for the account.
  • list - Do not create contact instances that have an email and/or mobile field that matches an address within the unsubscribers list for the requested list.
  • none - Create all contacts instances without checking for unsubscribers.
Example: any

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
field_email_not_in_list
Type: validation_errorStatus: 422		 Message:
The list does not contain an email type field
Developer Message:
An email address field is required on the list in order to save this field
field_mobile_not_in_list
Type: validation_errorStatus: 422		 Message:
The list does not contain a mobile phone type field
Developer Message:
A mobile phone address field is required on the list in order to save this field
no_subscribed_addresses
Type: validation_errorStatus: 422		 Message:
No contacts created
Developer Message:
No contacts were created due to the state of the remove_unsubscribers query parameter in the request.
list_not_mutable
Type: validation_errorStatus: 422		 Message:
Cannot create, modify or delete contacts in this list
Developer Message:
List is a system list which cannot be modified.

Update Contacts

Update one or more contacts with the following endpoints.

Update Multiple Contacts

Update multiple contacts within a single request.

Update Multiple Contacts

{
    "contacts": [
        {
            "id": 748,
            "email": "richard@example.com",
            "account_key": "pwNtDm2h"
        },
        {
            "id": 14,
            "mobile": "0400000000",
            "subscribed": {
                "email": false,
                "mobile": true
            }
        }
    ]
}

HTTP Response

204 No Content
content-type: application/json; charset=UTF-8

Endpoint

PATCH /v1/lists/{list_id}/contacts

Minimum API Key Access Level: Standard Access

Attributes

Field Description
contacts array, required A collection of contact instances.
contacts.* object, required Each contact instance can use the attributes outlined in Update a Single Contact. A maximum of 1000 contact instances can be sent per request.
contacts.*.id integer, required Unique identifier for the instance.
Example: 3178

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
field_email_not_in_list
Type: validation_errorStatus: 422		 Message:
The list does not contain an email type field
Developer Message:
An email address field is required on the list in order to save this field
field_mobile_not_in_list
Type: validation_errorStatus: 422		 Message:
The list does not contain a mobile phone type field
Developer Message:
A mobile phone address field is required on the list in order to save this field
cannot_reset_double_opt_in
Type: validation_errorStatus: 422		 Message:
Double opt-in flag cannot be reset
Developer Message:
Double opt-in cannot be reset to false once it has been set to true
list_not_mutable
Type: validation_errorStatus: 422		 Message:
Cannot create, modify or delete contacts in this list
Developer Message:
List is a system list which cannot be modified.

Update a Single Contact

Update Contact

{
    "email": "john@example.com",
    "mobile": "0400000000",
    "account_key": "pwNtDm2h"
}

Unsubscribe via Email Address

{
    "subscribed": {
        "email": false,
        "mobile": true
    }
}

Mark as Already Verified (by Email Address) via Another Product

{
    "email": "sam@example.com",
    "double_opt_in": true
}

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 347,
    "list_id": 3178,
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "email": "john@example.com",
    "mobile": "0400000000",
    "blocked": {
        "email": false,
        "mobile": false
    },
    "subscribed": {
        "email": true,
        "mobile": true
    },
    "is_active": true,
    "double_opt_in": false,
    "double_opt_in_time": null,
    "account_key": "pwNtDm2h",
    "_links": {
        "self": {
            "href": "/v1/lists/3178/contacts/347"
        },
        "list": {
            "href": "/v1/lists/3178"
        }
    }
}

Returns the updated contact instance.

Endpoint

PATCH /v1/lists/{list_id}/contacts/{id}

Minimum API Key Access Level: Standard Access

Attributes

Field Description
email string, optional The email of the contact.
Example: john@example.com
mobile string, optional The mobile phone number of the contact.
Example: 0400000000
[list_fields] string, optional List fields can be submitted when their name is has been converted to only use lowercase, alphanumeric or underscore characters. Values must match the field type.
Example: 03/06/20
subscribed object, optional The subscribed status of the contact.
subscribed.email boolean, optional True if the contact's email is subscribed.
Example: true
subscribed.mobile boolean, optional True is the contact's mobile phone number is subscribed.
Example: true
is_active boolean, optional The active status of the contact.
Example: true
double_opt_in boolean, optional If set to true then double_opt_in_time will be updated to the current time. Once a double_opt_in_time is not null it cannot be reverted.

Allowing a contact to be double opted in via the API is handy when your contacts have already verified their email via another product.

How double opt ins can help your email sends can be found in Improve Deliverability & Open Rates With a Double Opt-In Process.
Example: true

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
field_email_not_in_list
Type: validation_errorStatus: 422		 Message:
The list does not contain an email type field
Developer Message:
An email address field is required on the list in order to save this field
field_mobile_not_in_list
Type: validation_errorStatus: 422		 Message:
The list does not contain a mobile phone type field
Developer Message:
A mobile phone address field is required on the list in order to save this field
cannot_reset_double_opt_in
Type: validation_errorStatus: 422		 Message:
Double opt-in flag cannot be reset
Developer Message:
Double opt-in cannot be reset to false once it has been set to true
list_not_mutable
Type: validation_errorStatus: 422		 Message:
Cannot create, modify or delete contacts in this list
Developer Message:
List is a system list which cannot be modified.

Delete Contacts

Delete one or more contacts within a single request.

Delete Multiple Contacts via Query Parameters

DELETE /v1/lists/174/contacts?id:in=47,14,98

Delete a Single Contact via Query Parameters

DELETE /v1/lists/174/contacts?id=674

Delete a Single Contact via URL Values

DELETE /v1/lists/174/contacts/28

HTTP Response

204 No Content
content-type: application/json; charset=UTF-8

Endpoint

DELETE /v1/lists/{list_id}/contacts{?id}

Minimum API Key Access Level: Standard Access

Synchronous Actions

All contacts are deleted synchronously when sending as a collection. What does this mean for requests?

Parameters

Field Description
id integer, optional Filter IDs by number filters. A maximum of 1000 contact ids can be sent per request.
Example: 7,12,354

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
list_not_mutable
Type: validation_errorStatus: 422		 Message:
Cannot create, modify or delete contacts in this list
Developer Message:
List is a system list which cannot be modified.
filter_id_required
Type: validation_errorStatus: 422		 Message:
Missing id filter in query string
Developer Message:
Bulk delete requests must include an "id=" or "id:in=" query parameter

Messages

A message is the metadata for an email or SMS message. Contacts can be sent messages. Every message has a message folder (see Folder type under Folders). When you create a message you may supply folder_id, or omit it to use the API default (the message folder with the lowest id). Use the folder link in _links to load that folder’s metadata.

The contents of messages are stored within a linked message content instance. These include the HTML/plain text for email message types and text for SMS message types. Message content can be customised with the use of wildcards and conditional wildcards.

You can create, update, and delete messages and save or update message content with the REST endpoints in this section. You can also create messages via the JSON-RPC API or via the platform.

Account default sender details

For email messages, your account stores default from name, from address, and reply-to values. Users update these in the application when they save sender details for future sends (for example Save for future sends on message details). When you omit from_address and/or reply_to on POST /v1/messages while creating a new email, the platform may populate those fields from these stored defaults.

Use Get message sender defaults to read the current values. Send explicit from_address and reply_to whenever your integration must not depend on account defaults that can change when users save details in the UI.

The Message Object

Example Message

{
    "id": 4847,
    "name": "Reset Password",
    "type": "email",
    "subject": "You requested to reset your password",
    "from_name": "Company Name",
    "from_address": "company@example.com",
    "reply_to": "company@example.com",
    "thumbnail_url": "",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "/v1/messages/4847"
        },
        "folder": {
            "href": "/v1/folders/12"
        },
        "content": {
            "href": "/v1/messages/4847/content"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the instance.
Example: 4847
name string The name of the message.
Example: Reset Password
type enum, fixed The type of message. Values include email and sms.
Example: email
subject string, nullable The subject of the message.
Example: You requested to reset your password
from_name string, nullable The from name of the sender.
Example: Company Name
from_address string, nullable The from address of the sender.
Example: company@example.com
reply_to string, nullable The reply-to address of the sender.
Example: company@example.com
thumbnail_url string, nullable The URL of the thumbnail generated for the message.
creation_time string, timestamp The instance's creation time.
Example: 2020-04-05T23:46:02Z
last_modified_time string, timestamp The instance's last modified time.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object, the message’s folder when folder_id is present in the response (expected in normal use), and message content.

The Message Content Object

{
    "message_id": 4847,
    "body_html": "<html><body>Email</body></html>",
    "body_text": "Email",
    "_links": {
        "self": {
            "href": "/v1/messages/4847/content"
        },
        "message": {
            "href": "/v1/messages/4847"
        }
    }
}

Attributes

Field Description
message_id integer Unique identifier for the instance.
Example: 4847
body_html string, nullable The HTML body of the message (email message type only).
Example: <html><body>Email</body></html>
body_text string, nullable The text body of the message (both sms and email message types).
Example: Email
For email_type html (HTML-only) messages, the platform may return null here even when a plain string was supplied on write, because that email type does not expose a separate stored text part the same way plain or plain-html does.
_links object Self discoverable links to the current object and message are provided.

Get message sender defaults

Returns the account-level default from_name, from_address, and reply_to used when creating a new email message without those fields in the JSON body. Requires the message.view scope (see Account default sender details). Any field may be null if no default is stored.

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "from_name": "Company Name",
    "from_address": "company@example.com",
    "reply_to": "replies@example.com",
    "_links": {
        "self": {
            "href": "/v1/message-sender-defaults"
        }
    }
}

Endpoint

GET /v1/message-sender-defaults

Minimum API Key Access Level: Limited Access

Attributes

Field Description
from_name string, nullable Default display name applied to new email messages when from_name is not supplied on create.
from_address string, nullable Default From address applied when from_address is omitted on create.
reply_to string, nullable Default Reply-To address applied when reply_to is omitted on create.
_links object Self discoverable links to the current object.

Get Messages

Get one or more messages with the following endpoints.

Get all Messages

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "offset": 0,
    "limit": 100,
    "size": 1,
    "_links": {
        "self": {
            "href": "/v1/messages"
        }
    },
    "_embedded": {
        "messages": [
            {
                "id": 4847,
                "name": "Reset Password",
                "type": "email",
                "subject": "You requested to reset your password",
                "from_name": "Company Name",
                "from_address": "company@example.com",
                "reply_to": "company@example.com",
                "thumbnail_url": "",
                "creation_time": "2020-04-05T23:46:02Z",
                "last_modified_time": "2020-04-05T23:46:02Z",
                "_links": {
                    "self": {
                        "href": "/v1/messages/4847"
                    },
                    "folder": {
                        "href": "/v1/folders/12"
                    },
                    "content": {
                        "href": "/v1/messages/4847/content"
                    }
                }
            }
        ]
    }
}

Returns a collection of your messages.

Endpoint

GET /v1/messages{?id,type,name,subject,from_name,from_address,reply_to,thumbnail_url,creation_time,last_modified_time,fields}

Minimum API Key Access Level: Limited Access

Parameters

Field Description
id integer, optional Filter IDs by number filters.
Example: 754
type string, optional Filter by message type. Values include:
  • email - Email message
  • sms - SMS/Text message
Example: email
name string, optional Filter names by string filters.
Example: One Time Password
subject string, optional Filter subject by string filters.
Example: Reset Your Password
from_name string, optional Filter sender from name by string filters.
Example: Support Team
from_address string, optional Filter sender from address by string filters. These can be an email address for email types or a phone number for sms types.
Example: marketing@example.com
reply_to string, optional Filter sender reply-to address by string filters. These can be an email address for email types. sms types do not utilise this field.
Example: support@example.com
thumbnail_url string, optional Filter thumbnail url by string filters.
creation_time string, timestamp, optional Filter creation times by date and time filters.
Example: 2019-12-20T04:12:00Z
last_modified_time string, timestamp, optional Filter last modified times by date and time filters.
Example: 2019-12-20T04:12:00Z
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • type
  • name
  • subject
  • from_name
  • from_address
  • reply_to
  • thumbnail_url
  • creation_time
  • last_modified_time
  • folder — include the folder link in _links when the message has a non-empty folder_id (see Folders).
Example: id,from_address

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Get a Message

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 4847,
    "name": "Reset Password",
    "type": "email",
    "subject": "You requested to reset your password",
    "from_name": "Company Name",
    "from_address": "company@example.com",
    "reply_to": "company@example.com",
    "thumbnail_url": "",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "/v1/messages/4847"
        },
        "folder": {
            "href": "/v1/folders/12"
        },
        "content": {
            "href": "/v1/messages/4847/content"
        }
    }
}

Returns the message with the given ID.

Endpoint

GET /v1/messages/{id}{?expand,fields}

Minimum API Key Access Level: Limited Access

Parameters

Field Description
id integer, required Unique identifier for the instance.
Example: 294
expand string, optional Expand the response via one or more links. Multiple values can be grouped by commas. Values include:
  • content - Emit the message content instance linked to the message.
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • type
  • name
  • subject
  • from_name
  • from_address
  • reply_to
  • thumbnail_url
  • creation_time
  • last_modified_time
  • folder — include the folder link in _links when the message has a non-empty folder_id (see Folders).
Example: id,from_address

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Get Message Contents

Get one or more message contents with the following endpoints.

Get a Message's Content instance

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "message_id": 4847,
    "body_html": "<html><body>Email</body></html>",
    "body_text": "Email",
    "_links": {
        "self": {
            "href": "/v1/messages/4847/content"
        },
        "message": {
            "href": "/v1/messages/4847"
        }
    }
}

Returns the message content with the given message ID. For HTML-only (email_type html) messages, body_text may be null in the response even if your client previously sent a plain string when saving content; see the Message Content Object attribute notes.

Endpoint

GET /v1/messages/{message_id}/content{?expand,fields}

Minimum API Key Access Level: Limited Access

Parameters

Field Description
message_id integer, required Unique identifier for the linked message.
Example: 294
expand string, optional Expand the response via one or more links. Multiple values can be grouped by commas. Values include:
  • message - Emit the message instance linked to the message content.
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • message_id
  • body_html
  • body_text
Example: id,body_html

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Create a message

Create a new message. You must supply a non-empty name (after trimming leading and trailing whitespace). For email messages you must supply email_type and a non-empty subject, and initial body fields depend on email_type (see attributes below). For sms messages you must supply content_sms.

If the folder_id property is omitted from the request JSON (not merely null or empty), the API chooses the message folder with the lowest id (among folders with type message). If you include folder_id in the body, that value is used and no default is applied. The folders lookup uses the same access as listing folders (typically the list.view scope); if the token cannot list folders and you omit folder_id, resolution may fail.

Create an email message

{
    "folder_id": 12,
    "type": "email",
    "email_type": "html",
    "name": "Reset Password",
    "from_name": "Company Name",
    "from_address": "company@example.com",
    "reply_to": "company@example.com",
    "subject": "You requested to reset your password",
    "content_html": "<p>You requested a password reset.</p>",
    "content_text": "You requested a password reset."
}

Create an SMS message

{
    "type": "sms",
    "name": "Order confirmation SMS",
    "content_sms": "Thanks for your order. Reply STOP to opt out."
}

HTTP Response

201 Created
content-type: application/json; charset=UTF-8

{
    "id": 4847,
    "name": "Reset Password",
    "type": "email",
    "subject": "You requested to reset your password",
    "from_name": "Company Name",
    "from_address": "company@example.com",
    "reply_to": "company@example.com",
    "thumbnail_url": "",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-05T23:46:02Z",
    "_links": {
        "self": {
            "href": "/v1/messages/4847"
        },
        "folder": {
            "href": "/v1/folders/12"
        },
        "content": {
            "href": "/v1/messages/4847/content"
        }
    }
}

The response includes a Location header pointing to the new message when supported by the server.

Endpoint

POST /v1/messages

Minimum API Key Access Level: Limited Access

Attributes

The drag-and-drop email builder is not supported for create or update through this REST API. Use plain, plain-html, html, or raw_html here, or create drag-and-drop emails in the application UI.

Field Description
folder_id integer, optional Id of the message folder to create the message in. Omit this property entirely from the JSON body to let the API assign the message folder with the lowest id (see introduction above). When present, it must be a valid message folder id.
type string, required Message type: email or sms.
name string, required Display name of the message (email and SMS). Must not be empty or whitespace-only.
email_type string, required for email How email content is represented. Supported values: plain, plain-html, html, raw_html. Omit for sms.
from_name string, optional From name.
from_address string, optional From address (email or SMS sender, depending on type). For email, if omitted on create, the platform may apply the account’s saved default sender (updated when users save sender details for future sends in the UI).
reply_to string, optional Reply-to (email messages). If omitted on create, the platform may apply the account’s saved default reply-to.
subject string, required for email Subject line. Must not be empty or whitespace-only. Omit for sms.
content_html string, conditional Initial HTML body (content_html). Required on create when email_type is html or plain-html. For raw_html, you must supply at least one of content_html or content_html_raw (either field alone is sufficient).
content_text string, conditional Initial plain-text body (content_text). Required when email_type is plain or plain-html.
content_sms string, required for sms SMS body on create. Stored as platform content_text. Use this field instead of content_text when type is sms.
content_html_raw string, conditional Raw HTML body (content_html_raw). On create with email_type raw_html, may be sent instead of content_html to supply the full raw document. Also used for certain template / “save from raw” platform flows when both is_template and backend save_from_raw semantics apply.
is_template boolean, optional Whether the message is marked as reusable starter content in your account.
is_responsive boolean, optional Responsive HTML flag (email).

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
validation_error
Type: validation_errorStatus: 422		 Validation failed (for example missing type, name, email_type or subject for email, empty or whitespace-only name or subject, missing content_sms for SMS, missing required body fields for the given email_type (such as content_html / content_text, or raw_html with neither content_html nor content_html_raw), or no message folder exists when folder_id was omitted). See #message-errors in the error _links when present.
invalid_request
Type: invalid_requestStatus: 400		 The platform rejected the save (for example an unsupported email type such as drag-and-drop builder output). Check developer_message.
not_found
Type: not_foundStatus: 404		 Related resource not found (for example invalid folder).

Update a message

Update message metadata and optionally body fields in one request.

Update a message

{
    "name": "Reset Password (updated)",
    "subject": "Password reset request"
}

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 4847,
    "name": "Reset Password (updated)",
    "type": "email",
    "subject": "Password reset request",
    "from_name": "Company Name",
    "from_address": "company@example.com",
    "reply_to": "company@example.com",
    "thumbnail_url": "",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_modified_time": "2020-04-06T12:00:00Z",
    "_links": {
        "self": {
            "href": "/v1/messages/4847"
        },
        "folder": {
            "href": "/v1/folders/12"
        },
        "content": {
            "href": "/v1/messages/4847/content"
        }
    }
}

Endpoints

PATCH /v1/messages/{id}

POST /v1/messages/{id}

Minimum API Key Access Level: Limited Access

Parameters

Field Description
id integer, required Message to update.

Attributes

All fields are optional on update. You may send any subset of the create-message attributes that you need to change (for example name, subject, from_address, content_html, content_text, folder_id, email_type, or the boolean flags). Omit keys you do not want to modify.

When name or subject is present in the body, it must be non-empty after trimming leading and trailing whitespace (same rule as Create a message). Empty or whitespace-only values are rejected.

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
not_found
Type: not_foundStatus: 404		 The message does not exist, is not visible for this account, or is hidden (treated like not found for writes).
validation_error
Type: validation_errorStatus: 422		 Validation failed (for example empty or whitespace-only name or subject when those keys are supplied); see #message-errors when present.
invalid_request
Type: invalid_requestStatus: 400		 Platform rejected the save (for example unsupported operation for the message type).

Delete a message

Permanently deletes a message. This cannot be recovered via the REST API.

HTTP Response

204 No Content
content-type: application/json; charset=UTF-8

A successful response returns 204 No Content with no JSON body.

Endpoint

DELETE /v1/messages/{id}

Minimum API Key Access Level: Limited Access

Parameters

Field Description
id integer, required Message to delete.

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
not_found
Type: not_foundStatus: 404		 The message does not exist, is not visible, or is hidden.

Save message content

Create or replace the HTML and/or plain-text body for a message by posting to its content URL. The API forwards the payload to the platform message save (there is no separate “create content” resource in the backend). You must send at least one of body_html or body_text. An empty JSON object {} (no keys) is rejected with 400 invalid_request, not schema validation on individual fields.

Save message content

{
    "body_html": "<html><body><p>Updated email</p></body></html>",
    "body_text": "Updated email"
}

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "message_id": 4847,
    "body_html": "<html><body><p>Updated email</p></body></html>",
    "body_text": "Updated email",
    "_links": {
        "self": {
            "href": "/v1/messages/4847/content"
        },
        "message": {
            "href": "/v1/messages/4847"
        }
    }
}

Endpoint

POST /v1/messages/{message_id}/content

Minimum API Key Access Level: Limited Access

Parameters

Field Description
message_id integer, required Message whose content you are saving.

Attributes

Field Description
body_html string, optional HTML body (email messages). At least one of body_html or body_text is required.
body_text string, optional Plain-text body (email or SMS).

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
not_found
Type: not_foundStatus: 404		 The message does not exist, is not visible, or is hidden.
invalid_request
Type: invalid_requestStatus: 400		 The JSON body was empty, contained no recognised writable fields (for example {}), could not be decoded, or Content-Type was not application/json as required for JSON bodies.
validation_error
Type: validation_errorStatus: 422		 Request failed validation (for example neither body_html nor body_text supplied when the request is otherwise accepted for processing).

Update message content

Partially update message content with PATCH (same attribute rules as save message content). POST to the same URL is documented as save message content; both write paths accept the same JSON body.

Update message content

{
    "body_html": "<html><body><p>Patched HTML</p></body></html>"
}

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

(Response body matches the message content object after the save.)

Endpoint

PATCH /v1/messages/{message_id}/content

Minimum API Key Access Level: Limited Access

Parameters

Field Description
message_id integer, required Message whose content you are updating.

Attributes

Same as save message content: at least one of body_html or body_text.

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
not_found
Type: not_foundStatus: 404		 The message does not exist, is not visible, or is hidden.
invalid_request
Type: invalid_requestStatus: 400		 The JSON body was empty, contained no recognised writable fields (for example {}), could not be decoded, or Content-Type was not application/json as required for JSON bodies.
validation_error
Type: validation_errorStatus: 422		 Request failed validation (for example neither body_html nor body_text supplied when the request is otherwise accepted for processing).

Reports

A report contains statistics and analytics data for a sent message. Reports provide detailed information about message delivery, engagement, and performance metrics.

Reports are automatically created when messages are sent and can be accessed via the API to track message and batch performance.

The Report Object

Example Report

{
    "id": 1234,
    "message_id": 5678,
    "message_name": "Welcome Email",
    "message_type": "email",
    "creation_time": "2020-04-05T23:46:02Z",
    "creator_user_id": 42,
    "creator_user_name": "John Doe",
    "is_ab_test": false,
    "is_test": false,
    "report_url": "https://app.vision6.com.au/reports/1234",
    "last_sent_time": "2020-04-05T23:46:02Z",
    "sent": 1000,
    "bounced": 5,
    "unsubscribed": 2,
    "profile_update": 1,
    "sms_delivered": 0,
    "sms_acknowledged": 0,
    "sms_failed": 0,
    "sms_responses_count": 0,
    "total_recipients": 1000,
    "not_opened": 300,
    "opened": 700,
    "deactivated": 0,
    "complaints": 0,
    "unique_clicks": 150,
    "failed": 0,
    "clicks": {
        "https://example.com/link1": 50,
        "https://example.com/link2": 100
    },
    "domains": {
        "gmail.com": 400,
        "yahoo.com": 300,
        "outlook.com": 300
    },
    "_links": {
        "self": {
            "href": "/v1/reports/1234"
        },
        "message": {
            "href": "/v1/messages/5678"
        },
        "sent_contacts": {
            "href": "/v1/messages/5678/sent-contacts?report_id=1234"
        },
        "ab_test": null,
        "social": {
            "href": "/v1/reports/1234/social"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the report instance.
Example: 1234
message_id integer The ID of the message this report is for.
Example: 5678
message_name string, nullable The name of the message this report is for.
Example: Welcome Email
message_type enum, nullable The type of message. Values include email and sms.
Example: email
creation_time string, timestamp The time the report was created.
Example: 2020-04-05T23:46:02Z
creator_user_id integer The user ID of the user who created this report.
Example: 42
creator_user_name string, nullable The full name of the user who created this report.
Example: John Doe
is_ab_test boolean Whether this report is for an AB test.
Example: false
is_test boolean Whether this report is for a test send. Use this to distinguish test sends from live campaign reports.
Example: false
report_url string, nullable URL to the publicly available report page.
Example: https://app.vision6.com.au/reports/1234
last_sent_time string, timestamp Time the last message was sent.
Example: 2020-04-05T23:46:02Z
sent integer Total number of messages sent.
Example: 1000
bounced integer Total number of bounced messages.
Example: 5
unsubscribed integer Total number of unsubscribed messages.
Example: 2
profile_update integer Total number of profiles updated.
Example: 1
sms_delivered integer Total number of SMS messages successfully delivered (SMS only).
Example: 0
sms_acknowledged integer Total number of acknowledged SMS messages (SMS only).
Example: 0
sms_failed integer Total number of failed SMS messages (SMS only).
Example: 0
sms_responses_count integer Total number of SMS responses (SMS only).
Example: 0
total_recipients integer Total number of contacts sent to (Email only).
Example: 1000
not_opened integer Total number of messages not opened (Email only).
Example: 300
opened integer Total number of messages opened (Email only).
Example: 700
deactivated integer Total number of deactivated messages (Email only).
Example: 0
complaints integer Total number of complaints (Email only).
Example: 0
unique_clicks integer Total number of unique link clicks (Email only).
Example: 150
failed integer Total number of failed email sends (Email only).
Example: 150
clicks object Map of link click data, where keys are URLs and values are click counts (Email only).
Example: {"https://example.com/link1": 50, "https://example.com/link2": 100}
domains object Domain statistics showing the distribution of email addresses this message was sent to, where keys are domain names and values are counts (Email only).
Example: {"gmail.com": 400, "yahoo.com": 300, "outlook.com": 300}
_links object Self discoverable links to the current object, message, sent contacts, AB test (if applicable), and social statistics are provided.

Get Reports

Get one or more reports with the following endpoints.

Get all Reports

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "offset": 0,
    "limit": 100,
    "size": 1,
    "_links": {
        "self": {
            "href": "/v1/reports"
        }
    },
    "_embedded": {
        "reports": [
            {
                "id": 1234,
                "message_id": 5678,
                "message_name": "Welcome Email",
                "message_type": "email",
                "creation_time": "2020-04-05T23:46:02Z",
                "creator_user_id": 42,
                "creator_user_name": "John Doe",
                "is_ab_test": false,
                "is_test": false,
                "report_url": "https://app.vision6.com.au/reports/1234",
                "last_sent_time": "2020-04-05T23:46:02Z",
                "sent": 1000,
                "bounced": 5,
                "unsubscribed": 2,
                "profile_update": 1,
                "sms_delivered": 0,
                "sms_acknowledged": 0,
                "sms_failed": 0,
                "sms_responses_count": 0,
                "total_recipients": 1000,
                "not_opened": 300,
                "opened": 700,
                "deactivated": 0,
                "complaints": 0,
                "unique_clicks": 150,
                "failed": 0,
                "clicks": {
                    "https://example.com/link1": 50,
                    "https://example.com/link2": 100
                },
                "domains": {
                    "gmail.com": 400,
                    "yahoo.com": 300,
                    "outlook.com": 300
                },
                "_links": {
                    "self": {
                        "href": "/v1/reports/1234"
                    },
                    "message": {
                        "href": "/v1/messages/5678"
                    },
                    "sent_contacts": {
                        "href": "/v1/messages/5678/sent-contacts?report_id=1234"
                    },
                    "ab_test": null,
                    "social": {
                        "href": "/v1/reports/1234/social"
                    }
                }
            }
        ]
    }
}

Returns a collection of your reports, ordered by creation time (most recent first).

Endpoint

GET /v1/reports{?fields=id,message_id,message_name,message_type,creation_time,creator_user_id,creator_user_name,is_ab_test,is_test,last_sent_time,sent,bounced,unsubscribed,profile_update,sms_delivered,sms_acknowledged,sms_failed,sms_responses_count,total_recipients,not_opened,opened,deactivated,complaints,unique_clicks,failed}

Minimum API Key Access Level: Report Access

Parameters

To ensure the best performance with our complex data, we've optimised filtering for the most commonly used fields. For some of the more advanced data fields, filtering isn't available at this time. Those fields are: not_opened, deactivated, complaints, unique_clicks, profile_update, sms_delivered, sms_acknowledged, sms_failed, clicks, devices, domains, social, sent, bounced, unsubscribed.

Field Description
id integer, optional Filter IDs by number filters.
Example: 1234
message_id integer, optional Filter by message ID using number filters.
Example: 5678
message_name string, optional Filter message names by string filters.
Example: Welcome Email
message_type string, optional Filter by message type. Values include email and sms.
Example: email
creation_time string, timestamp, optional Filter creation times by date and time filters.
Example: 2020-04-05T23:46:02Z
last_sent_time string, timestamp, optional Filter last sent times by date and time filters.
Example: 2020-04-05T23:46:02Z
creator_user_id integer, optional Filter by creator user ID using number filters.
Example: 42
creator_user_name string, optional Filter creator user names by string filters.
Example: John Doe
is_ab_test boolean, optional Filter by whether the report is for an AB test.
Example: true
is_test boolean, optional Filter by whether the report is for a test send.
Example: false
sent integer, optional Filter by sent count using number filters.
Example: 1000
bounced integer, optional Filter by bounced count using number filters.
Example: 5
unsubscribed integer, optional Filter by unsubscribed count using number filters.
Example: 2
sms_responses_count integer, optional Filter by SMS responses count using number filters.
Example: 10
total_recipients integer, optional Filter by contact total using number filters.
Example: 1000
opened integer, optional Filter by opened count using number filters.
Example: 700
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • message_id
  • message_name
  • message_type
  • creation_time
  • creator_user_id
  • creator_user_name
  • is_ab_test
  • is_test
  • report_url
  • last_sent_time
  • sent
  • bounced
  • unsubscribed
  • profile_update
  • sms_delivered
  • sms_acknowledged
  • sms_failed
  • sms_responses_count
  • total_recipients
  • not_opened
  • opened
  • deactivated
  • complaints
  • unique_clicks
  • failed
  • clicks
  • domains
Example: id,message_id,sent,opened

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Get a Report

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 1234,
    "message_id": 5678,
    "message_name": "Welcome Email",
    "message_type": "email",
    "creation_time": "2020-04-05T23:46:02Z",
    "creator_user_id": 42,
    "creator_user_name": "John Doe",
    "is_ab_test": false,
    "is_test": false,
    "report_url": "https://app.vision6.com.au/reports/1234",
    "last_sent_time": "2020-04-05T23:46:02Z",
    "sent": 1000,
    "bounced": 5,
    "unsubscribed": 2,
    "profile_update": 1,
    "sms_delivered": 0,
    "sms_acknowledged": 0,
    "sms_failed": 0,
    "sms_responses_count": 0,
    "total_recipients": 1000,
    "not_opened": 300,
    "opened": 700,
    "deactivated": 0,
    "complaints": 0,
    "unique_clicks": 150,
    "failed": 0,
    "clicks": {
        "https://example.com/link1": 50,
        "https://example.com/link2": 100
    },
    "domains": {
        "gmail.com": 400,
        "yahoo.com": 300,
        "outlook.com": 300
    },
    "_links": {
        "self": {
            "href": "/v1/reports/1234"
        },
        "message": {
            "href": "/v1/messages/5678"
        },
        "sent_contacts": {
            "href": "/v1/messages/5678/sent-contacts?report_id=1234"
        },
        "ab_test": null,
        "social": {
            "href": "/v1/reports/1234/social"
        }
    }
}

Returns the report with the given ID.

Endpoint

GET /v1/reports/{id}{?expand,fields}

Minimum API Key Access Level: Report Access

Parameters

Field Description
id integer, required Unique identifier for the report instance.
Example: 1234
expand string, optional Expand the response via one or more links. Multiple values can be grouped by commas. Values include:
  • ab_test - Emit AB test result data for the report (if applicable).
  • social - Emit social interaction statistics for the report.
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • message_id
  • message_name
  • message_type
  • creation_time
  • creator_user_id
  • creator_user_name
  • is_ab_test
  • is_test
  • report_url
  • last_sent_time
  • sent
  • bounced
  • unsubscribed
  • profile_update
  • sms_delivered
  • sms_acknowledged
  • sms_failed
  • sms_responses_count
  • total_recipients
  • not_opened
  • opened
  • deactivated
  • complaints
  • unique_clicks
  • failed
  • clicks
  • domains
Example: id,message_id,sent,opened

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

The AB Test Object

Example AB Test

{
    "report_id": 1234,
    "variant_stats": {
        "1": {
            "sent": 500,
            "opened": 350,
            "unique_clicks": 80
        },
        "2": {
            "sent": 500,
            "opened": 380,
            "unique_clicks": 95
        }
    },
    "total_variants": 2,
    "winner_variant": 2,
    "_links": {
        "self": {
            "href": "/v1/reports/1234/ab-test"
        }
    }
}

Attributes

Field Description
report_id integer Unique identifier for the report this AB test data belongs to.
Example: 1234
variant_stats object Statistics for each AB test variant. Keys are variant IDs, values are objects containing statistics such as sent, opened, unique_clicks, etc.
Example: {"1": {"sent": 500, "opened": 350}, "2": {"sent": 500, "opened": 380}}
total_variants integer Total number of variants in the test.
Example: 2
winner_variant integer, nullable The winning variant ID, if a winner has been determined.
Example: 2
_links object Self discoverable links to the current object are provided.

Get AB Test Data

Get AB test statistics for a report.

Get AB Test Data for a Report

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "report_id": 1234,
    "variant_stats": {
        "1": {
            "sent": 500,
            "opened": 350,
            "unique_clicks": 80
        },
        "2": {
            "sent": 500,
            "opened": 380,
            "unique_clicks": 95
        }
    },
    "total_variants": 2,
    "winner_variant": 2,
    "_links": {
        "self": {
            "href": "/v1/reports/1234/ab-test"
        }
    }
}

Returns AB test statistics for the report with the given ID. This endpoint is only available for reports where is_ab_test is true.

Endpoint

GET /v1/reports/{report_id}/ab-test{?fields}

Minimum API Key Access Level: Report Access

Parameters

Field Description
report_id integer, required Unique identifier for the report instance.
Example: 1234
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • report_id
  • variant_stats
  • total_variants
  • winner_variant
Example: report_id,variant_stats,winner_variant

Errors

Please view our Errors documentation for a list of common error responses. This endpoint returns a 404 Not Found error if the report does not exist or is not an AB test.

The Social Object

Example Social Statistics

{
    "report_id": 1234,
    "facebook": {
        "click_count": 25,
        "share_count": 10,
        "link_id": 567
    },
    "twitter": {
        "click_count": 15,
        "share_count": 5,
        "link_id": 568
    },
    "linkedin": {
        "click_count": 8,
        "share_count": 2,
        "link_id": 569
    },
    "_links": {
        "self": {
            "href": "/v1/reports/1234/social"
        }
    }
}

Attributes

Field Description
report_id integer Unique identifier for the report this social data belongs to.
Example: 1234
facebook object Facebook interaction statistics. Contains click_count, share_count, and link_id (nullable).
Example: {"click_count": 25, "share_count": 10, "link_id": 567}
twitter object Twitter interaction statistics. Contains click_count, share_count, and link_id (nullable).
Example: {"click_count": 15, "share_count": 5, "link_id": 568}
linkedin object LinkedIn interaction statistics. Contains click_count, share_count, and link_id (nullable).
Example: {"click_count": 8, "share_count": 2, "link_id": 569}
_links object Self discoverable links to the current object are provided.

Get Social Statistics

Get social interaction statistics for a report.

Get Social Statistics for a Report

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "report_id": 1234,
    "facebook": {
        "click_count": 25,
        "share_count": 10,
        "link_id": 567
    },
    "twitter": {
        "click_count": 15,
        "share_count": 5,
        "link_id": 568
    },
    "linkedin": {
        "click_count": 8,
        "share_count": 2,
        "link_id": 569
    },
    "_links": {
        "self": {
            "href": "/v1/reports/1234/social"
        }
    }
}

Returns social interaction statistics for the report with the given ID. This includes click and share counts for connected social networks (Facebook, Twitter, LinkedIn).

Endpoint

GET /v1/reports/{report_id}/social{?fields}

Minimum API Key Access Level: Report Access

Parameters

Field Description
report_id integer, required Unique identifier for the report instance.
Example: 1234
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • report_id
  • facebook
  • twitter
  • linkedin
Example: report_id,facebook,twitter

Errors

Please view our Errors documentation for a list of common error responses. This endpoint returns a 404 Not Found error if the report does not exist.

Sent Contacts

Get contacts that were sent a particular message with the following endpoint. Returns basic information about contacts that were sent a message, including send time, open time, and open type.

The Sent Contacts Object

Example Sent Contacts Object

{
    "contact_id": 1,
    "list_id": 6,
    "send_time": "2025-09-11T04:22:14Z",
    "report_id": 2,
    "first_open_time": "2025-09-11T14:22:38",
    "last_open_time": "2025-09-11T14:22:38",
    "open_type": "html",
    "_links": {
        "list": {
            "href": "/v1/lists/6"
        },
        "contact": {
            "href": "/v1/lists/6/contacts/1"
        }
    }
}

Attributes

Field Description
contact_id integer Identifier for the contact in the list.
Example: 1
list_id integer Identifier for the list the message was sent to.
Example: 6
send_time string, timestamp The date and time the message was sent to the contact.
Example: 2025-09-11T04:22:14Z
report_id integer Identifier for the report of the send.
Example: 2
first_open_time string, timestamp The date and time the message was first opened by the contact.
Example: 2025-09-11T14:22:38
last_open_time string, timestamp The date and time the message was last opened by the contact.
Example: 2025-09-11T14:22:38
open_type string How the contact first opened the message.
Example: html
_links object Links to the List endpoint and the Contact endpoint.

Get Sent Contacts

Get a collection of sent contacts using the following endpoint.

Get all Sent Contacts

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "offset": 0,
    "limit": 100,
    "size": 1,
    "_links": {
        "self": {
            "href": "/v1/messages/115/sent-contacts"
        }
    },
    "_embedded": {
        "sent-contacts": [
            {
                "contact_id": 3,
                "list_id": 6,
                "send_time": "2025-09-11T04:22:14Z",
                "report_id": 2,
                "first_open_time": null,
                "last_open_time": null,
                "open_type": "not_opened",
                "_links": {
                    "list": {
                        "href": "/v1/lists/6"
                    },
                    "contact": {
                        "href": "/v1/lists/6/contacts/3"
                    }
                }
            }
        ]
    }
}

Returns a collection of the sent contacts for the specified message.

Endpoint

GET /v1/messages/{message_id}/sent-contacts{?contact_id,list_id,send_time,report_id,first_open_time,last_open_time,open_type}

Parameters

Field Description
contact_id integer, optional Filter IDs by number filters.
Example: 1
list_id integer, optional Filter IDs by number filters.
Example: 6
send_time string, timestamp, optional Filter last modified times by date and time filters.
Example: 2025-09-11T04:22:14Z
report_id integer, optional Filter IDs by number filters.
Example: 2
first_open_time string, timestamp, optional Filter last modified times by date and time filters.
Example: 2025-09-11T14:22:38
last_open_time string, timestamp, optional Filter last modified times by date and time filters.
Example: 2025-09-11T14:22:38
open_type string, optional Filter by open type. Values include:
  • not_opened - Not Opened
  • html - HTML email open
  • text - Text email open
  • sms - sms message open

Example: html

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Transactional Sends

Transactional Email

{
    "type": "email",
    "list_id": 345,
    "group_name": "Happy Birthday",
    "message_id": 427,
    "recipients": [
        {
            "email": "john@example.com",
            "first_name": "John",
            "url_key": "dyr61Gv6p3"
        }
    ]
}

Transactional sends let you send messages asynchronously. This is more flexible than a batch send. A send can be customised with dynamic content and unique recipient fields.

Benefits of transactional messages:

Both email and sms transactional types are supported.

JSON Examples

Copy and paste these JSON examples to start sending quickly.

All requests are sent to POST /v1/transactional-sends and will return 202 Accepted header codes when they are successfully added.

Send an email message to a contact

Transactional Email

{
    "type": "email",
    "list_id": 345,
    "group_name": "Happy Birthday",
    "message_id": 427,
    "subject": "It's been another year John!",
    "recipients": [
        {
            "contact_id": 42187,
            "first_name": "John",
            "url_key": "oiserjoifdewh"
        }
    ]
}

You will need the following:

Email message with custom content

Transactional Email

{
    "type": "email",
    "list_id": 345,
    "group_name": "Reset Password",
    "from_name": "Company Name",
    "from_address": "support@example.com",
    "subject": "How to Reset your Password",
    "body_html": "<html><body>Hi %%name%%<br>Click <a src='%%reset_link%%'>here</a> to reset your password</body></html>",
    "body_text": "Hi %%name%%, visit %%reset_link%% to reset your password",
    "recipients": [
        {
            "email": "sam@example.com",
            "name": "Sam",
            "reset_link": "https://example.com/reset-password?key=KJHuIyhUIOh"
        }
    ]
}

You will need the following:

Send an SMS message to a contact

Transactional SMS

{
    "type": "sms",
    "list_id": 6148,
    "group_name": "SMS Promotional",
    "message_id": 2148,
    "from_address": "61400000000",
    "recipients": [
        {
            "contact_id": 254,
            "promotion_name": "End of Year Sale"
        }
    ]
}

You will need the following:

SMS Message without a list

Transactional SMS

{
    "type": "sms",
    "group_name": "Order Confirmations",
    "from_address": "61400000000",
    "body_text": "Congratulations! Your order %%order_number%% has been received and our warehouse staff will prepare it shortly.",
    "unsubscribe_type": "word",
    "recipients": [
        {
            "mobile": "61400000000",
            "order_number": "ORD-45798789"
        }
    ]
}

You will need the following:

Send to multiple contacts

Transactional SMS

{
    "type": "sms",
    "list_id": 6148,
    "group_name": "End of Month Reminders",
    "from_address": "61400000000",
    "body_text": "Hello! This is your end of month reminder to renew your license.",
    "recipients": [
        {
            "contact_id": 517
        },
        {
            "contact_id": 58
        },
        {
            "contact_id": 9314
        }
    ]
}

You will need the following:

Recipients

Recipients must have at least one of these:

If contact_id is present, this will always be used to validate a recipient. Otherwise, email or mobile will be used, based on the message type.

When a list_id is provided, recipients are treated as contacts on the list identified by the list_id. Recipients with fields specified that don't match fields in the list will be added.

Email Recipients

Email Recipient Examples

{
    "contact_id": 2147
}

{
    "email": "bob@example.com"
}

{
    "email": "sam@example.com",
    "location": "Brisbane, Australia",
    "tickets": 3
}

Transactional email always requires a list_id.

An email recipient may be identified via:

SMS Recipients

SMS Recipient Examples

{
    "contact_id": 2147
}

{
    "mobile": "61400000000"
}

{
    "mobile": "61400000000",
    "ticket_url": "https://www.example.com/tickets/126459"
}

A list_id is not required for transactional SMS. When specified, recipients are treated as contacts on the list identified by the list_id.

SMS recipients may be identified by:

Valid Mobile Phone Numbers

Our API only accepts mobile numbers in international format without the leading + sign and without spaces.

For Australian numbers this means an 11-digit number consisting of country code (61) followed by the mobile number without the leading zero. Example: 61400000009.

These formats apply to any mobile fields, which include from_address, mobile and a list's Mobile field.

Transactional Groups

We group results for transactional sends into transactional groups. Transactional groups can be discovered via the transactional groups endpoints.

A transactional group can be linked by supplying a group_id or group_name.

Wildcards and Conditional Wildcards

Example Recipient Wildcards

{
    "contact_id": 457,
    "total_orders": 7,
    "token": "ORD-VqSPCzlxb7"
}

New wildcard and conditional wildcard values can be provided within each recipient. These values will override existing contact field values and are not saved after each send is complete.

These values will apply to the body_html, body_text, subject and the same fields within messages.

The following fields are reserved and may not be used as wildcards:

For more information on using wildcards and conditional wildcards, visit the wildcards introduction.

Email From Address Requirements

For email sends, the domain and address used in from_address (and reply_to / bcc_address where provided) must be configured in your account before you can send.

If an unverified sender address is used, the API returns a 422 validation error:

Email Attachments

An attachment shared by all recipients

{
    "type": "email",
    "list_id": 345,
    "group_name": "Happy Birthday",
    "message_id": 427,
    "recipients": [
        {
            "email": "john@example.com"
        }
    ],
    "attachments": [
        {
            "type": "application/pdf",
            "name": "terms_and_conditions.pdf",
            "content": "JVBERi0xLjQKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291cmNlcyAyIDAgUgovQ29udGVudHMgNCAwIFI+PgplbmRvYmoKNCAwIG9iago8PC9GaWx0ZXIgL0ZsYXRlRGVjb2RlIC9MZW5ndGggNzE+PgpzdHJlYW0KeJwzUvDiMtAzNVco5ypUMFDwUjBUKAfSWUDsDsTpQFFDPQMgUABBGBOFSs7l0g8J8DFUcMlXCOQK5AIrUkAmi9K5ADZmFKUKZW5kc3RyZWFtCmVuZG9iagoxIDAgb2JqCjw8L1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUiBdCi9Db3VudCAxCi9NZWRpYUJveCBbMCAwIDU5NS4yOCA4NDEuODldCj4+CmVuZG9iago1IDAgb2JqCjw8L0ZpbHRlciAvRmxhdGVEZWNvZGUgL1R5cGUgL1hPYmplY3QKL1N1YnR5cGUgL0Zvcm0KL0Zvcm1UeXBlIDEKL0JCb3ggWzAuMDAgMC4wMCA1OTUuMjggODQxLjg5XQovUmVzb3VyY2VzIAo8PC9Qcm9jU2V0IFsvUERGIC9UZXh0IC9JbWFnZUIgL0ltYWdlQyAvSW1hZ2VJIF0KL0ZvbnQgPDw+Pi9YT2JqZWN0IDw8L0kxIDYgMCBSCj4+Pj4vR3JvdXAgPDwvVHlwZS9Hcm91cC9TL1RyYW5zcGFyZW5jeT4+Ci9MZW5ndGggNTggPj4Kc3RyZWFtCnicM1Lw4jLQMzVXKOcqVDA0MNAzMFAAQSjTyMRcz8xEwdjcQM/SRCE5V0Hf01DBJV8hkEsBAEjbC3IKZW5kc3RyZWFtCmVuZG9iago2IDAgb2JqCjw8L1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdlIC9XaWR0aCAxMDAgL0hlaWdodCAxMDAgL0NvbG9yU3BhY2UgL0RldmljZUdyYXkgL0JpdHNQZXJDb21wb25lbnQgMSAvRmlsdGVyIC9GbGF0ZURlY29kZSAvRGVjb2RlUGFybXMgPDwvUHJlZGljdG9yIDE1IC9Db2xvcnMgMSAvQml0c1BlckNvbXBvbmVudCAxIC9Db2x1bW5zIDEwMCA+Pi9MZW5ndGggMjMzID4+c3RyZWFtCjjLzdSxDcMgEEDRsyjo4gWQWIOOlewFQCwQr0THGkheADoXKJdzZMVp7KOMK78K8+9kwJ+nwB+rAEzQfISBU8XmN10TvXCKypkVE8wd8jEPvaITOoTNmezPL7sU3W9Oaj5ve6m9lQV/FrxUMcrZb4k7Ieol5YeBkVON7WFFiGvl9AIREMOWB04VwUlcvl2uVYygcYHVCyu5Z3jKo+CN6iYW1MXkmVXMkxEF1Mjp058y8KLZOklz0JXTvi+wBuxQpGVRABo7NNG+JAwdcgZf9mh2J2yTbOOmWO17jXTIWjn901+qV285T7kXCmVuZHN0cmVhbQplbmRvYmoKMiAwIG9iago8PAovUHJvY1NldCBbL1BERiAvVGV4dCAvSW1hZ2VCIC9JbWFnZUMgL0ltYWdlSV0KL0ZvbnQgPDwKPj4KL1hPYmplY3QgPDwKL1RQTDEgNSAwIFIKPj4KPj4KZW5kb2JqCjcgMCBvYmoKPDwKL0NyZWF0b3IgKE9ubGluZTJQREYuY29tKQovUHJvZHVjZXIgKE9ubGluZTJQREYuY29tKQovQ3JlYXRpb25EYXRlIChEOjIwMjAwNzE2MDE1NDQzKQo+PgplbmRvYmoKOCAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMSAwIFIKL09wZW5BY3Rpb24gWzMgMCBSIC9GaXRIIG51bGxdCi9QYWdlTGF5b3V0IC9PbmVDb2x1bW4KPj4KZW5kb2JqCnhyZWYKMCA5CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDIyNyAwMDAwMCBuIAowMDAwMDAxMTI1IDAwMDAwIG4gCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA4NyAwMDAwMCBuIAowMDAwMDAwMzE0IDAwMDAwIG4gCjAwMDAwMDA2NTAgMDAwMDAgbiAKMDAwMDAwMTIzMSAwMDAwMCBuIAowMDAwMDAxMzM4IDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgOQovUm9vdCA4IDAgUgovSW5mbyA3IDAgUgovSUQgWzw2OUExNTMwNEUyMjdDMTU2RTQwNUMyQ0M0RUM4NjczMD48NjlBMTUzMDRFMjI3QzE1NkU0MDVDMkNDNEVDODY3MzA+XQo+PgpzdGFydHhyZWYKMTQ0MQolJUVPRgo="
        }
    ]
}

Only john@example.com will receive these 2 attachments

{
    "type": "email",
    "list_id": 345,
    "group_name": "Happy Birthday",
    "message_id": 427,
    "recipients": [
        {
            "email": "john@example.com",
            "attachments": [
                {
                    "type": "application/pdf",
                    "name": "event_tickets.pdf",
                    "content": "JVBERi0xLjQKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291cmNlcyAyIDAgUgovQ29udGVudHMgNCAwIFI+PgplbmRvYmoKNCAwIG9iago8PC9GaWx0ZXIgL0ZsYXRlRGVjb2RlIC9MZW5ndGggNzE+PgpzdHJlYW0KeJwzUvDiMtAzNVco5ypUMFDwUjBUKAfSWUDsDsTpQFFDPQMgUABBGBOFSs7l0g8J8DFUcMlXCOQK5AIrUkAmi9K5ADZmFKUKZW5kc3RyZWFtCmVuZG9iagoxIDAgb2JqCjw8L1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUiBdCi9Db3VudCAxCi9NZWRpYUJveCBbMCAwIDU5NS4yOCA4NDEuODldCj4+CmVuZG9iago1IDAgb2JqCjw8L0ZpbHRlciAvRmxhdGVEZWNvZGUgL1R5cGUgL1hPYmplY3QKL1N1YnR5cGUgL0Zvcm0KL0Zvcm1UeXBlIDEKL0JCb3ggWzAuMDAgMC4wMCA1OTUuMjggODQxLjg5XQovUmVzb3VyY2VzIAo8PC9Qcm9jU2V0IFsvUERGIC9UZXh0IC9JbWFnZUIgL0ltYWdlQyAvSW1hZ2VJIF0KL0ZvbnQgPDw+Pi9YT2JqZWN0IDw8L0kxIDYgMCBSCj4+Pj4vR3JvdXAgPDwvVHlwZS9Hcm91cC9TL1RyYW5zcGFyZW5jeT4+Ci9MZW5ndGggNTggPj4Kc3RyZWFtCnicM1Lw4jLQMzVXKOcqVDA0MNAzMFAAQSjTyMRcz8xEwdjcQM/SRCE5V0Hf01DBJV8hkEsBAEjbC3IKZW5kc3RyZWFtCmVuZG9iago2IDAgb2JqCjw8L1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdlIC9XaWR0aCAxMDAgL0hlaWdodCAxMDAgL0NvbG9yU3BhY2UgL0RldmljZUdyYXkgL0JpdHNQZXJDb21wb25lbnQgMSAvRmlsdGVyIC9GbGF0ZURlY29kZSAvRGVjb2RlUGFybXMgPDwvUHJlZGljdG9yIDE1IC9Db2xvcnMgMSAvQml0c1BlckNvbXBvbmVudCAxIC9Db2x1bW5zIDEwMCA+Pi9MZW5ndGggMjMzID4+c3RyZWFtCjjLzdSxDcMgEEDRsyjo4gWQWIOOlewFQCwQr0THGkheADoXKJdzZMVp7KOMK78K8+9kwJ+nwB+rAEzQfISBU8XmN10TvXCKypkVE8wd8jEPvaITOoTNmezPL7sU3W9Oaj5ve6m9lQV/FrxUMcrZb4k7Ieol5YeBkVON7WFFiGvl9AIREMOWB04VwUlcvl2uVYygcYHVCyu5Z3jKo+CN6iYW1MXkmVXMkxEF1Mjp058y8KLZOklz0JXTvi+wBuxQpGVRABo7NNG+JAwdcgZf9mh2J2yTbOOmWO17jXTIWjn901+qV285T7kXCmVuZHN0cmVhbQplbmRvYmoKMiAwIG9iago8PAovUHJvY1NldCBbL1BERiAvVGV4dCAvSW1hZ2VCIC9JbWFnZUMgL0ltYWdlSV0KL0ZvbnQgPDwKPj4KL1hPYmplY3QgPDwKL1RQTDEgNSAwIFIKPj4KPj4KZW5kb2JqCjcgMCBvYmoKPDwKL0NyZWF0b3IgKE9ubGluZTJQREYuY29tKQovUHJvZHVjZXIgKE9ubGluZTJQREYuY29tKQovQ3JlYXRpb25EYXRlIChEOjIwMjAwNzE2MDE1NDQzKQo+PgplbmRvYmoKOCAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMSAwIFIKL09wZW5BY3Rpb24gWzMgMCBSIC9GaXRIIG51bGxdCi9QYWdlTGF5b3V0IC9PbmVDb2x1bW4KPj4KZW5kb2JqCnhyZWYKMCA5CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDIyNyAwMDAwMCBuIAowMDAwMDAxMTI1IDAwMDAwIG4gCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA4NyAwMDAwMCBuIAowMDAwMDAwMzE0IDAwMDAwIG4gCjAwMDAwMDA2NTAgMDAwMDAgbiAKMDAwMDAwMTIzMSAwMDAwMCBuIAowMDAwMDAxMzM4IDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgOQovUm9vdCA4IDAgUgovSW5mbyA3IDAgUgovSUQgWzw2OUExNTMwNEUyMjdDMTU2RTQwNUMyQ0M0RUM4NjczMD48NjlBMTUzMDRFMjI3QzE1NkU0MDVDMkNDNEVDODY3MzA+XQo+PgpzdGFydHhyZWYKMTQ0MQolJUVPRgo="
                },
                {
                    "type": "image/png",
                    "name": "event_qr_code.png",
                    "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
                }
            ]
        }
    ]
}

Attachments can be added for all and/or specific recipients via the attachments field.

Inline Attachments

Example Inline Attachment

{
    "type": "email",
    "list_id": 217,
    "group_name": "Register Today",
    "from_name": "Company Name",
    "from_address": "support@example.com",
    "subject": "Register Today",
    "body_html": "<html><body>Hi %%name%%,<br/>Register with your QR code:<br/><img src='%%attachment:qr-code.png%%' alt=''/></body></html>",
    "recipients": [
        {
            "email": "ben@example.com",
            "name": "Ben",
            "attachments": [
                {
                    "type": "image/png",
                    "name": "qr-code.png",
                    "content": "iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAYAAABw4pVUAAAEeElEQVR4Xu2c0XIqMQxDu///0XRaliGFZvcodkxodV+vSRzJkp0wdLtcLpcP/1sGgc2ELMPFdyImZC0+TMhifJgQE7IaAovl4x5iQhZDYLF0rBATshgCi6VjhZiQxRBYLB1ZIdu2pR+hfU5T1+89xbXrkOc6dV8CAtn3cR0TsiNiQprSsELuYIQUMiLJ29aqpbTS7lUzyae3bySfXm4kn1TLGtnQhBx3Hyvklx7yqkIb+j6ESL5XA71eoU5KJAcVVLJm1rmONJKmEDKlmJDzYdmEnFjWjEJ7W4WokxUBr12TKJasSdY518Y1YmmFmBBA46uaH7l7kGq2QsCNnExEBGx1HWI16r7RC+bbW1av4ntiJwpXn3IIscB8/kYPMSHN8zuxCLVSybsQqfIsomhlZzwJpU5ZMxInwBN7IYUT9X4TsiNgQgq/MSTNMqIiQqaqfNUqH9cPTVmRZCP3gdlEzTgXXdOE7EiR+wYF9RZHeldYIWpSajy5kZMnlah1qHlnxcsKydqYjMMEVFLZI5U6+5zd86/2CyorRCwfApgao35jSC6PRIFkOFCVEr3PyJalgq1OUyrYKgDqmGxCGgQI2CSGkKyuoyqQEisrhC58iyMHnRHTy5PYFBkUyPoqVl/xJmRHLevWLrbkJ85MyLsTQppi5P5ALIVcDEnFR2Iik+GRlckKMSFXOE1I50+yzBjDZ4/qqQohdkGmC9UuyJpkFFXtlOSZOXHJlmVCeGmMTFwm5Bd81T75UoWQS5yqItIgidUQyyJ7jVS2chFO7SEm5NiyVHweV5MtS92QPEOQqrVCOoUQGTNngEoIJ22YFEUkhuTwFRNSCJnXsxpeVqNV8yGOQGJMCEVgj4tU/5KEVKpFxPpDVVfkMhix5VTLMiHPZTIyPqf1EBOyACHEd0kTjXiw+ll1SiT2pX5lUH4xJKNo1iFMCPh9iAm5aqC8h0TkrPYcsheZcEixqDZL9qWTYaipE5AqYwgwJqT5pk9tqKqK/iUhVHqjcWoFq8NBZAhQ1T6CgWxZI5sonzEhI6OAgrAYa0JEQlTACB/qBVO1qTYH8q41Y32Cw7S3LLr5Lc6E3BGTe4gVclxu6tDwuFqIENHtfuxNEifkE3sh43YPZpInsUTqGibkBCkT0gBkhQBdkSlFfQuK2E7kNg+O+yMkYtF0rzTLmlHN5GZsQjrP7yaEauBkSlN/p15pWVmPhcRq1Obdm6xIzkeULG1Z5HCqMrPGWxMi/mCHkJl1f4jcc6ZdDNVKJRZB7JHYUUQV5FxkqqQdZjnLIlVLyCQAkHVMSOdiSO4qhARCOOkPZK8R9aYphCRIwCAVSQ4a8XXy2aw8p/UQE/KMACkcE9KZ1ohNRV4OaMGGLItuchYX6Q/qJEbsKGsqK1fIGdD0/03IHSkrZMeCVLM6JpM1wz2EVr3jxhCQFTK2jT9FETAhFKmiOBNSBDTdxoRQpIriTEgR0HQbE0KRKoozIUVA021MCEWqKM6EFAFNtzEhFKmiOBNSBDTdxoRQpIriPgGzSEo+SG5vWQAAAABJRU5ErkJggg=="
                }
            ]
        }
    ]
}

Attachments can be added to the body HTML via inline Content-ID identifiers. To add an inline attachment you can use a wildcard in the format of %%attachment:[attachment.name]%%. The output will be similar to cid:content_[generated ID].

Generally inline attachments are used via Content-ID identifiers for images. e.g, <img src="%%attachment:[attachment.name]%%" alt="" />.

We recommend that only the following types are used as image attachments:

In messages, it is recommended that you give a unique name to each inline attachment.

Accepted File Types

The following file types are accepted as attachments:

SMS Sender IDs

All sms sends must use a from_address that is already available as an SMS sender on your account. Valid sender types are:

A how-to guide for applying for a new Sender ID has been provided in our support article.

Examples include:

If the Sender ID is not available on your account, the API returns invalid_from_address.

Dedicated (virtual) numbers that are assigned to a list must be used with that same list_id. If the number is assigned to a different list, the API returns from_address_invalid_list.

SMS Unsubscribe Methods

Stop/Unsubscribe Word Example

We're running a market sale on this weekend at 10:30 and you're invited!
Reply STOP to opt out

Link Example

We're running a market sale on this weekend at 10:30 and you're invited!
To opt out, go to https://short.example.com/xxxxxxxxxxx

Recipients should have the ability to opt out of receiving further SMS messages. Our system provides multiple mechanisms to assist with unsubscribes via the unsubscribe_type parameter. Possible values for unsubscribe_type are:

Request Limits

All transactional sends are sent asynchronously. What does this mean for requests?

Each transactional send request has the following limits and validation criteria:

SMS Content Limits

When sending transactional SMS, it is important to consider that may not be sent if the body_text is too long. Our recommendation is to keep any SMS message sent to ~500 characters to reduce any risks of SMS message carriers rejecting the content from being sent.

Automations

If contacts are created or edited then automation triggers will be fired for each contact.

Recipient and Webhook Correlation

Example Response Body (2 recipients were provided in the request)

{
    "_embedded": {
        "recipients": [
            {
                "uuid": "j4RwlxSNekLlaFF0vi2tPg"
            },
            {
                "uuid": "lCeoxEX9ZTqfzkiPxzws4Q"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "/v1/transactional-sends"
        }
    }
}

To facilitate correlation and tracking of transactional sends, a uuid is returned for each recipient of a send.

The Transactional Send Object

Transactional email example

{
    "type": "email",
    "list_id": 345,
    "group_name": "Happy Birthday",
    "message_id": 427,
    "recipients": [
        {
            "email": "john@example.com",
            "first_name": "John",
            "url_key": "oiserjoifdewh"
        }
    ]
}

HTTP Response

202 Accepted
content-type: application/json; charset=UTF-8

{
    "_embedded": {
        "recipients": [
            {
                "uuid": "j4RwlxSNekLlaFF0vi2tPg"
            },
            {
                "uuid": "lCeoxEX9ZTqfzkiPxzws4Q"
            },
        ]
    },
    "_links": {
        "self": {
            "href": "/v1/transactional-sends"
        }
    }
}

Send a message (via a message_id or raw HTML/text) to a list of recipients. The send report is stored against the transactional group transactional groups.

Endpoint

POST /v1/transactional-sends

Minimum API Key Access Level: Standard Access

Attributes

Field Description
list_id integer Unique identifier for the linked list. Always required for Email.
Example: 89
group_id integer, optional Unique identifier for the linked group.
Example: 248
group_name string, optional Unique name for the linked group.
Example: Password Reset Report
message_id integer, optional Unique identifier for the linked message. Providing a message_id will override any type provided.
Example: 754
type enum, required The message send type. Values include:
  • email
  • sms
Example: email
unsubscribe_type enum, required The type of unsubscribing allowed on this send (see Unsubscribing).
Applies to SMS only. Values include:
  • none
  • word
  • link
Example: word
body_text string, optional The text body of the email and sms message types.
Example: Hi %%name%%, visit %%reset_link%% to reset your password
body_html string, optional The HTML body of the email message type. Applies to email only.
Example: Hi %%name%%<br>Click <a src="%%reset_link%%">here</a> to reset your password
subject string, optional The message subject line. Applies to email only.
Example: Password Reset
from_name string, optional The sender from name. Applies to email only.
Example: Vision6 Support
from_address string, optional The sender from address.
Example: support@example.com
reply_to string, optional The sender reply-to address for email message types. Applies to email only.
Example: support@example.com
bcc_address string, optional The sender bind carbon copy (bcc) address for email message types. Applies to email only.
Example: support@example.com
include_unsubscribed boolean, optional By default all unsubscribed email addresses for the recipients supplied will not be sent to. To ignore this behaviour set this to true.
Example: false
recipients array, required Collection of recipients. A maximum of 100 recipients can be sent per request.
recipients.*.contact_id integer, optional Unique identifier for the contact.
Example: 457
recipients.*.email string, optional The email of the contact. Applies to email only.
Example: frank@example.com
recipients.*.mobile string, optional The mobile phone number of the contact. Applies to SMS only. See Valid Phone Numbers
Example: 0400000000
recipients.*.{wildcard_key} string, optional Values corresponding to wildcard keys (see Wildcards).
If the value contains HTML and recipient_data_html_encoded is false, prefix the wildcard_key with a # to prevent it being encoded when included in body_html. Applies to email only.
recipient_data_html_encoded boolean, optional By default wildcard data is expected to be appropriately encoded. Set this to false if it is plain text and should be encoded when included in HTML. Applies to email only.
Example: false
attachments array, optional Collection of attachments. Applies to email only.
attachments.*.type string, required The mimetype of the attachment.
Example: text/calendar
attachments.*.name string, required The name of the attachment.
Example: this_meeting_could_have_been_an_email.ical
attachments.*.content string, required Base64 encoded attachment data.
Example: QkVHSU46VkNBTEVOREFSCkNBTFNDQUxFOkdSRUdPUklBTgpCRUdJTjpWRVZFTlQKU1VNTUFSWTpBYnJhaGFtIExpbmNvbG4KRFRTVEFSVDoyMDA4MDIxMgpEVEVORDoyMDA4MDIxMwpEVFNUQU1QOjIwMTUwNDIxVDE0MTQwMwpFTkQ6VkVWRU5UCkVORDpWQ0FMRU5EQVI=

Errors

Please view our Errors documentation for a list of common error responses.

Code Description
email_address_missing
Type: validation_errorStatus: 422		 Message:
Recipient does not have an email address field
Developer Message:
Missing email address field for the email message type send
mobile_address_missing
Type: validation_errorStatus: 422		 Message:
Recipient does not have a mobile number field
Developer Message:
Missing mobile number field for the sms message type send
list_address_field_missing
Type: validation_errorStatus: 422		 Message:
Selected list does not have an address field
Developer Message:
Add an email or mobile field to the list that matches the message type
content_missing
Type: validation_errorStatus: 422		 Message:
Message is empty. Add some content.
Developer Message:
Must provide content body
group_missing
Type: validation_errorStatus: 422		 Message:
Invalid send group
Developer Message:
Either group_id or group_name is required
group_count_exceeded
Type: validation_errorStatus: 422		 Message:
Cannot create group
Developer Message:
Maximum number of transactional groups exceeded
invalid_attachment_name
Type: validation_errorStatus: 422		 Message:
One or more attachments are invalid
Developer Message:
Attachment name contains invalid characters
invalid_attachment_extension
Type: validation_errorStatus: 422		 Message:
One or more attachments are invalid
Developer Message:
Extension is not part of the valid set of extensions for the given mime type
invalid_attachment_content
Type: validation_errorStatus: 422		 Message:
One or more attachments are invalid
Developer Message:
Invalid base64 encoded content
account_owner_unverified
Type: validation_errorStatus: 422		 Message:
Your email must be verified before you can send
Developer Message:
Account owner email is not verified
recipient_destination_ambiguous
Type: validation_errorStatus: 422		 Message:
You must choose one destination to send to. Use contact ID, email, or mobile.
Developer Message:
Recipient destination is ambiguous. Specify only one of contact_id, email or mobile
invalid_wildcard_name_characters
Type: validation_errorStatus: 422		 Message:
Wildcard name contains invalid characters
Developer Message:
Wildcard name can only contain A-Z, a-z, 0-9, or _ (underscore)
invalid_wildcard_name_reserved
Type: validation_errorStatus: 422		 Message:
Wildcard name is reserved
Developer Message:
Wildcard name must not be id when sending to contacts in a list
invalid_wildcard_name_too_long
Type: validation_errorStatus: 422		 Message:
Wildcard name must be 255 or less characters long
Developer Message:
Wildcard name must not exceed 255 characters
invalid_wildcard_value_too_long
Type: validation_errorStatus: 422		 Message:
Wildcard replacement must be 10,000 or less characters long
Developer Message:
Wildcard replacement content must not exceed 10,000 characters
subject_empty
Type: validation_errorStatus: 422		 Message:
Message subject is empty
Developer Message:
A subject must be provided either directly via the subject field or by using an existing message by providing message_id
from_name_required
Type: validation_errorStatus: 422		 Message:
Message from name is empty
Developer Message:
The message specified by message_id does not have a from_name saved
invalid_from_address
Type: validation_errorStatus: 422		 Message:
Message from address is invalid
Developer Message:
From address is not a valid address for the message type
invalid_from_address_domain
Type: validation_errorStatus: 422		 Message:
The domain in the from address must be validated before it can be used
Developer Message:
Address must be a validated domain configured in your account
unverified_from_address
Type: validation_errorStatus: 422		 Message:
The from address must be verified before it can be used
Developer Message:
From address must be a verified address in your account
invalid_reply_to_address
Type: validation_errorStatus: 422		 Message:
Message reply-to address is invalid
Developer Message:
reply_to not a valid address for the message type
unverified_reply_to_address
Type: validation_errorStatus: 422		 Message:
The reply-to address must be verified before it can be used
Developer Message:
Reply-to address must be a verified address in your account
invalid_bcc_address_domain
Type: validation_errorStatus: 422		 Message:
The domain in the Bcc address must be validated before it can be used
Developer Message:
Address must be a validated domain configured in your account
redundant_unsubscribe_type
Type: validation_errorStatus: 422		 Message:
An unsubscribe_type cannot be provided along with a message_id
Developer Message:
When providing a message_id, it is expected for the message content to already contain the relevant stop words or opt-out link
unsubscribe_type_sender_mismatch
Type: validation_errorStatus: 422		 Message:
An unsubscribe_type cannot be provided when the sender is not a virtual number
Developer Message:
SMS responses can only be collected for virtual numbers
recipient_missing_list_id
Type: validation_errorStatus: 422		 Message:
You must provide a list_id
Developer Message:
A recipient can only be identified via contact_id in the context of a list. Provide a valid list_id or identify the recipient via mobile or email address
from_address_invalid_list
Type: validation_errorStatus: 422		 Message:
The specified from_address cannot be used with this list
Developer Message:
The From address provided or saved against the message is assigned to a different list
missing_stop_words
Type: validation_errorStatus: 422		 Message:
The content provided does not contain a valid stop word
Developer Message:
If a list_id is provided, body_text must contain one of the stop words defined on the list. Otherwise, body_text should contain STOP

Transactional Groups

The results for transactional sends are added to transactional groups.

The Transactional Group Object

Example Transactional Group

{
    "id": 135478,
    "type": "email",
    "name": "Reset Password Messages",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_sent_time": "2020-04-05T23:46:02Z",
    "sent": 72,
    "failed_contacts": 2,
    "bounced": 0,
    "delivered": 70,
    "opened": 15,
    "clicked": 14,
    "unsubscribed": 0,
    "_links": {
        "self": {
            "href": "/v1/transactional-groups/135478"
        }
    }
}

Attributes

Field Description
id integer Unique identifier for the instance.
Example: 135478
name string The name of the group. All group names are unique.
Example: Reset Password Messages
creation_time string, timestamp The instance's creation time.
Example: 2020-04-05T23:46:02Z
last_sent_time string, timestamp The instance's last sent time. This is the last time that a send was added to the group.
Example: 2020-04-05T23:46:02Z
sent integer Total recipients, i.e. total contact count that has been specified in all sends for this transactional group.
Example: 72
failed_contacts integer Total number of recipients that failed the validation.
Example: 2
bounced integer Total number of recipients that had an email bounce.
Example: 0
delivered integer Total number of recipients who successfully received a message.
Example: 70
opened integer One open is recorded for each individual recipient who opens a message, without duplicate opens.
Example: 15
clicked integer Total number of recipients that clicked any link (one or more links), one or more times.
Example: 14
unsubscribed integer Total number of recipients that unsubscribed because of a message from this transactional group (may happen multiple times per contact).
Example: 0
_links object Self discoverable links to the current object are provided.

Get Transactional Groups

Get one or more transactional groups with the following endpoints.

Get all Transactional Groups

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "offset": 0,
    "limit": 100,
    "size": 1,
    "_links": {
        "self": {
            "href": "/v1/transactional-groups"
        }
    },
    "_embedded": {
        "transactional-groups": [
            {
                "id": 135478,
                "type": "email",
                "name": "Reset Password Messages",
                "creation_time": "2020-04-05T23:46:02Z",
                "last_sent_time": "2020-04-05T23:46:02Z",
                "sent": 72,
                "failed_contacts": 2,
                "bounced": 0,
                "delivered": 70,
                "opened": 15,
                "clicked": 14,
                "unsubscribed": 0,
                "_links": {
                    "self": {
                        "href": "/v1/transactional-groups/135478"
                    }
                }
            }
        ]
    }
}

Returns a collection of your transactional groups.

Endpoint

GET /v1/transactional-groups{?id,name,creation_time,last_sent_time,sent,failed_contacts,bounced,delivered,opened,clicked,unsubscribed,fields}

Minimum API Key Access Level: Report Access

Parameters

Field Description
id integer, optional Unique identifier for the instance.
Example: 54
type enum, required The group type. Values include:
  • email
  • sms
Example: email
name string, optional Filter names by string filters.
Example: One Time Password
creation_time string, timestamp, optional Filter creation times by date and time filters.
Example: 2019-12-20T04:12:00Z
last_sent_time string, timestamp, optional Filter last sent times by date and time filters.
Example: 2019-12-20T04:12:00Z
sent integer, optional Filter the total sent messages by number filters.
Example: 32187
failed_contacts integer, optional Filter the total failed contact messages by number filters.
Example: 35
bounced integer, optional Filter the total bounced messages by number filters.
Example: 0
delivered integer, optional Filter the total delivered messages by number filters.
Example: 17548
opened integer, optional Filter the total opened messages by number filters.
Example: 5648
clicked integer, optional Filter the total clicked messages by number filters.
Example: 4975
unsubscribed integer, optional Filter the total unsubscribed messages by number filters.
Example: 23
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • name
  • creation_time
  • last_sent_time
  • sent
  • failed_contacts
  • bounced
  • delivered
  • opened
  • clicked
  • unsubscribed
Example: id,sent

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Get a Transactional Group

HTTP Response

200 OK
content-type: application/json; charset=UTF-8

{
    "id": 135478,
    "type": "email",
    "name": "Reset Password Messages",
    "creation_time": "2020-04-05T23:46:02Z",
    "last_sent_time": "2020-04-05T23:46:02Z",
    "sent": 72,
    "failed_contacts": 2,
    "bounced": 0,
    "delivered": 70,
    "opened": 15,
    "clicked": 14,
    "unsubscribed": 0,
    "_links": {
        "self": {
            "href": "/v1/transactional-groups/135478"
        }
    }
}

Returns the transactional group with the given ID.

Endpoint

GET /v1/transactional-groups/{id}{?fields}

Minimum API Key Access Level: Report Access

Parameters

Field Description
id integer, optional Unique identifier for the instance.
Example: 54
fields string, optional Select the fields to be within responses. Multiple values can be grouped by commas. Values include:
  • id
  • name
  • creation_time
  • last_sent_time
  • sent
  • failed_contacts
  • bounced
  • delivered
  • opened
  • clicked
  • unsubscribed
Example: id,sent

Errors

Please view our Errors documentation for a list of common error responses. There are no endpoint specific errors for this request.

Webhooks

Webhooks open opportunities for automated practises such as reacting to email opens, contact synchronisation and bounced email tracking.

Instead of requiring regular checks for updates via the API, webhooks send events direct to application URLs after they happen. Sending updates directly to applications allows for them to be kept up to date when our data changes or events are performed.

Batched events

When we send events to your application they'll be grouped together in batches of up to 1000 events that are spaced out by 10 second intervals. This means that when there's a lot happening in your account you'll receive all updates in smaller chunks that won't overload your application.

For example, if a user uploads 10,000 contacts from a spreadsheet we'll let you know of all changes over 10 separate webhook requests in 1 minute, 40 seconds.

Guidelines

Webhook Requests

Example Webhook Content Body

{
    "events": [
        {
            "object": "recipient",
            "event": "sent",
            "id": 1000059,
            "report_id": 45,
            "message_id": 9,
            "message_type": "email",
            "list_id": 27,
            "contact_id": 1837,
            "email": "alex@example.com",
            "timestamp": "2021-03-01T02:29:39Z"
        },
        {
            "object": "contact",
            "event": "created",
            "id": 1833,
            "list_id": 27,
            "timestamp": "2021-01-15T05:47:23Z"
        }
    ]
}

Events are sent with the following specifications:

Attributes

Field Description
events array A collection of webhook event instances.
events.* object Each webhook event instance can use the attributes outlined in Contact Events and Recipient Events. A maximum of 1000 webhook event instances can be sent per request.
events.*.object enum, fixed The instance type. Values include contact and recipient.
Example: recipient
events.*.event enum, fixed The action that has occurred.
Example: created
events.*.timestamp string, timestamp The datetime logged when the event occurred.
Example: 2020-04-05T23:46:02Z

Authorisation

The integrity of payloads can be verified by confirming one or more signed keys provided in every webhook request. There are multiple comma separated JWT signatures within the value of the Vision6-Signature header. A single verified signed key is enough to positively verify the payload.

We provide multiple signed keys for each webhook to allow applications to rotate their signed keys with a lowered risk of downtime or missed requests when updating signed keys.

For instructions on how to validate a JWT signature you can read the official JWT introduction. The secret values used to verify signatures are found within the platform.

Handling Failures

If application URLs do not respond to a webhook requests with successful HTTP status codes (200-299) then the responses are deemed to be errors. Redirection HTTP status codes (300-399) are also deemed to be errors and any returned location header values are not followed.

Requests are re-sent after error responses. Events expire after a day of failed requests.

Returning a 410 HTTP code will immediately delete the webhook.

Contact Events

The contact object events sent by webhooks are:

All examples within each event are shown as individual webhook events. They are placed within the events.* collection of webhook requests.

Contact Webhook Attributes

This instance contains instructions for locating a list's contact and how to identify the event that occurred.

Field Description
object enum, fixed The instance type. Values include contact.
Example: contact
event enum, fixed The action that has occurred. Values include:
  • created
  • updated
  • deleted
Example: created
id integer Unique identifier for the instance.
Example: 347
list_id integer The list id of the list that the contact is in.
Example: 3178
timestamp string, timestamp The datetime logged when the event occurred.
Example: 2020-04-05T23:46:02Z

Contacts Created

Example Contact Created Event

{
    "object": "contact",
    "event": "created",
    "id": 1000059,
    "list_id": 27,
    "timestamp": "2021-01-15T05:47:23Z"
}

This event is triggered when a contact is created.

Examples include:

Attributes

Recipient instances include all fields in contact webhook attributes.

Contacts Updated

Example Contact Sent Event

{
    "object": "contact",
    "event": "updated",
    "id": 1000059,
    "list_id": 27,
    "timestamp": "2021-01-15T05:47:23Z"
}

This event is triggered when a contact is updated.

Examples include:

Attributes

Recipient instances include all fields in contact webhook attributes.

Contacts Deleted

Example Contact Deleted Event

{
    "object": "contact",
    "event": "deleted",
    "id": 1000059,
    "list_id": 27,
    "timestamp": "2021-01-15T05:47:23Z"
}

This event is triggered when a contact is deleted.

Examples include:

Attributes

Recipient instances include all fields in contact webhook attributes.

Recipient Events

For emails, the recipient object events sent by webhooks are:

For SMS, the recipient object events sent by webhooks are:

All examples within each event are shown as individual webhook events. They are placed within the events.* collection of webhook requests.

How to identify how recipients are sent

There are variants of unique identifiers to track how recipients have been sent. Here are all situations that can occur.

Recipient Webhook Attributes

This instance contains instructions to identify how the recipient was sent, with additional data for the event triggered.

Note that there are many optional attributes within a recipient instance. If a particular attribute is not found within the instance, then it is not relevant to the event. For example, a recipient sent from a transactional send will not have automation_id and step_id attributes supplied.

Field Description
object enum, fixed The instance type. Values include recipient.
Example: recipient
event enum, fixed The action that occurred. Values include:
  • sent
  • opened
  • clicked
  • bounced
  • failed
Example: sent
id integer Unique identifier for the instance.
Example: 3178
automation_id integer, optional Unique identifier for the linked automation.
Example: 48
step_id integer, optional Unique identifier for the linked automation's step.
Example: 978
uuid string, optional Unique identifier for a recipient.
Example: j4RwlxSNekLlaFF0vi2tPg
group_id integer, optional Unique identifier for the linked group.
Example: 248
group_name string, optional Unique name for the linked group.
Example: Password Reset Report
message_id integer, optional Unique identifier for the linked message.
Example: 754
message_type enum, fixed, optional The type of message. Values include email and sms.
Example: email
list_id integer, optional Unique identifier for the linked list.
Example: 89
contact_id integer, optional Unique identifier for the linked list's contact.
Example: 478
email string, optional The email of the contact.
Example: john@example.com
mobile string, optional The mobile phone number of the contact.
Example: 0400000000
timestamp string, timestamp The datetime logged when the event occurred.
Example: 2020-04-05T23:46:02Z

Recipients Sent

Example Recipient Sent Event

{
    "object": "recipient",
    "event": "sent",
    "id": 1000059,
    "report_id": 45,
    "message_id": 9,
    "message_type": "email",
    "list_id": 27,
    "contact_id": 1837,
    "email": "alex@example.com",
    "timestamp": "2021-03-01T02:29:39Z"
}

This event is triggered when a recipient is sent a message.

Examples include:

Attributes

Recipient instances include all fields in recipient webhook attributes.

Recipients Opened

Example Recipient Opened Event

{
    "object": "recipient",
    "event": "opened",
    "id": 16000002,
    "uuid": "j4RwlxSNekLlaFF0vi2tPg",
    "group_id": 1,
    "group_name": "Reset Password",
    "message_id": 9,
    "message_type": "email",
    "list_id": 27,
    "contact_id": 1832,
    "email": "alice@example.com",
    "device_type": "Desktop",
    "device_name": "Gmail",
    "country_code": "AU",
    "timestamp": "2021-01-15T02:58:51Z"
}

This event is triggered when a recipient successfully opens the email message that has been sent to them.

Examples include:

Attributes

Recipient instances include all fields in recipient webhook attributes with the addition of the following attributes:

Field Description
device_type string, optional A description of the type of device used to interact with the message.
Example: Desktop
device_name string, optional A description of the device / mail client used to interact with the message.
Example: Gmail
country_code string, optional The last known country location of the device that interacted with the message. Formatted as an ISO 3166 Alpha-2 2 character country code.
Example: AU

Recipients Acknowledged

Example Recipient Acknowledged Event

{
    "object": "recipient",
    "event": "acknowledged",
    "id": 16000002,
    "uuid": "j4RwlxSNekLlaFF0vi2tPg",
    "group_id": 1,
    "group_name": "Reset Password SMS",
    "message_id": 9,
    "message_type": "sms",
    "list_id": 27,
    "contact_id": 1832,
    "mobile": "61400000000",
    "timestamp": "2021-01-15T02:58:51Z"
}

This event is triggered when the handset of a recipient acknowledges having received a SMS. This is dependent on the recipient's device acknowledging having received a SMS.

Recipients Clicked

Example Recipient Clicked Event

{
    "object": "recipient",
    "event": "clicked",
    "id": 16000002,
    "uuid": "j4RwlxSNekLlaFF0vi2tPg",
    "group_id": 1,
    "group_name": "Reset Password",
    "message_id": 9,
    "message_type": "email",
    "list_id": 27,
    "contact_id": 1832,
    "mobile": "61400000000",
    "device_type": "Desktop",
    "device_name": "Gmail",
    "link_url": "https://www.example.com/store",
    "link_type": "html_email",
    "country_code": "AU",
    "timestamp": "2021-01-15T02:58:53Z"
}

This event is triggered when a recipient successfully clicks a link within the message that was sent to them.

Examples include:

Attributes

Recipient instances include all fields in recipient webhook attributes with the addition of the following attributes:

Field Description
device_type string, optional A description of the type of device used to interact with the message.
Example: Desktop
device_name string, optional A description of the device or mail client used to interact with the message.
Example: Gmail
link_url string, optional The url of the link clicked.
Example: https://www.example.com/
link_type string, optional The type of link clicked. Values include html_email and text_email.
Example: html_email
country_code string, optional The last known country location of the device that interacted with the message. Formatted as an ISO 3166 Alpha-2 2 character country code.
Example: AU

Recipients Bounced

Example Recipient Bounced Event

{
    "object": "recipient",
    "event": "bounced",
    "id": 16000003,
    "uuid": "j4RwlxSNekLlaFF0vi2tPg",
    "group_id": 1,
    "group_name": "Reset Password",
    "message_id": 9,
    "message_type": "email",
    "list_id": 27,
    "contact_id": 1843,
    "email": "bob@example.com",
    "bounce_reason": "Incorrect Domain",
    "bounce_string": "Status: 5.1.2 (bad destination system: no such domain)",
    "is_temporary_bounce": false,
    "timestamp": "2021-01-15T02:58:55Z"
}

This event is triggered when a recipient has been sent and not reached successfully. When this occurs the outcome is reported within the bounce_reason, bounce_string and is_temporary_bounce attributes.

All bounce data should be considered accurate at the time the bounce was recorded. That said, from time to time there are going to be false positives. If you believe there is a false positive, we would recommend getting in contact directly with the recipient to follow up.

For a full and complete list of bounce status codes and reasons, please refer to the RFC available here: https://tools.ietf.org/html/rfc3463

Examples include:

Attributes

Recipient instances include all fields in recipient webhook attributes with the addition of the following attributes:

Field Description
bounce_reason string, optional A short description of why the message bounced.
Example: No such Mailbox
bounce_string string, optional Further diagnostic information about the bounce, typically including the bounce status code received from the remote mail system.
Example: Status: 5.1.1 (bad destination mailbox address)
is_temporary_bounce boolean, optional Indicates if this was a temporary bounce. If set to false then assume that this is a permanent bounce.
Example: false

Recipients Failed

Example Recipient Failed Event

{
    "object": "recipient",
    "event": "failed",
    "id": 16000002,
    "uuid": "j4RwlxSNekLlaFF0vi2tPg",
    "group_id": 1,
    "group_name": "Reset Password",
    "message_id": 9,
    "message_type": "email",
    "list_id": 27,
    "contact_id": 1832,
    "fail_reason": "The contact cannot be found",
    "timestamp": "2021-01-15T02:58:51Z"
}

This event is triggered when an attempt to send a message to a recipient has failed.

If this event occurs then visit the product to ensure that the contact, list, message and/or transactional groups required still exist and can be successfully saved.

Attributes

Recipient instances include all fields in recipient webhook attributes with the addition of the following attributes:

Field Description
fail_reason string, optional A short description of why Vision6 failed to send the message.
Example: `The contact cannot be found

SMS Events

The SMS events sent by webhooks are:

SMS Received

Example SMS received

{
    "object": "sms",
    "event": "received",
    "id": 16000002,
    "uuid": "j4RwlxSNekLlaFF0vi2tPg",
    "group_id": 1,
    "group_name": "Marketing Messages",
    "message_id": 9,
    "message_type": "sms",
    "list_id": 27,
    "contact_id": 1832,
    "mobile": "61400000000",
    "body_text": "UNSUBSCRIBE",
    "timestamp": "2021-01-15T02:58:51Z"
}

This event is triggered when an SMS response has been received.

Attributes

The instance include all fields in recipient webhook attributes with the addition of the following attributes:

Field Description
body_text string, optional The contents of the SMS response.
Example: UNSUBSCRIBE

Errors

Conventional HTTP response codes are used to indicate the success or failure of an API request. HTTP response codes in the 2xx range indicate success, while codes in the 4xx range indicate an error.

Response Payload

Invalid Request Schema Response

422 Unprocessable Entity
content-type: application/json; charset=UTF-8

{
    "id": "80001b6ad17281e4113cc5731d7f636ed3eca12d",
    "method": "POST",
    "status": 422,
    "type": "validation_error",
    "code": "invalid_attachment_name",
    "message": "There was an error in the request",
    "developer_message": "Check all the fields supplied in the request are valid",
    "field": "name",
    "collection": "attachments",
    "index": 2,
    "timestamp": "2020-12-15T03:50:21Z",
    "_links": {
        "error": {
            "href": "/rest-api/#transactional-send-endpoint-errors"
        },
        "self": {
            "href": "[current_url]"
        }
    }
}

Empty Request Body Response

400 Bad Request
content-type: application/json; charset=UTF-8

{
    "id": "ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca",
    "method": "GET",
    "status": 400,
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "The server did not understand the request.",
    "developer_message": "Check that the request body is properly encoded and not empty.",
    "timestamp": "2020-04-05T23:46:02Z",
    "_links": {
        "error": {
            "href": "/rest-api/#errors"
        },
        "self": {
            "href": "[current_url]"
        }
    }
}

Attributes

Field Description
id string The identifier for this error. This is not unique and is generated per response.
Example: ad4b90ae927dcd450bc238b7bf2729a0afe9d8ca
method enum, fixed The HTTP verb used for the current request. Values include:
  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
Example: POST
status integer The HTTP response code. Values include:
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 405 - Method Not Allowed
  • 409 - Conflict
  • 422 - Unprocessable Entity
  • 429 - Too Many Requests
  • 503 - Unavailable
Example: 422
type string The type of error provided. This is supplemented by the code. Values include:
  • ApiKeyInvalid
  • ApiKeyMissing
  • Conflict
  • InvalidApiVersion
  • InvalidRequest
  • IpRestricted
  • MethodNotAllowed
  • NotFound
  • PermissionDenied
  • ServiceUnavailable
  • SslRequired
  • TooManyRequests
  • ValidationError
Example: NotFound
code string, optional The key to represent the error. This is supplemented by the type.
Example: invalid_boolean
message string A user friendly error message.
Example: The server did not understand the request.
developer_message string A message to assist developers with correcting the request payload.
Example: Check that the request body is properly encoded and not empty.
field string, optional The field the error was caused by.
Example: mobile
collection string, optional If the error was caused by an element in a collection; the collection field.
Example: contacts
index integer, optional If the error was caused by an element in a collection; the element's index in the collection.
Example: 427
timestamp string, timestamp The creation time of this error.
Example: 2020-04-05T23:46:02Z
_links object Self discoverable links to the current object are provided. In addition a url to the documentation is also included for this error.
Example: /rest-api/#400-bad-request

Type Error Messages

The following errors are relevant to all error responses from the API.

Code Description
invalid_request
Type: invalid_requestStatus: 400		 Message:
The server did not understand the request.
Developer Message:
The request was invalid. Check that the request is correct and try again.
invalid_api_version
Type: invalid_api_versionStatus: 400		 Message:
Invalid API version
Developer Message:
The API version number was invalid. Check that the request is correct and try again.
api_key_missing
Type: api_key_missingStatus: 401		 Message:
Incorrect authentication details
Developer Message:
Authentication is required but the Authorization header was missing from the request
api_key_invalid
Type: api_key_invalidStatus: 401		 Message:
Incorrect authentication details
Developer Message:
The authentication details supplied in the Authorization header were invalid
api_key_invalid
Type: api_key_invalidStatus: 401		 Message:
Incorrect authentication details
Developer Message:
The access token is incompatible with this API. Please generate a new one
ip_restricted
Type: ip_restrictedStatus: 403		 Message:
You do not have permission to access the resource
Developer Message:
Account security settings prevent access from this IP
permission_denied
Type: permission_deniedStatus: 403		 Message:
You do not have permission to access the resource
Developer Message:
Check to make sure you have permission to perform the requested operation
ssl_required
Type: ssl_requiredStatus: 403		 Message:
You do not have permission to access the resource
Developer Message:
API is only accessible via https
not_found
Type: not_foundStatus: 404		 Message:
Could not find the requested resource.
Developer Message:
Check the requested URI to make sure it corresponds to a valid resource.
method_not_allowed
Type: method_not_allowedStatus: 405		 Message:
The operation is not permitted.
Developer Message:
The HTTP method used to access the resource is not permitted. Use OPTIONS to confirm the available methods.
conflict
Type: conflictStatus: 409		 Message:
There was an issue with the request.
Developer Message:
Check the fields object for more information and correct any issues before resubmitting the request.
validation_error
Type: validation_errorStatus: 422		 Message:
There was an error in the request
Developer Message:
Check all the fields supplied in the request are valid
too_many_requests
Type: too_many_requestsStatus: 429		 Message:
You do not have permission to access the resource
Developer Message:
Too many requests. API rate limit exceeded
service_unavailable
Type: service_unavailableStatus: 503		 Message:
The service you requested is not available at this time
Developer Message:
The service may be busy or down for maintenance. Please retry the request in a few moments

Schema Error Messages

The following errors are returned in situations where the field values within the requested payload are invalid.

Code Description
required
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Required field
not_empty
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must not be empty
too_long
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Too many characters or elements
too_short
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Too few characters or elements
invalid_range
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be between "[parameter]" and "[parameter]"
invalid_string
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a string
invalid_boolean
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a boolean
invalid_integer
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be an integer
invalid_number
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a number
invalid_positive_number
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a positive number
invalid_bitfield
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a valid bitfield combination
invalid_array
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be an array
invalid_object
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Invalid object, collection or invalid elements
invalid_collection
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a valid collection
invalid_id
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
The specified object could not be found. Check the id and try again
invalid_url
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a valid URL
invalid_iso_date_time
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a valid ISO 8601 date string
invalid_iso_date
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a valid ISO 8601 date and time string
invalid_date
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a valid date
invalid_date_time
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a valid date and time
invalid_email_address
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a valid email address
invalid_mobile_address
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Must be a valid mobile number
unexpected_field
Type: validation_errorStatus: 422		 Message:
Check all the fields supplied in the request are valid
Developer Message:
Unexpected field in request

Filter Error Messages

The following errors are returned in situations where the search filter within the requested payload are invalid.

Code Description
invalid_time_zone
Type: invalid_requestStatus: 400		 Message:
The time zone is invalid or not supported
Developer Message:
The time zone supplied in the "_tz" query string parameter is invalid or not supported
parameter_not_supported
Type: invalid_requestStatus: 400		 Message:
The "[parameter]" parameter is not a valid search filter
Developer Message:
The "[parameter]" query string parameter is not supported for this resource
parameter_not_available
Type: invalid_requestStatus: 400		 Message:
The "[parameter]" parameter is not available for this request method
Developer Message:
The "[parameter]" query string parameter is not available for this HTTP request method
invalid_operator
Type: invalid_requestStatus: 400		 Message:
The "[parameter]" parameter is not a valid search filter
Developer Message:
The "[parameter]" operator is not a valid search operator
invalid_query_syntax
Type: invalid_requestStatus: 400		 Message:
The "[query_field]" filter is not valid
Developer Message:
The syntax of the "[query_field]" query string parameter is not valid or is incorrect for this type of field
text_search_not_supported
Type: invalid_requestStatus: 400		 Message:
Full text search is not available for this resource
Developer Message:
The "q" query string parameter is not supported for this resource
invalid_order_by
Type: invalid_requestStatus: 400		 Message:
The "order_by" parameter is not valid
Developer Message:
The syntax of the "order_by" parameter is not valid or it contains an unknown field
invalid_limit
Type: invalid_requestStatus: 400		 Message:
The result limit must be a positive number
Developer Message:
The "limit" query string parameter must be a positive integer
invalid_offset
Type: invalid_requestStatus: 400		 Message:
The result offset must be a positive number
Developer Message:
The "offset" query string parameter must be a positive integer
invalid_filter_list
Type: invalid_requestStatus: 400		 Message:
The "[field_list]" filter is not valid
Developer Message:
The "[field_list]" filter must be a valid comma separated list

Migration Guide

If you are migrating from the JSON-RPC API then we suggest reading through all methods that are existing in your use case for migration notes and examples.

Lists Migration

The following methods have migration recommendations.

countLists

Get All Lists

GET /v1/lists?limit=0

When migrating from the countLists method you can:

getListById

Get All Lists

GET /v1/lists?id:in=478

When migrating from the getListById method you can:

searchLists

Get All Lists

GET /v1/lists

When migrating from the searchLists method you can:

Contacts Migration

The following methods have migration recommendations.

addContacts

Create Multiple Contacts

POST /v1/lists/174/contacts

{
    "contacts": [
        {
            "email": "fgdgfdsgsdf@gfdgfsd.gfsd",
            "account_key": "pwNtDm2h"
        },
        {
            "mobile": "0400000000",
            "subscribed": {
                "email": false,
                "mobile": true
            }
        }
    ]
}

When migrating from the addContacts method you can:

Automations will need to be updated to use new REST API specific Automation Triggers.

The overwrite field is not currently supported, but may be introduced at a later stage.

confirmContact

Update Multiple Contacts

PATCH /v1/lists/174/contacts

{
    "contacts": [
        {
            "id": 3487,
            "double_opt_in": true
        }
    ]
}

When migrating from the confirmContact method you can:

Automation events are not carried over from the JSON-RPC API.

countContacts

Get All Contacts

GET /v1/lists/174/contacts?limit=0

When migrating from the countContacts method you can:

deactivateContact

Update Multiple Contacts

PATCH /v1/lists/174/contacts

{
    "contacts": [
        {
            "id": 3487,
            "is_active": false
        }
    ]
}

When migrating from the deactivateContact method you can:

Automation events are not carried over from the JSON-RPC API.

deleteContacts

Delete Contacts

DELETE /v1/lists/174/contacts?id:in=23,467,42

When migrating from the deleteContacts method you can:

editContacts

Update Multiple Contacts

PATCH /v1/lists/174/contacts

{
    "contacts": [
        {
            "id": 3487,
            "email": "vincent@example.com"
        }
    ]
}

When migrating from the editContacts method you can:

getContactById

Get All Contacts

GET /v1/lists/174/contacts?id:in=478

When migrating from the getContactById method you can:

reactivateContact

Update Multiple Contacts

PATCH /v1/lists/174/contacts

{
    "contacts": [
        {
            "id": 3487,
            "is_active": true
        }
    ]
}

When migrating from the reactivateContact method you can:

Automation events are not carried over from the JSON-RPC API.

resubscribeContact

Update Multiple Contacts

PATCH /v1/lists/174/contacts

{
    "contacts": [
        {
            "id": 3487,
            "subscribed": {
                "email": true,
                "mobile": false
            }
        }
    ]
}

When migrating from the resubscribeContact method you can:

Automation events are not carried over from the JSON-RPC API.

The consent_type, consent_text, list_preferences and ip_address fields are not currently supported, but may be introduced at a later stage.

searchContacts

Get All Contacts

GET /v1/lists/174/contacts

When migrating from the searchContacts method you can:

subscribeContact

Create Multiple Contacts

POST /v1/lists/174/contacts

{
    "contacts": [
        {
            "id": 3487,
            "subscribed": {
                "email": true,
                "mobile": true
            }
        }
    ]
}

When migrating from the subscribeContact method you can:

The consent_type, consent_text, list_preferences and ip_address fields are not currently supported, but may be introduced at a later stage.

unsubscribeContact

Update Multiple Contacts

PATCH /v1/lists/174/contacts

{
    "contacts": [
        {
            "id": 3487,
            "subscribed": {
                "email": false,
                "mobile": false
            }
        }
    ]
}

When migrating from the unsubscribeContact method you can:

Automation events are not carried over from the JSON-RPC API.

unsubscribeContactById

Update Multiple Contacts

PATCH /v1/lists/174/contacts

{
    "contacts": [
        {
            "id": 3487,
            "subscribed": {
                "email": false,
                "mobile": false
            }
        }
    ]
}

When migrating from the unsubscribeContact method you can:

Automation events are not carried over from the JSON-RPC API.

Messages Migration

The following methods have migration recommendations.

countMessages

Get All Messages

GET /v1/messages?limit=0

When migrating from the countMessages method you can:

getMessageById

Get All Messages

GET /v1/messages?id:in=478

When migrating from the getMessageById method you can:

searchMessages

Get All Messages

GET /v1/messages

When migrating from the searchMessages method you can:

Transactional Migration

Documentation for sending transactional messages is found within Transactional Sends.

json