Newsletters

Newsletter issues (campaigns): write, review, test, send, schedule, pause, report.

GET /newsletters — List newsletters
POST /newsletters — Create a draft
GET /newsletters/{id} — Retrieve a newsletter
PATCH /newsletters/{id} — Update a draft
DELETE /newsletters/{id} — Delete a draft
POST /newsletters/{id}/duplicate — Duplicate
GET /newsletters/{id}/review — Pre-send review
POST /newsletters/{id}/test — Send a test email
POST /newsletters/{id}/send — Send now
POST /newsletters/{id}/schedule — Schedule
POST /newsletters/{id}/unschedule — Unschedule
POST /newsletters/{id}/pause — Pause sending
POST /newsletters/{id}/resume — Resume sending
POST /newsletters/{id}/send-more — Send to the next N
GET /newsletters/{id}/report — Report

get`/newsletters`— List newsletters

Keys: full_access

Query parameters

status	"draft" \| "scheduled" \| "sending" \| "paused" \| "sent" \| "failed" \| "held"
limit	integer	1–100, default 20.
after	uuid	Id of the last item of the previous page (older items).
before	uuid	Id of the first item of the previous page (newer items).

curl -X GET https://api.smartletter.ai/newsletters \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY"

Response 200

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "newsletter",
      "id": "7c3e1a52-0000-4000-8000-000000000001",
      "segment_id": "2d9e4b11-0000-4000-8000-000000000003",
      "topic_id": null,
      "subject": "This week in AI",
      "preheader": "Three tools worth your time",
      "status": "draft",
      "body": {
        "format": "markdown",
        "content": "# Hello\n\nThree tools this week…"
      },
      "audience_limit": null,
      "scheduled_for": null,
      "pause_reason": null,
      "recipient_estimate": null,
      "created_at": "2026-10-17T09:00:00.000Z",
      "updated_at": "2026-10-17T09:00:00.000Z"
    }
  ]
}

post`/newsletters`— Create a draft

Creates a draft from a Markdown or HTML body. The platform adds the footer (unsubscribe link, postal address) when the issue is sent.

Keys: full_access

Body

subjectrequired	string	Subject line.
preheader	string	Preview text shown after the subject.
segment_id	uuid	Newsletter (segment) to send from. Optional when the workspace has a single active newsletter.
topic_id	uuid	Topic of that newsletter; its subscribers receive the issue.
markdown	string	Body in Markdown. Give `markdown` or `html`.
html	string	Body in HTML. The platform footer is added around it.

curl -X POST https://api.smartletter.ai/newsletters \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"This week in AI","preheader":"Three tools worth your time","markdown":"# Hello\n\nThree tools this week…"}'

Response 201

{
  "object": "newsletter",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "segment_id": "2d9e4b11-0000-4000-8000-000000000003",
  "topic_id": null,
  "subject": "This week in AI",
  "preheader": "Three tools worth your time",
  "status": "draft",
  "body": {
    "format": "markdown",
    "content": "# Hello\n\nThree tools this week…"
  },
  "audience_limit": null,
  "scheduled_for": null,
  "pause_reason": null,
  "recipient_estimate": null,
  "created_at": "2026-10-17T09:00:00.000Z",
  "updated_at": "2026-10-17T09:00:00.000Z"
}

get`/newsletters/{id}`— Retrieve a newsletter

Keys: full_access

curl -X GET https://api.smartletter.ai/newsletters/<id> \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY"

Response 200

{
  "object": "newsletter",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "segment_id": "2d9e4b11-0000-4000-8000-000000000003",
  "topic_id": null,
  "subject": "This week in AI",
  "preheader": "Three tools worth your time",
  "status": "draft",
  "body": {
    "format": "markdown",
    "content": "# Hello\n\nThree tools this week…"
  },
  "audience_limit": null,
  "scheduled_for": null,
  "pause_reason": null,
  "recipient_estimate": null,
  "created_at": "2026-10-17T09:00:00.000Z",
  "updated_at": "2026-10-17T09:00:00.000Z"
}

patch`/newsletters/{id}`— Update a draft

Keys: full_access

Body

subject	string
preheader	string
topic_id	uuid
markdown	string
html	string

curl -X PATCH https://api.smartletter.ai/newsletters/<id> \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"This week in AI (updated)"}'

Response 200

{
  "object": "newsletter",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "segment_id": "2d9e4b11-0000-4000-8000-000000000003",
  "topic_id": null,
  "subject": "This week in AI",
  "preheader": "Three tools worth your time",
  "status": "draft",
  "body": {
    "format": "markdown",
    "content": "# Hello\n\nThree tools this week…"
  },
  "audience_limit": null,
  "scheduled_for": null,
  "pause_reason": null,
  "recipient_estimate": null,
  "created_at": "2026-10-17T09:00:00.000Z",
  "updated_at": "2026-10-17T09:00:00.000Z"
}

delete`/newsletters/{id}`— Delete a draft

Only drafts can be deleted. Unschedule a scheduled issue first.

Keys: full_access

curl -X DELETE https://api.smartletter.ai/newsletters/<id> \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY"

Response 200

{
  "object": "newsletter",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "deleted": true
}

post`/newsletters/{id}/duplicate`— Duplicate

Copies subject, preheader, body and targeting into a new draft. Never the sending state or the stats.

Keys: full_access

curl -X POST https://api.smartletter.ai/newsletters/<id>/duplicate \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY"

Response 201

{
  "object": "newsletter",
  "id": "9a0d2f3e-0000-4000-8000-000000000004",
  "segment_id": "2d9e4b11-0000-4000-8000-000000000003",
  "topic_id": null,
  "subject": "This week in AI",
  "preheader": "Three tools worth your time",
  "status": "draft",
  "body": {
    "format": "markdown",
    "content": "# Hello\n\nThree tools this week…"
  },
  "audience_limit": null,
  "scheduled_for": null,
  "pause_reason": null,
  "recipient_estimate": null,
  "created_at": "2026-10-17T09:00:00.000Z",
  "updated_at": "2026-10-17T09:00:00.000Z"
}

get`/newsletters/{id}/review`— Pre-send review

Runs the checks a send runs (subject, unsubscribe link, Gmail clipping at ~102 KB, postal address, sending domain) without sending. Blocking items make send and schedule fail with 422.

Keys: full_access

curl -X GET https://api.smartletter.ai/newsletters/<id>/review \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY"

Response 200

{
  "object": "review",
  "blocking": false,
  "items": [
    {
      "id": "subject",
      "level": "ok"
    },
    {
      "id": "gmail_clip",
      "level": "ok",
      "values": {
        "kb": 18
      }
    }
  ]
}

post`/newsletters/{id}/test`— Send a test email

Sends the issue to the workspace owner only, subject prefixed with [Test]. 10 per hour; counts in the monthly quota.

Keys: full_access

curl -X POST https://api.smartletter.ai/newsletters/<id>/test \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY"

Response 200

{
  "object": "test_email",
  "to": "owner@acme.com"
}

post`/newsletters/{id}/send`— Send now

Locks the rendered issue and starts sending. Warm-up, test batch and automatic pauses apply. audience_limit sends to the N most engaged contacts first. A blocking pre-send item answers 422 presend_blocked with the items in details.

Keys: full_access · accepts Idempotency-Key

Body

audience_limit

integer

Send only to the N most engaged contacts now; the rest can follow with send-more.

curl -X POST https://api.smartletter.ai/newsletters/<id>/send \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audience_limit":500}'

Response 200

{
  "object": "newsletter",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "status": "sending"
}

post`/newsletters/{id}/schedule`— Schedule

Schedules a draft up to one year ahead. Same checks as a send.

Keys: full_access · accepts Idempotency-Key

Body

scheduled_atrequired	datetime	ISO 8601 date, in the future, at most one year ahead.
audience_limit	integer	Send only to the N most engaged contacts now; the rest can follow with send-more.

curl -X POST https://api.smartletter.ai/newsletters/<id>/schedule \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at":"2026-10-20T08:00:00Z"}'

Response 200

{
  "object": "newsletter",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "status": "scheduled",
  "scheduled_for": "2026-10-20T08:00:00.000Z"
}

post`/newsletters/{id}/unschedule`— Unschedule

Keys: full_access

curl -X POST https://api.smartletter.ai/newsletters/<id>/unschedule \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY"

Response 200

{
  "object": "newsletter",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "status": "draft"
}

post`/newsletters/{id}/pause`— Pause sending

Keys: full_access

curl -X POST https://api.smartletter.ai/newsletters/<id>/pause \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY"

Response 200

{
  "object": "newsletter",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "status": "paused"
}

post`/newsletters/{id}/resume`— Resume sending

Resumes a manual pause (or a quota / suspension pause once lifted). A pause for bounces, complaints or a failed test batch needs our team: 409.

Keys: full_access

curl -X POST https://api.smartletter.ai/newsletters/<id>/resume \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY"

Response 200

{
  "object": "newsletter",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "status": "sending"
}

post`/newsletters/{id}/send-more`— Send to the next N

For an issue sent with an audience_limit: sends to the next count most engaged contacts. Nobody gets it twice.

Keys: full_access · accepts Idempotency-Key

Body

countrequired

integer

How many of the next most engaged contacts to add.

curl -X POST https://api.smartletter.ai/newsletters/<id>/send-more \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count":1000}'

Response 200

{
  "object": "newsletter",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "status": "sending"
}

get`/newsletters/{id}/report`— Report

Opens, clicks, bounces, complaints and unsubscribes, sending progress, and results per mailbox provider.

Keys: full_access

curl -X GET https://api.smartletter.ai/newsletters/<id>/report \
  -H "Authorization: Bearer $SMARTLETTER_API_KEY"

Response 200

{
  "object": "report",
  "id": "7c3e1a52-0000-4000-8000-000000000001",
  "status": "sent",
  "totals": {
    "sent": 1200,
    "delivered": 1188,
    "opened": 540,
    "clicked": 96,
    "bounced": 12,
    "complained": 0,
    "unsubscribed": 4
  },
  "rates": {
    "delivery": 0.99,
    "open": 0.4545,
    "click": 0.0808,
    "bounce": 0.01,
    "complaint": 0,
    "unsubscribe": 0.0034
  },
  "progress": {
    "attempted": 1200,
    "recipient_estimate": 1200,
    "audience_limit": null
  },
  "providers": [
    {
      "provider": "gmail",
      "sent": 700,
      "delivered": 698,
      "opened": 330,
      "clicked": 60,
      "bounced": 2,
      "complained": 0
    }
  ]
}

Newsletters

get/newsletters— List newsletters

Query parameters

Response 200

post/newsletters— Create a draft

Body

Response 201

get/newsletters/{id}— Retrieve a newsletter

Response 200

patch/newsletters/{id}— Update a draft

Body

Response 200

delete/newsletters/{id}— Delete a draft

Response 200

post/newsletters/{id}/duplicate— Duplicate

Response 201

get/newsletters/{id}/review— Pre-send review

Response 200

post/newsletters/{id}/test— Send a test email

Response 200

post/newsletters/{id}/send— Send now

Body

Response 200

post/newsletters/{id}/schedule— Schedule

Body

Response 200

post/newsletters/{id}/unschedule— Unschedule

Response 200

post/newsletters/{id}/pause— Pause sending

Response 200

post/newsletters/{id}/resume— Resume sending

Response 200

post/newsletters/{id}/send-more— Send to the next N

Body

Response 200

get/newsletters/{id}/report— Report

Response 200

get`/newsletters`— List newsletters

post`/newsletters`— Create a draft

get`/newsletters/{id}`— Retrieve a newsletter

patch`/newsletters/{id}`— Update a draft

delete`/newsletters/{id}`— Delete a draft

post`/newsletters/{id}/duplicate`— Duplicate

get`/newsletters/{id}/review`— Pre-send review

post`/newsletters/{id}/test`— Send a test email

post`/newsletters/{id}/send`— Send now

post`/newsletters/{id}/schedule`— Schedule

post`/newsletters/{id}/unschedule`— Unschedule

post`/newsletters/{id}/pause`— Pause sending

post`/newsletters/{id}/resume`— Resume sending

post`/newsletters/{id}/send-more`— Send to the next N

get`/newsletters/{id}/report`— Report