LetterFlight API docs

LetterFlight is API-first: everything the dashboard does — adding subscribers, sending campaigns, reading delivery stats — is a plain HTTPS JSON call.

Don't write the integration yourself. Copy the green block below into your AI coding agent (Cursor, Claude Code, ChatGPT, Copilot…) and it wires LetterFlight into your codebase in about five minutes — auth, subscriber capture on sign-up, and campaign sending, with the curl commands to verify.

Copy this for your AI agent

You are integrating the LetterFlight newsletter API into an existing codebase.

BASE URL: https://letterflight.com/api/v1
AUTH: send the header "Authorization: Bearer <API_KEY>" with every call.
API keys look like sk_... and are created in the LetterFlight dashboard:
https://letterflight.com/dashboard  (a key is shown exactly once when created)

WHAT LETTERFLIGHT IS
A hosted newsletter service with deliverability guardrails that cannot be
turned off. Design around them, do not try to bypass them:
1. Double opt-in: POST /subscribers always creates the address as "pending"
   and emails it a confirmation link. Only "confirmed" subscribers ever
   receive campaigns. There is no API to skip the confirmation email.
2. Every email automatically carries per-recipient List-Unsubscribe headers
   plus RFC 8058 one-click unsubscribe. You never add these yourself.
3. Frequency cap: a subscriber gets at most 5 campaign emails per 24 hours.
   Extra recipients are skipped and counted in the response (skippedFreq).
4. Hard bounces are detected automatically; the address becomes "bounced"
   and is never mailed again.

ENDPOINTS (all JSON)
- GET  /me                               -> {"user":{...},"quota":{used,limit,
                                            remaining}} — account + plan quota usage
- GET  /auth/me                          -> {"user":{...}}  verify the key
- POST /subscribers  {"email","name"?}   -> 201 {"id","email","status":"pending"}
     adding an already pending/confirmed address -> 200 with the existing record;
     re-adding an unsubscribed address reopens it as pending and re-sends the
- GET  /subscribers                      -> {"subscribers":[...],"count":N}
- GET  /subscribers?status=confirmed     -> filter: pending|confirmed|unsubscribed|bounced
- GET  /subscribers?limit=50&offset=0    -> paginate; response adds "total" plus the
     limit/offset you passed (limit caps at 500). Omit for the full list.
- GET  /subscribers/:id                  -> subscriber object, or 404
- DELETE /subscribers/:id                -> {"deleted":1}
- POST /send  {"subject","body","html"?,"mode"?} -> 201 {"campaignId","requested",
                                            "sent","failed","bounced","skippedFreq","mode"}
     body (plain text) is required; html is the optional HTML version.
     mode defaults to "blast" (mails every confirmed subscriber). Use
     mode "test" to send ONE copy to your own account email — it never
     touches subscribers, deliveries or frequency caps. Always preview
     with mode "test" first.
     Put {{unsubscribe_url}} anywhere in body or html; it is replaced per
     recipient with their unique unsubscribe link before sending.
     In HTML campaigns LetterFlight also injects open tracking and rewrites
     links through a redirector — engagement numbers appear on the campaign.
- POST /campaigns {"subject","body","html"?,"scheduled_at"} -> 201 {"campaignId",
                                            "status":"scheduled","scheduled_at"}
     scheduled_at: a FUTURE UTC time "YYYY-MM-DD HH:MM:SS". Nothing is sent
     at creation; the campaign fires when its time passes and then behaves
     exactly like a POST /send blast (same guardrails).
- DELETE /campaigns/:id                  -> {"deleted":1,"status":"cancelled"}
     cancels a scheduled campaign. A sent campaign cannot be cancelled
     (409). A campaign owned by someone else answers 404.
- GET  /campaigns                        -> {"campaigns":[...]} recent sends;
     every row carries "status" (scheduled|sending|sent|failed|cancelled),
     "scheduled_at", "html", plus engagement numbers: "delivered", "opened"
     (unique subscribers), "open_count", "open_rate", "clicked" (unique),
     "click_count", "click_rate" (rates are relative to delivered; null if
     nothing was delivered yet)
- GET  /campaigns/:id                    -> {"campaign":{...},"deliveries":[...]}
     the campaign object carries the same engagement numbers.

TYPICAL INTEGRATIONS
- Sign-up flow: after a user registers in the app, POST /subscribers with
  their email. Set expectations: they must click the confirmation email.
- Regular sending: POST /send with the newsletter content. Only confirmed
  subscribers receive it; the response tells you exactly how many.
- Scheduled sending: POST /campaigns with a future scheduled_at; cancel
  with DELETE /campaigns/:id if plans change before it fires.
- Engagement reporting: poll GET /campaigns after a send and read the
  opened / clicked / *_rate numbers (unique subscribers; rates relative to
  delivered).

TASK
1. Store my API key in an env var (suggest LETTERFLIGHT_API_KEY) and read it
   from there. Never hardcode it.
2. Create one small module that wraps these endpoints with the base URL and
   auth header. No new dependencies beyond what my project already uses.
3. Wire it in at the sensible places: add-to-newsletter on sign-up, and a
   send-newsletter command/function.
4. Print the curl commands I can run to verify the integration end to end.

The 60-second version (for humans)

# 1. verify your key + see your plan quota
curl https://letterflight.com/api/v1/me -H "Authorization: Bearer sk_..."

# 2. add a subscriber (they get a confirmation email; double opt-in is not optional)
curl -X POST https://letterflight.com/api/v1/subscribers \
  -H "Authorization: Bearer sk_..." -H "content-type: application/json" \
  -d '{"email":"reader@example.com","name":"Jane Doe"}'

# 3. send a campaign (only confirmed subscribers receive it)
curl -X POST https://letterflight.com/api/v1/send \
  -H "Authorization: Bearer sk_..." -H "content-type: application/json" \
  -d '{"subject":"Issue #12","body":"Hello reader. Unsubscribe: {{unsubscribe_url}}"}'

# 4. check delivery + engagement counters (opens, clicks, rates)
curl https://letterflight.com/api/v1/campaigns -H "Authorization: Bearer sk_..."

Create your key in the dashboard — it is shown exactly once, and can be revoked there at any time.

Endpoints

Method & pathWhat it doesReturns
GET /meCurrent account + plan quota usage{"user":{...},"quota":{"used","limit","remaining"}}
GET /auth/meVerify the key / current account{"user":{...}}
POST /subscribersAdd subscriber — always pending, confirmation email is sent automatically (double opt-in). Re-adding a pending/confirmed address returns the existing record with 200.201 {"id","email","status"}
GET /subscribersList; optional ?status= filter (pending|confirmed|unsubscribed|bounced) and optional pagination ?limit=&offset= (limit caps at 500; adds total to the response; omit for the full list){"subscribers":[...],"count":N}
GET /subscribers/:idOne subscriberobject / 404
DELETE /subscribers/:idRemove permanently{"deleted":1}
POST /sendCampaign to confirmed subscribers only. body (text) required, html optional. {{unsubscribe_url}} placeholder is replaced per recipient. Optional mode:"test" sends one copy to your own account email instead — never touches subscribers or caps. HTML campaigns get open tracking + link rewriting injected automatically.201 {"campaignId","requested","sent","failed","bounced","skippedFreq","mode"}
POST /campaignsSchedule a campaign — nothing is sent at creation; it fires when scheduled_at (future UTC YYYY-MM-DD HH:MM:SS) passes, with the same guardrails as POST /send.201 {"campaignId","status":"scheduled","scheduled_at"}
DELETE /campaigns/:idCancel a scheduled campaign (a sent one answers 409){"deleted":1,"status":"cancelled"}
GET /campaignsRecent campaigns with counters + lifecycle (status / scheduled_at / html) (last 100), plus engagement: delivered, opened / open_count / open_rate, clicked / click_count / click_rate{"campaigns":[...]}
GET /campaigns/:idOne campaign + per-status delivery counts + the same engagement numbers{"campaign":{...},"deliveries":[...]}

Engagement semantics: opened/clicked count unique subscribers (a subscriber who opens twice still counts once; open_count is the raw total), rates are relative to delivered and are null until something has been delivered. Text-only campaigns (no html) can record clicks but not opens.

Rate limits

SurfaceLimitOn limit
Account registration5 per IP / 10 min429
Public subscribe page POST3 per IP / hour429 page
Early-access leads5 per IP / hour429
Landing funnel beacons (/api/v1/track)60 per IP / minsilently dropped (200)
Email open/click pixels (/t/o, /t/c)300 per IP / minevent dropped, response unchanged
Free tool: email auth check10 per IP / hour429
Authenticated API (Authorization: Bearer sk_…)no hard limit — be reasonable; sending is throttled per subscriber (5 campaign emails / 24h) instead—

Error codes

StatusMeaning
400Invalid input (missing subject, bad email, bad scheduled_at, non-http(s) click-through URL…)
401Missing or invalid key — send Authorization: Bearer sk_… or X-API-Key
402Plan subscriber limit reached (response carries upgrade_url on free)
403Forbidden — email address not verified yet, or the complaint-rate circuit breaker paused sending (response carries the numbers)
404Not found or not yours (ownership is never leaked)
409Conflict — e.g. cancelling an already-sent campaign
413Payload too large (CSV batches: 100 rows / 2 MB default, 5,000 rows / 5 MB attested migration)
422Address previously hard-bounced; re-subscription refused
429Rate limited — slow down (see table above)
500Internal error — retry with backoff
502The confirmation email could not be sent (row stays pending; retry by re-adding the address)

Guardrails your integration must respect

LetterFlight · newsletter hosting that reaches the inbox · every email includes one-click unsubscribe