DocsIntegrations

REST API

Manage subscribers and campaigns from code. Scoped keys, predictable errors and an OpenAPI 3.1 spec.

A JSON REST API for one newsletter at a time: sync subscribers from your product or CRM, publish campaigns from your CMS, and pull results into your own dashboards. The base URL is:

Text
https://newsletter.sh/api/v1

Authentication

An owner creates keys under Settings → API keys. A key looks like nsh_ followed by 40 characters, belongs to one newsletter, and is shown once: only a hash is stored. Send it as a bearer token:

Check a keyShell
export NSH_KEY="nsh_..."   # from Settings → API keys

curl https://newsletter.sh/api/v1/me \
  -H "Authorization: Bearer $NSH_KEY"
ResponseJSON
{
  "data": {
    "newsletter": { "name": "Field Notes", "slug": "field-notes", "subscribers": 4182, "doubleOptIn": true },
    "key": { "name": "CRM sync", "prefix": "nsh_8fK2aQ1x", "scopes": ["subscribers:read", "subscribers:write"] }
  }
}

A newsletter can have up to 20 active keys. Revoke one at any time; it stops working immediately.

Permissions (scopes)

Give each key only what it needs. The settings page has presets for common jobs.

API scopes
ScopeAllows
subscribers:readLook up and list subscribers and tags
subscribers:writeAdd, update, tag and unsubscribe subscribers
campaigns:readRead campaigns and their results
campaigns:writeCreate, edit and delete draft campaigns
campaigns:sendSend and schedule campaigns
Permission presets
PresetScopes
Full accessAll five
Sign-up form / CRM syncsubscribers:read, subscribers:write
Read only (reporting)subscribers:read, campaigns:read
Publishing (create and send)campaigns:read, campaigns:write, campaigns:send

Endpoints

All API endpoints
EndpointScopeDoes
GET/meany keyThe newsletter and the key's permissions
GET/subscriberssubscribers:readList subscribers (filter by status and tag)
POST/subscriberssubscribers:writeAdd or update one subscriber
POST/subscribers/batchsubscribers:writeAdd or update up to 100 subscribers
GET/subscribers/{email}subscribers:readOne subscriber, with welcome-series progress
PATCH/subscribers/{email}subscribers:writeUpdate name, fields and tags
DELETE/subscribers/{email}subscribers:writeUnsubscribe
GET/tagssubscribers:readTags in use, with counts
GET/campaignscampaigns:readList campaigns, newest first
POST/campaignscampaigns:writeCreate a draft from Markdown
GET/campaigns/{id}campaigns:readA campaign with results and clicks per link
PATCH/campaigns/{id}campaigns:writeEdit a draft or scheduled campaign
DELETE/campaigns/{id}campaigns:writeDelete a draft
POST/campaigns/{id}/sendcampaigns:sendRun the checks, then send (or dry-run)
POST/campaigns/{id}/schedulecampaigns:sendSchedule a draft
DELETE/campaigns/{id}/schedulecampaigns:sendUnschedule (back to draft)

Successful responses wrap the result in data. Timestamps are ISO 8601 strings in UTC. Emails in paths are case-insensitive.

Subscribers

Add or update a subscriber

POST /subscribers creates the reader (201) or merges name, fields and tags into an existing one (200). With double opt-in, the reader gets a confirmation email and the response is 202.

Shell
curl -X POST https://newsletter.sh/api/v1/subscribers \
  -H "Authorization: Bearer $NSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "tags": ["vip"],
    "fields": { "company": "Analytical Engines" },
    "doubleOptIn": false,
    "welcome": true
  }'
  • doubleOptIn and welcome default to the newsletter's settings.
  • Field keys are lowercase letters, digits and _, starting with a letter (up to 30 fields, values up to 200 characters).
  • Someone who unsubscribed can only come back with "doubleOptIn": true, so they confirm it themselves. Bounced, complained and suppressed addresses are refused with 409.

Batch

Shell
curl -X POST https://newsletter.sh/api/v1/subscribers/batch \
  -H "Authorization: Bearer $NSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subscribers":[{"email":"ada@example.com"},{"email":"grace@example.com","tags":["beta"]}]}'

Up to 100 rows per call. The response counts created, updated and failed, with a result for each row, so one bad address doesn't fail the batch.

Update tags and fields

Shell
curl -X PATCH https://newsletter.sh/api/v1/subscribers/ada@example.com \
  -H "Authorization: Bearer $NSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"addTags":["customer"],"removeTags":["trial"],"fields":{"company":"Acme","coupon":null}}'

A null field value removes that field. Send tags instead of addTags/removeTags to replace all tags. Status can't be changed with PATCH; use DELETE to unsubscribe.

List

Shell
curl "https://newsletter.sh/api/v1/subscribers?status=subscribed&tag=vip&limit=100" \
  -H "Authorization: Bearer $NSH_KEY"

Pages hold up to 100 subscribers (50 by default). Pass the response's nextCursor as cursor to get the next page; it is null on the last one. The tag filter is applied within each page, so a page can hold fewer than limit rows while more remain.

Campaigns

Create a draft from Markdown

Shell
curl -X POST https://newsletter.sh/api/v1/campaigns \
  -H "Authorization: Bearer $NSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "This week at Acme",
    "preheader": "Three things we shipped",
    "markdown": "## Hello {{first_name|there}}\n\nWe shipped **three** things.\n\n- Faster search\n- Dark mode\n\n[Read the changelog](https://acme.com/changelog){button}"
  }'

Markdown supports headings, bold, italic, code, links, lists, quotes, --- dividers, images (![alt](https://…)), buttons ([Label](https://…){button}) and merge fields. Add segmentId to send to a segment. Drafts and scheduled campaigns can be edited with PATCH.

Check, then send

Shell
# Dry run: blockers, warnings and recipient count. Nothing is sent.
curl -X POST https://newsletter.sh/api/v1/campaigns/CAMPAIGN_ID/send \
  -H "Authorization: Bearer $NSH_KEY" -H "Content-Type: application/json" \
  -d '{"dryRun":true}'

# Send. Warnings must be acknowledged, just like the Send button.
curl -X POST https://newsletter.sh/api/v1/campaigns/CAMPAIGN_ID/send \
  -H "Authorization: Bearer $NSH_KEY" -H "Content-Type: application/json" \
  -d '{"acknowledgeWarnings":true}'
202 AcceptedJSON
{
  "ok": true,
  "status": "sending",
  "blockers": [],
  "warnings": [],
  "recipients": 4182,
  "warmup": null
}

Blockers return 422 send_blocked; unacknowledged warnings return 409 warnings_not_acknowledged. Both list what to fix.

Schedule

Shell
curl -X POST https://newsletter.sh/api/v1/campaigns/CAMPAIGN_ID/schedule \
  -H "Authorization: Bearer $NSH_KEY" -H "Content-Type: application/json" \
  -d '{"scheduledAt":"2026-12-01T09:00:00Z"}'

Between one minute and one year ahead. DELETE the same path to unschedule. GET /campaigns/{id} returns live results (sent, delivered, opens, clicks, unsubscribes, bounces, complaints and rates) and clicks per link.

Errors

Errors use standard HTTP status codes and a consistent JSON body:

JSON
{
  "error": "insufficient_scope",
  "message": "This key doesn't have the \"subscribers:write\" permission. Create a key that does in Settings → API keys."
}
Error codes
StatusCodes
400invalid_request
401missing_api_key, invalid_api_key
403insufficient_scope, plan_limit (the account's subscriber limit is reached)
404not_found
409suppressed, unsubscribed, not_editable, not_schedulable, warnings_not_acknowledged, …
422invalid_email, invalid_content, invalid_segment, missing_subject, invalid_time, send_blocked
429rate_limited

Rate limits

Each key can make 120 requests in a burst, then 2 per second sustained. A batch call costs one request per 10 rows. Over the limit you get 429 rate_limited; wait a second or two and retry with backoff.

OpenAPI spec

The full API is described in an OpenAPI 3.1 document at /api/v1/openapi.json. Import it into Postman or Insomnia, or generate a typed client in any language. Each operation lists the scope it needs as x-required-scope.

Shell
curl https://newsletter.sh/api/v1/openapi.json -o newsletter-sh-openapi.json

Want to react to events instead of polling? See Webhooks.

newsletter.sh

Newsletters on your own sending account. Invite-only, sent through Amazon SES or the provider you already use.

© 2026 newsletter.sh