Using the Letterhead API

Edit in CMS

The Letterhead API lets you work with your newsletters from your own code — your audience, your content, your sending, and your reporting. Everything you can do in the dashboard, you can build around.

Authentication

Every request needs an API key sent as a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

One key reaches every newsletter in your account, so you don’t need a separate key per newsletter. See Generate & manage API keys to create one.

Most read endpoints also expect api=true in the query string. It tells Letterhead you’re authenticating with a key rather than a signed-in session, and the reference notes it wherever it applies.

Base URL

Requests go to the same subdomain you sign in with — just swap api in for app:

If you sign in at https://{yourPrefix}.app.tryletterhead.com, your API base URL is https://{yourPrefix}.api.tryletterhead.com. For example, acme.app.tryletterhead.com becomes acme.api.tryletterhead.com.
If you sign in at the plain https://app.tryletterhead.com (no subdomain), your API base URL is the plain https://api.tryletterhead.com.

What you can build

Your audience — add, update, and remove contacts, set their subscription status per newsletter, and tag people in bulk
Segments — create and update saved audience groups, count who’s in one, preview the members, and pull engagement over time — or list Letterhead’s built-in system segments (see below) instead of hard-coding their IDs
Content — push articles into your curation library and distribute them across newsletters, including in bulk for many articles in one request
Sending — draft a letter from your own HTML or from a template, then send it — see Sending your own HTML for what’s tracked automatically and what can get a send rejected
Your newsletters — list what you’ve published, across your whole account or a chosen few of your newsletters, and narrow the list to the ones carrying a tag you organize by (see below)
Promotions — create and manage the paid placements running inside your newsletters
Reporting — pull opens, clicks, bounces, and unsubscribes, with a daily breakdown and per-newsletter detail
Audience overlap — shared subscriber counts for every pair of newsletters, and combined unique reach for a selection

Filtering your newsletters by tag

If you organize your newsletters with tags, you can ask for just the ones carrying a tag rather than pulling everything and sorting it out in your own code.

First list your tags to get their ids, then pass those ids when you list your newsletters:

GET /api/v3/letters/tags?api=true
GET /api/v3/letters?api=true&allChannels=true&tags[]=<tagId>

Two things worth knowing before you build against it:

Naming more than one tag narrows the list, it doesn’t widen it. Asking for two tags returns the newsletters carrying both of them, not the ones carrying either. To gather everything across several tags, ask for one tag at a time and combine the results yourself.
You can name up to 50 tags in a request, and the filter works the same way whichever set you’re listing — your templates, a chosen few newsletters, or everything at once.

The same filter works when you pull performance numbers for many newsletters at once. The metrics request takes its tags inside a filters object, and the total it returns counts only the newsletters that match:

POST /api/v3/letters/metrics?api=true
{ "filters": { "tags": ["<tagId>"] } }

Each tag must be sent as its id, as text, exactly as the tag list returns it — a number, an empty entry, or more than 50 tags is rejected rather than quietly ignored.

Listing the built-in system segments

Alongside the segments you build yourself, every account has a set of built-in, read-only system segments — Loyalists, New & Engaged, Casual, Fading, Ghosts, Single Newsletter, Everyone but Ghosts, and (on some accounts) a 60-day version of Everyone but Ghosts. Each already sends to a reserved numeric ID, but until now the only way to find that number was to copy it out of the app’s URL. List them from their own endpoint instead:

GET /api/v3/contacts/segments/system?api=true

Each entry in the response carries an id — the number to pass as segment when scheduling or sending a letter — a stable key, and a display name. It’s a separate, read-only listing: it doesn’t affect GET /api/v3/contacts/segments above, and a system segment can’t be created, updated, or deleted.

API reference

The complete endpoint reference — paths, parameters, request and response formats, and examples — is in the API reference on this site. It’s generated from the API’s own specification, so it stays in step with what the API actually does.

Next steps

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