Skip to content
Letterhead Letterhead Letterhead Help Center
Admin Tools

Overview

Edit in CMS

Letterhead API 3.0.0

Section titled “Letterhead API 3.0.0”

Letterhead’s API lets you build around your newsletters — your audience, your content, your sending, and your reporting.

We release it with stability in mind, and we add to it regularly. If something looks wrong, or you need something that isn’t here yet, let us know.

Authorization

Every request needs a Bearer token. Administrators can generate an API key at any time from Settings -> API Keys, then send it in the Authorization header:

Authorization: Bearer <your-api-key>

Keys are company-scoped: one key reaches every newsletter in your account.

Most read endpoints also expect api=true in the query string, which tells Letterhead you are authenticating with an API key rather than a signed-in session.

Information

  • OpenAPI version: 3.0.3

Operations

Section titled “ Operations ”
GET
/api/v3/contacts/overview
GET
/api/v3/contacts/metrics/groups
POST
/api/v3/contacts
GET
/api/v3/contacts/overlap
GET
/api/v3/contacts/overlap/selection
POST
/api/v3/contacts/search
POST
/api/v3/contacts/browse
GET
/api/v3/contacts/tags
POST
/api/v3/contacts/tags
GET
/api/v3/contacts/tags/{tagId}
PUT
/api/v3/contacts/tags/{tagId}
DELETE
/api/v3/contacts/tags/{tagId}
POST
/api/v3/contacts/tags/{tagId}/apply
POST
/api/v3/contacts/tags/{tagId}/strip
POST
/api/v3/contacts/tags/{tag}/members
DELETE
/api/v3/contacts/tags/{tag}/members
GET
/api/v3/contacts/{email}
PUT
/api/v3/contacts/{email}
DELETE
/api/v3/contacts/{email}
GET
/api/v3/contacts/{email}/activity
GET
/api/v3/contacts/{email}/engagement
GET
/api/v3/contacts/{email}/last-active
GET
/api/v3/contacts/{email}/suppressions
GET
/api/v3/contacts/{email}/export
POST
/api/v3/contacts/{email}/subscriptions
POST
/api/v3/contacts/{email}/subscriptions/bulk
PUT
/api/v3/contacts/{email}/subscriptions/{channelSlug}
DELETE
/api/v3/contacts/{email}/subscriptions/{channelSlug}
GET
/api/v3/contacts/engagement-timeline
GET
/api/v3/contacts/imports
GET
/api/v3/contacts/imports/{importUniqueId}/errors
POST
/api/v3/contacts/imports/{importUniqueId}/retry
GET
/api/v3/contacts/custom-fields
POST
/api/v3/contacts/custom-fields
GET
/api/v3/contacts/custom-fields/segment-criteria
GET
/api/v3/contacts/custom-fields/{fieldId}
PUT
/api/v3/contacts/custom-fields/{fieldId}
DELETE
/api/v3/contacts/custom-fields/{fieldId}
POST
/api/v3/audience
GET
/api/v3/contacts/segments
POST
/api/v3/contacts/segments
GET
/api/v3/contacts/segments/{segmentId}
PUT
/api/v3/contacts/segments/{segmentId}
DELETE
/api/v3/contacts/segments/{segmentId}
GET
/api/v3/contacts/segments/{segmentId}/count
GET
/api/v3/contacts/segments/{segmentId}/engagement-timeline
GET
/api/v3/contacts/segments/{segmentId}/engagement-timeline/csv
POST
/api/v3/contacts/segments/{segmentId}/preview
POST
/api/v3/contacts/segments/criteria/count
GET
/api/v3/contacts/segments/location-coverage
GET
/api/v3/audience/segments
GET
/api/v3/letters
POST
/api/v3/letters/actions/draft
POST
/api/v3/letters/actions/send
POST
/api/v3/letters/subject-line-analyses
GET
/api/v3/letters/subject-line-performances
POST
/api/v3/letters/templates/actions/generate-from-url
GET
/api/v3/letters/templates/active
GET
/api/v3/letters/{letterUuid}
POST
/api/v3/letters/{letterUuid}
POST
/api/v3/letters/{letterUuid}/actions/draft
POST
/api/v3/letters/{letterUuid}/actions/send
POST
/api/v3/letters/{letterUuid}/agents/actions/run-preflight
GET
/api/v3/letters/{letterUuid}/agents/runs
POST
/api/v3/curations
POST
/api/v3/curations/bulk
POST
/api/v3/curations/discover
GET
/api/v3/promotions
POST
/api/v3/promotions
GET
/api/v3/promotions/{promotionCollateralUid}
POST
/api/v3/promotions/{promotionCollateralUid}
DELETE
/api/v3/promotions/{promotionCollateralUid}
GET
/api/v3/promotions/promoters
GET
/api/v3/promotions/insights
GET
/api/v3/promotions/actions/by-dates
POST
/api/v3/promotions/actions/refresh-cache
POST
/api/v3/promotions/actions/schedule
GET
/api/v3/promotions/{promotionCollateralUid}/preview
POST
/api/v3/promotions/{promotionCollateralUid}/clones
GET
/api/v3/promotions/{promotionCollateralUid}/metrics/download
GET
/api/v3/promotions/listings
POST
/api/v3/promotions/listings
POST
/api/v3/promotions/listings/{listingUniqueId}
DELETE
/api/v3/promotions/listings/{listingUniqueId}
GET
/api/v3/promotions/purchases
GET
/api/v3/promotions/purchases/{purchaseUniqueId}/preview
POST
/api/v3/promotions/purchases/{purchaseUniqueId}
GET
/api/v3/channels
POST
/api/v3/channels
GET
/api/v3/channels/by-brand
DELETE
/api/v3/channels/{channelSlug}
POST
/api/v3/channels/{channelSlug}/actions/update-slug
POST
/api/v3/channels/{channelSlug}/actions/update-title
GET
/api/v3/channels/{channel}/newsletter-links
GET
/api/v3/channels/{channelSlug}/segments/{segmentId}/recommended-send-time
POST
/api/v3/metrics
POST
/api/v3/metrics/audience
GET
/api/v3/metrics/portfolio-health
GET
/api/v3/metrics/operational-pulse
GET
/api/v3/metrics/active-engagement
POST
/api/v3/metrics/clicks/links
POST
/api/v3/metrics/clicks/topics
POST
/api/v3/metrics/clicks/topic-share
GET
/api/v3/automations
GET
/api/v3/automations/health-summary
POST
/api/v3/automations/{automationUniqueId}/actions/update-status
POST
/api/v3/automations/{automationUniqueId}/actions/trigger
POST
/api/v3/automations/{automationUniqueId}/actions/change-template
POST
/api/v3/automations/{automationUniqueId}/actions/reactivate-and-restart
GET
/api/v3/automations/email-preferences
PUT
/api/v3/automations/email-preferences
POST
/api/v3/transactionals/actions/draft
POST
/api/v3/transactionals/actions/send
GET
/api/v3/teams
GET
/api/v3/agents
POST
/api/v3/agents
GET
/api/v3/agents/{agentUuid}
POST
/api/v3/agents/{agentUuid}
DELETE
/api/v3/agents/{agentUuid}
POST
/api/v3/agents/{agentUuid}/actions/activate
POST
/api/v3/agents/{agentUuid}/actions/deactivate
GET
/api/v3/links

Authentication

Section titled “ Authentication ”

bearerAuth

Section titled “bearerAuth ”

A company-level Letterhead API key, sent as a Bearer token.

Security scheme type: http

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