Compare audience overlap for selected newsletters

GET

/api/v3/contacts/overlap/selection

const url = 'https://api.tryletterhead.com/api/v3/contacts/overlap/selection?channels%5B%5D=example';
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/overlap/selection?channels%5B%5D=example' \
  --header 'Authorization: Bearer <token>'

Returns a Venn-style overlap breakdown for a chosen set of 2 to 5 newsletters from your company audience: the total unique reach across the set, each newsletter’s own total plus the count exclusive to it, and the shared count for every group of two or more of the selected newsletters. Counts are active subscribers only, deduplicated by email.

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

Authorizations

bearerAuth

Parameters

Query Parameters

channels[]

required

string

Channel identifier (slug) of a newsletter to compare. Repeat the parameter once per newsletter — between 2 and 5 in total, and each must be distinct.

api

boolean

Set to true to receive the JSON API response.

Responses

200

200 OK

application/json

object

items

object

uniqueReach

Distinct contacts active on at least one newsletter in the set (the deduped union).

integer

newsletters

One entry per selected newsletter.

Array<object>

object

channel

The newsletter’s channel identifier (slug).

string

name

The newsletter’s display name.

string

activeSubscribers

The newsletter’s own active-subscriber total.

integer

exclusiveActiveSubscribers

Subscribers active on this newsletter and no other in the set.

integer

groupOverlaps

One entry per group of 2 or more selected newsletters (the intersection regions).

Array<object>

object

channels

The newsletters in the overlap region, each as { channel, name }.

Array<object>

object

channel

string

name

string

sharedActiveSubscribers

Subscribers shared across that group.

integer

message

string

total

integer

Example

{
  "items": {
    "uniqueReach": 18100,
    "newsletters": [
      {
        "channel": "channel-one",
        "name": "The Daily",
        "activeSubscribers": 12400,
        "exclusiveActiveSubscribers": 9300
      },
      {
        "channel": "channel-two",
        "name": "Weekend Reads",
        "activeSubscribers": 8800,
        "exclusiveActiveSubscribers": 5700
      }
    ],
    "groupOverlaps": [
      {
        "channels": [
          {
            "channel": "channel-one",
            "name": "The Daily"
          },
          {
            "channel": "channel-two",
            "name": "Weekend Reads"
          }
        ],
        "sharedActiveSubscribers": 3100
      }
    ]
  },
  "message": "Newsletter overlap selection",
  "total": 1
}

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