Newsletters API
API reference for managing newsletters. Create drafts, add content blocks, update status, render previews, and send test emails programmatically.
Manage newsletter issues — create drafts, update metadata, render previews, and send test emails.
List newsletters
GET /api/v1/newsletters
| Parameter | Type | Description |
|---|---|---|
status |
string | Filter: draft, in_progress, ready, sent |
page |
integer | Page number |
per_page |
integer | Items per page (max 100) |
Response:
json
{
"newsletters": [
{
"id": "a1b2c3d4",
"title": "Weekly Update — Jan 6",
"subject_line": "Your weekly update",
"preheader_text": "Q1 kickoff, new starters, and more",
"status": "draft",
"scheduled_date": "2026-01-06",
"template_slug": "clean",
"blocks_count": 4,
"created_at": "2026-01-05T10:30:00Z",
"updated_at": "2026-01-05T14:22:00Z"
}
],
"meta": {"page": 1, "per_page": 20, "total": 12, "total_pages": 1}
}
Create a newsletter
POST /api/v1/newsletters
| Field | Type | Required | Description |
|---|---|---|---|
title |
string | Yes | Newsletter title (displayed in header) |
subject_line |
string | No | Email subject line |
preheader_text |
string | No | Preview text shown in inbox |
template_slug |
string | No | Template slug (defaults to clean) |
scheduled_date |
string | No | Target send date (YYYY-MM-DD) |
Get a newsletter
GET /api/v1/newsletters/:id
Returns the newsletter with its ordered content blocks:
{
"newsletter": {
"id": "a1b2c3d4",
"title": "Weekly Update",
"blocks": [
{
"id": "nb_001",
"position": 1,
"content_block": {
"id": "cb_abc",
"title": "CEO Update",
"block_type": "ceo_update",
"status": "ready"
}
}
]
}
}
Update a newsletter
PATCH /api/v1/newsletters/:id
Send only the fields you want to change. Supports: title, subject_line, preheader_text, status, template_slug, scheduled_date.
Delete a newsletter
DELETE /api/v1/newsletters/:id
Returns 204 No Content.
Preview (render HTML)
GET /api/v1/newsletters/:id/preview
Returns the fully rendered HTML — styled with the selected template, brand colours applied, and email-client compatible:
{"html": "<!DOCTYPE html><html>..."}
Send preview email
POST /api/v1/newsletters/:id/send_preview
Requires send_preview scope. The email must belong to a current team member.
| Field | Type | Required |
|---|---|---|
email |
string | Yes |