Get a contact's engagement breakdown

GET

/api/v3/contacts/{email}/engagement

const url = 'https://api.tryletterhead.com/api/v3/contacts/example/engagement?api=true';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/contacts/example/engagement?api=true' \
  --header 'Authorization: Bearer <token>'

Returns a contact’s lifetime engagement rolled up into counters and rates — how many newsletters reached them, how many they opened and clicked, their bounce history, and how often they clicked a promotion.

This is the summary counterpart to Get a contact’s activity, which returns the individual events these numbers are derived from.

This is a company-level (v3) read. Authenticate with a company API key as a Bearer token.

Authorizations

bearerAuth

Parameters

Path Parameters

email

required

string

The contact’s email address.

Query Parameters

api

required

boolean

Set to true.

channel

string

Roll up only the contact’s activity on a single newsletter, by channel slug. Omit for every newsletter in the company.

Responses

200

200 OK

application/json

object

items

object

delivered

Newsletters successfully delivered to the contact.

integer

uniqueOpens

Newsletters the contact opened at least once.

integer

uniqueClicks

Newsletters in which the contact clicked at least one link.

integer

openRate

uniqueOpens as a percentage of delivered.

number

clickRate

uniqueClicks as a percentage of delivered.

number

clickToOpenRate

uniqueClicks as a percentage of uniqueOpens.

number

softBounces

Soft bounces recorded for the contact — temporary failures such as a full mailbox.

integer

hardBounces

Hard bounces recorded for the contact — permanent failures such as an invalid address.

integer

promotionClicks

Clicks the contact made on promotions, as opposed to editorial links.

integer

message

string

total

integer

Example

{
  "items": {
    "delivered": 184,
    "uniqueOpens": 121,
    "uniqueClicks": 37,
    "openRate": 65.8,
    "clickRate": 20.1,
    "clickToOpenRate": 30.6,
    "softBounces": 2,
    "hardBounces": 0,
    "promotionClicks": 4
  },
  "message": "Engagement breakdown retrieved.",
  "total": 1
}

Still can’t find what you need? Contact support.