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/links
GET /v1/emails/:id/clicks

List emails ​

GET /v1/emails

Returns 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 paginated list of email summary objects.

EXAMPLE RESPONSE ​

json
{
  "object": "list",
  "next": "/v1/emails?limit=5&start=5",
  "limit": 5,
  "start": 0,
  "data": [
    {
      "object": "email",
      "id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      "title": "Weekly Newsletter - Jan 24",
      "state": "published",
      "owner": "user@example.com",
      "recipients_count": 72,
      "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",
        "links": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/links",
        "clicks": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/clicks",
      },
    },
    {...},
    {...},
    {...},
    {...},
  ],
  "size": 5,
}

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!",
  "campaign": {
    "id": "e76d4cb7-e1e7-4579-ab24-7967377bfdd7",
    "name": "Weekly Newsletter",
    "details": "/v1/campaigns/e76d4cb7-e1e7-4579-ab24-7967377bfdd7"
  },
  "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",
    "clicks": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/clicks"
  }
}

List recipients of an email ​

GET /v1/emails/:id/recipients

Gets a list of recipients of an email.

Parameters ​

NameOptionalDefaultDescription
Pagination parametersSee pagination for more information.

RETURNS ​

A paginated list 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": "list",
  "next": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/recipients?limit=5&start=5",
  "limit": 5,
  "start": 0,
  "data": [
    {
      "object": "recipient",
      "id": "03f10d07-5cd9-4095-82e2-bc0c5e0d561e",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
    },
    {...},
    {...},
    {...},
    {...},
  ],
  "size": 5,
}

List opens of an email ​

GET /v1/emails/:id/opens

Gets a list of opens of an email.

Parameters ​

NameOptionalDefaultDescription
Pagination parametersSee pagination for more information.

RETURNS ​

A paginated list 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": "list",
  "next": "/v1/emails/937ccbe2-4cb5-4c76-96bf-29510b514dfa/opens?limit=5&start=5",
  "limit": 5,
  "start": 0,
  "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",
    },
    {...},
    {...},
    {...},
    {...},
  ],
  "size": 5,
}
GET /v1/emails/:id/links

Gets a list of links in an email.

Parameters ​

NameOptionalDefaultDescription
Pagination parametersSee pagination for more information.

RETURNS ​

A paginated list 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": "list",
  "next": null,
  "limit": 5,
  "start": 0,
  "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",
      },
    },
    {...},
  ],
  "size": 2,
}

List clicks in an email ​

GET /v1/emails/:id/clicks

Gets a list of clicks associated with an email.

Parameters ​

NameOptionalDefaultDescription
Pagination parametersSee pagination for more information.

RETURNS ​

A paginated list 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": "list",
  "next": null,
  "limit": 5,
  "start": 0,
  "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",
      },
    },
    {...},
    {...},
    {...},
  ],
  "size": 4,
}