API docs

Appearance

On this page

Emails ​

Endpoints ​

GET /v1/emails
GET /v1/emails/:id
GET /v1/emails/:id/recipients
GET /v1/emails/:id/opens
GET /v1/emails/:id/web_visits
GET /v1/emails/:id/links
GET /v1/emails/:id/clicks

List emails ​

GET /v1/emails

Gets a list of emails.

Parameters ​

NameOptionalDefaultDescriptionOptions
Pagination parametersSee pagination for more information.
sortoptionalcreated_atThe attribute to sort results by.created_at, published_at, recipients_count, opens_count
orderoptionaldescThe order of results based on the sort attribute.desc, asc
stateoptionalnoneFilters results to only include campaigns in the given state.published, scheduled, draft

Returns ​

A page of email summary objects.

Example response
json
{
  "object": "array",
  "has_more": true,
  "next": "/v1/emails?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "email",
      "id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      "title": "Weekly Newsletter - Jan 24",
      "state": "published",
      "owner": "user@example.com",
      "recipients_count": 72,
      "created_at": "2022-01-20T00:00:00.000Z",
      "updated_at": "2022-01-24T09:00:00.000Z",
      "last_modified_at": "2022-01-24T09:00:00.000Z",
      "scheduled_at": null,
      "published_at": "2022-01-24T09:00:00.000Z",
      "from_name": "Comms Department",
      "from_email": "comms@example.com",
      "reply_to_email": "comms@example.com",
      "subject_line": "Weekly Newsletter - January 24th",
      "preview_text": "Check out this week's newsletter!",
      "urls": {
        "details": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa",
        "recipients": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/recipients",
        "opens": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/opens",
        "web_visits": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/web_visits",
        "links": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/links",
        "clicks": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/clicks",
      },
    },
    {...},
    {...},
    {...},
    {...},
  ],
}

Retrieve an email ​

GET /v1/emails/:id

Gets the details of a single email.

Parameters ​

No parameters

Returns ​

An email object with the full object details and properties.

Example response
json
{
  "object": "email",
  "id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
  "title": "Weekly Newsletter - Jan 24",
  "state": "published",
  "owner": "user@example.com",
  "last_editor": "user@example.com",
  "recipients_count": 72,
  "opens_count": 60,
  "web_visits_count": 0,
  "links_count": 2,
  "clicks_count": 24,
  "unique_clicks_count": 20,
  "created_at": "2022-01-20T00:00:00.000Z",
  "updated_at": "2022-01-24T09:00:00.000Z",
  "last_modified_at": "2022-01-24T09:00:00.000Z",
  "scheduled_at": null,
  "published_at": "2022-01-24T09:00:00.000Z",
  "from_name": "Comms Department",
  "from_email": "comms@example.com",
  "reply_to_email": "comms@example.com",
  "subject_line": "Weekly Newsletter - January 24th",
  "preview_text": "Check out this week's newsletter!",
  "campaigns": [
    {
      "id": "e76d4cb7-e1e7-4579-ab24-7967377bfdd7",
      "name": "Weekly Newsletter",
      "details": "/v1/campaigns/e76d4cb7-e1e7-4579-ab24-7967377bfdd7"
    },
    {
      "id": "4ab1458c-91f9-4aae-bb22-22f1d5ef88b1",
      "name": "Comms Department Campaign",
      "details": "/v1/campaigns/4ab1458c-91f9-4aae-bb22-22f1d5ef88b1"
    }
  ],
  "urls": {
    "details": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa",
    "recipients": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/recipients",
    "links": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/links",
    "opens": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/opens",
    "web_visits": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/web_visits",
    "clicks": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/clicks"
  }
}

List recipients of an email ​

GET /v1/emails/:id/recipients

Gets recipients of an email.

Parameters ​

NameOptionalDefaultDescription
Pagination parametersSee pagination for more information.

Returns ​

A page of recipient objects. Each recipient is a simple object, containing the recipient's id, email, first name, and last name only.

Example response
json
{
  "object": "array",
  "has_more": true,
  "next": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/recipients?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "recipient",
      "id": "03f10d07-5cd9-4095-82e2-bc0c5e0d561e",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
    },
    {...},
    {...},
    {...},
    {...},
  ],
}

List opens of an email ​

GET /v1/emails/:id/opens

Gets the opens of an email.

Parameters ​

NameOptionalDefaultDescription
Pagination parametersSee pagination for more information.

Returns ​

A page of open objects. Each open is a simple object, containing the open's id, the recipient's email that the open belongs to, when the open event occurred, the duration of time the email was open, and the device the email was opened on (desktop, mobile, or other).

Example response
json
{
  "object": "array",
  "has_more": true,
  "next": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/opens?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "open",
      "id": "15a0dec5-e61f-4465-be96-237cc0d8edb0",
      "recipient": "john@example.com",
      "opened_at": "2022-01-24T09:12:07.000Z",
      "duration": 5000,
      "device_type": "desktop",
    },
    {...},
    {...},
    {...},
    {...},
  ],
}

List web visits of an email ​

GET /v1/emails/:id/web_visits

Gets web visits from an email.

Parameters ​

NameOptionalDefaultDescription
Pagination parametersSee pagination for more information.

Returns ​

A page of web visit objects. Each web visit is a simple object, containing the web visit's id, the recipient's email that the visit belongs to (null for anonymous visits), when the visit occurred, the referrer that led to the visit, IP address, and user agent.

Example response
json
{
  "object": "array",
  "has_more": true,
  "next": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/web_visits?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "web_visit",
      "id": "15a0dec5-e61f-4465-be96-237cc0d8edb0",
      "recipient": "john@example.com",
      "visited_at": "2022-01-24T09:12:07.000Z",
      "referrer": "email",
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
    },
    {
      "object": "web_visit",
      "id": "22b1fed6-f72e-4566-cf07-348dd1d9fec1",
      "recipient": null,
      "visited_at": "2022-01-24T10:15:33.000Z",
      "referrer": "sharepoint",
      "ip_address": "10.0.0.1",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
    },
    {...},
    {...},
    {...},
  ]
}

INFO

The referrer field indicates how users accessed the content. Possible values are: email, slack, text, sharepoint, web, teams, archive, page.

The recipient field will be null for anonymous web visits where the visitor is not associated with a known contact.

GET /v1/emails/:id/links

Gets links in an email.

Parameters ​

NameOptionalDefaultDescription
Pagination parametersSee pagination for more information.

Returns ​

A page of link objects. Each link is a simple object, containing the link id, href, count of clicks on the link, count of unique clicks, and a url to query for the full details of the link object.

Example response
json
{
  "object": "array",
  "has_more": false,
  "next": null,
  "limit": 5,
  "size": 2,
  "data": [
    {
      "object": "link",
      "id": "5eac7299-e279-49a0-8db5-2e2ec2edefc0",
      "link_href": "https://google.com",
      "clicks_count": 4,
      "unique_clicks_count": 3,
      "urls": {
        "details": "/v1/links/5eac7299-e279-49a0-8db5-2e2ec2edefc0",
      },
    },
    {...},
  ],
}

List clicks in an email ​

GET /v1/emails/:id/clicks

Gets clicks on all links in an email.

Parameters ​

NameOptionalDefaultDescription
Pagination parametersSee pagination for more information.

Returns ​

A page of click objects. Each click is a simple object, containing the click's id, recipient's email, and when the link was clicked. Each click object also contains simple objects for the associated link and email.

Example response
json
{
  "object": "array",
  "has_more": false,
  "next": null,
  "limit": 5,
  "size": 4,
  "data": [
    {
      "object": "click",
      "id": "9dbc3ed6-157f-41ea-891b-f7ddcab5a46d",
      "recipient": "john@example.com",
      "clicked_at": "2022-01-24T09:12:34.000Z",
      "link": {
        "id": "5eac7299-e279-49a0-8db5-2e2ec2edefc0",
        "link_href": "https://google.com",
        "details": "/v1/links/5eac7299-e279-49a0-8db5-2e2ec2edefc0",
      },
      "email": {
        "id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
        "title": "Weekly Newsletter - Jan 24",
        "details": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      },
      "urls": {
        "link": "/v1/links/5eac7299-e279-49a0-8db5-2e2ec2edefc0",
        "email": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      },
    },
    {...},
    {...},
    {...},
  ],
}