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:

• RESTful endpoints.
• HAL+JSON requests and responses.
  • The Content-Type within JSON responses are application/json, not application/hal+json.
• HTTPS only requests.

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:

• A Vision6 account
  • An account can be created at https://www.vision6.com.au/signup/
• A list
  • Lists can be created via the JSON-RPC API or via the platform.
• An active REST compatible API key
  • Create a new API key and/or check an existing API key's REST compatibility via the platform.
  • An REST compatible API key will be similar to aztM4wc0mWoX3ulJaF0RiJXETH3EYLaPgHYM54ZjzDICsfcRWw51nJ42pbEeFcsxyUl4IBYNvuaHQJER.
• The account's REST API endpoint
  • Endpoint hosts are generated based on an account by account basis. The endpoint for an account is found in the Integrations > API Keys page in the platform, under "REST API Endpoint". As such, endpoints are not included within documentation examples.
  • An endpoint will be similar to https://au1.api.vision6.com/v1/.

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:

• Messages
  • subject
• Message Contents
  • body_html
  • body_text
• Transactional Sends
  • subject
  • body_html
  • body_text

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:

• Message Contents
  • body_html
  • body_text
• Transactional Sends
  • body_html
  • body_text

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.

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.

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:

All datetimes and timestamps by default are in UTC.

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:

• Calculated on a per account basis.
• 120 requests per minute.
• 2000 requests per hour.

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

Advanced Automations

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"
        },
        "messages": {
            "href": "/v1/messages"
        },
        "transactional_groups": {
            "href": "/v1/transactional-groups"
        }
    }
}

Attributes

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"
        },
        "messages": {
            "href": "/v1/messages"
        },
        "transactional_groups": {
            "href": "/v1/transactional-groups"
        }
    }
}

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.

Lists can be created 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",
    "_links": {
        "self": {
            "href": "/v1/lists/3178"
        },
        "contacts": {
            "href": "/v1/lists/3178/contacts"
        }
    }
}

Attributes

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",
                "_links": {
                    "self": {
                        "href": "/v1/lists/3178"
                    },
                    "contacts": {
                        "href": "/v1/lists/3178/contacts"
                    }
                }
            }
        ]
    }
}

Returns a collection of your lists.

Endpoint

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

Minimum API Key Access Level: Standard Access

Parameters

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",
    "_links": {
        "self": {
            "href": "/v1/lists/3178"
        },
        "contacts": {
            "href": "/v1/lists/3178/contacts"
        }
    }
}

Returns the list with the given ID.

Endpoint

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

Minimum API Key Access Level: Standard Access

Parameters

Errors

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

Contacts

A contact is an individual in one of your lists.

Recommendations when managing contacts are:

• Create/update/delete contacts in batches over single requests. This will improve the performance of your requests.
• Ensure that an email and/or mobile field are set within each instance before creating/updating contacts.
• For custom contact data check out list fields.
• Decide on how you want to manage unsubscribes via the remove_unsubscribers parameter when creating contacts.

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.

Reserved Field Names

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

• id
• list_id
• creation_time
• last_modified_time
• email
• mobile
• blocked
• subscribed
• is_active
• double_opt_in
• double_opt_in_time
• _links
• _embedded

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

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

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

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

Parameters

Errors

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

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

Parameters

Errors

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

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

Errors

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

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

Errors

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

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?

• Valid responses will return a 204 No Content header with no content.
• If a failure occurs after the request validation then not all contacts may be deleted.

Parameters

Errors

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

Messages

A message is the metadata for an email or SMS template. Contacts can be sent messages.

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.

Messages can be created via the JSON-RPC API or via the platform.

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/3847"
        },
        "content": {
            "href": "/v1/messages/3847/content"
        }
    }
}

Attributes

The Message Content Object

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

Attributes

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/3847"
                    },
                    "content": {
                        "href": "/v1/messages/3847/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

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/3847"
        },
        "content": {
            "href": "/v1/messages/3847/content"
        }
    }
}

Returns the message with the given ID.

Endpoint

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

Minimum API Key Access Level: Limited Access

Parameters

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/3847/content"
        },
        "message": {
            "href": "/v1/messages/3847"
        }
    }
}

Returns the message content with the given message ID.

Endpoint

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

Minimum API Key Access Level: Limited Access

Parameters

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:

• Dynamic content can be sent without the requirement to store messages.
• A single API request can send messages on demand, up to 100 recipients.
• Wildcards may include sensitive values, as these are not stored after each send.
• Email messages can be sent with custom attachments. These do not count towards your file and image limits.

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:

• Message type
• Transactional group
• Email message ID - This is the ID of a message previously created
• List ID and a contact with an Email field

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:

• Message type
• Transactional group
• An email message with a from_name, from_address, subject, body_html and/or body_text
• List of recipients

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:

• Message type
• Transactional Group
• SMS Message ID - This is the ID of a message previously created
• List ID and a contact with an Mobile field

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:

• Message type
• Transactional group
• SMS message with a valid from_address (mobile number) and body_text
• List of recipients

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:

• Message type
• Transactional group
• Message with a valid from_address (mobile number) and body_text - When type is email a valid from_address is also required
• List ID and a list of contacts

Recipients

Recipients must have at least one of these:

• contact_id
• email
• mobile

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:

• contact_id (integer) - When specified, must be present in list_id and have a valid Email field value.
• email (string) - Must be a correctly formatted email address. If the email address doesn’t exist in list_id a new contact will be added.

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:

• contact_id (integer) - When specified, must be present in list_id and have a valid Mobile field value.
• mobile (string) - must be a correctly formatted mobile number. When a list_id is provided the list must have a valid Mobile field. See Valid Mobile Phone Numbers.

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.

• If group_id is provided then we search for an existing transactional group with a matching id. If none are found then we return an error.
• If group_name is provided then we search for an existing transactional group with a matching name and type. If none are found then we create a new transactional group with the supplied group_nameand type.
• If both group_id and group_name are provided then we ignore group_name.
• When providing a group_id, the type of the send (email or sms) must match the type of the group

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:

• contact_id
• email
• mobile
• attachments

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

Email Domain Configuration

For email sends it is required that the domains used within the from_address and bcc_address fields are configured within the platform. A configured domain will require SPF and DKIM domain records to be added, supplied within the Account > Domains page in the platform.

You can find out more about how to configure your domain name at Emails Going to Spam? Set up Your Domain Records. Please note that certain domains may not send emails until they are configured.

Once a domain is configured within the platform then it will also be DMARC aligned, and eligible for a DMARC policy.

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": "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"
        }
    ]
}

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": "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"
                },
                {
                    "type": "image/png",
                    "name": "event_qr_code.png",
                    "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
                }
            ]
        }
    ]
}

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

• Shared attachments can be included at the top level of the request payload. All recipients will receive a copy of the shared attachment (e.g.: Terms and Condtions.pdf).
• Recipient specific attachments can be included at the recipient level of the request. Only the recipient will receive these attachments (e.g.: Invoice 1234.pdf).
• It is required for all attachments to use unique names
• The content field is the contents of the file to attach. It must be base64 encoded.

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:

• image/jpeg
• image/png
• image/gif

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:

• jpg, jpeg, png, gif
• pdf
• eps
• rtf, txt
• swf
• mpg, mpeg
• csv
• xlsx, xls
• pptx, ppsx, pps, ppt, pot, ppa
• doc, docx
• wmv, avi, wav
• mov
• zip
• vcf, ics, vcs

SMS Sender IDs

All sms sends must use a sender ID previously approved for use with SMS in the from_address.

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

Examples include:

• 61400000000 - Your own mobile number
• Vision6 - Brand Name
• 440000000000 - Dedicated Number

Dedicated numbers assigned to lists must be assigned to the from_address.

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:

• word - Replies to your SMS messages will be checked for valid STOP words
  • For batch sends the product UI automatically adds Reply STOP to opt out, The API allows unsubscribe words within the message.
  • Valid stop/unsubscribe words include STOP and any of the list's stop/unsubscribe words (if a list_id is provided).
  • If the message doesn’t contain any valid unsubscribe words, a missing_stop_words error will be returned.
• link - An unsubscribe link will be added to the end of the message.
  • Warning: link adds text to the SMS. Extra SMS credits may be required to complete the send.
• none - Default setting. No changes will occur to your message's content.

Request Limits

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

• Valid response payloads will be a 202 Accepted with no content.
• Your unique identifier for reporting will be your requested transactional group names and IDs.
• If a failure occurs when sending to recipients the results will show within the transactional groups.

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

• 15MB in size. This includes email attachments and individual recipient attachments.
• All payload, recipient and wildcard key characters are required to be lowercase, alphanumeric or underscores.

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 uuid field is included in transactional webhook payloads, allowing for correlation with the initial transactional send recipient
• The uuids are generated and returned immediately as part of the response body
• An array of recipients is returned as an embedded resource, and each recipient instance contains a uuid field
• The recipients returned in the response are in the same order as they were provided in the request

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

Errors

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

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

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

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

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

• Respond to webhook requests immediately with a successful HTTP response code (200-299).
  • Creating your own database queues are great for managing events.
  • Other HTTP response status codes may lead to the webhook being deleted.
• When analysing events always check the object and event attributes first. These describe which attributes have been sent within the payload.
• Choose events that match the requirements of the application URL. Doing this will reduce the number of events sent.
• Testing can be achieved by creating a new webhook then creating a contact or sending a transactional email.

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:

• Requests use POST methods with a application/json; charset=UTF-8 content-type.
• Multiple events are batched within the events.* collection.
  • There is a limit of 1000 event instances.
  • Events do not have a guaranteed order by datetime or unique identifier.
• The user agent for requests will contain Vision6 Webhooks.
• Multiple webhooks using the same URL can be differentiated via the Vision6-Webhook-Id header. The value is the webhook's id.
• Authorisation can be completed by validating the Vision6-Signature header's signed keys.
• Requests are sent from our listed IP addresses. Note that these are subject to change.

Attributes

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:

• created
• updated
• deleted

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.

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:

• Creating a single new contact within the platform will create a single event.
• Uploading a spreadsheet with new contacts within the platform will create many events.
• Creating contacts via the API will create an event per contact.

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:

• Updating a single contact from within the platform will create a single event.
• Uploading a spreadsheet that updates contacts will create many events.
• Updating contacts via the API will create an event per contact.

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:

• Deleting a single contact from within the platform will create a single event.
• Selecting all contacts within a table and deleting all will create many events.
• Deleting contacts via the API will create an event per contact.

Attributes

Recipient instances include all fields in contact webhook attributes.

Recipient Events

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

• sent
• opened
• clicked
• bounced
• failed

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

• sent
• akcnowledged
• bounced
• failed

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.

• Transactional sends contain a uuid (see Correlation), group_id and group_name.
• Automated messages contain an automation_id and step_id.
• All other send methods contain a report_id.

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.

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: