Issues API

Create, manage, and send newsletter issues via the API.

Endpoints

Method	Endpoint	Description
`GET`	/api/v1/issues	List all issues
`GET`	/api/v1/issues/:id	Get an issue
`POST`	/api/v1/issues	Create an issue
`PATCH`	/api/v1/issues/:id	Update an issue
`DELETE`	/api/v1/issues/:id	Delete an issue
`POST`	/api/v1/issues/:id/send_now	Queue issue for immediate sending
`POST`	/api/v1/issues/:id/publish	Publish to web archive

List Issues

GET /api/v1/issues

Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 25, max: 100)
`status`	string	Filter by status: draft, approved, scheduled, sending, sent

Response

{
  "issues": [
    {
      "id": 1,
      "newsletter_id": 12,
      "subject": "Weekly Tech Digest #42",
      "status": "sent",
      "scheduled_for": null,
      "sent_at": "2025-01-10T09:00:00Z",
      "articles_count": 5,
      "created_at": "2025-01-09T12:00:00Z",
      "updated_at": "2025-01-10T09:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "has_more": false
  }
}

Get Issue

GET /api/v1/issues/:id

Response

{
  "id": 1,
  "newsletter_id": 12,
  "subject": "Weekly Tech Digest #42",
  "status": "draft",
  "scheduled_for": null,
  "sent_at": null,
  "articles_count": 3,
  "content_markdown": "# This Week in Tech\n\n...",
  "articles": [
    {
      "id": 101,
      "title": "AI Breakthrough...",
      "url": "https://example.com/article",
      "position": 1,
      "summarized_article": "Researchers announce..."
    }
  ],
  "created_at": "2025-01-09T12:00:00Z",
  "updated_at": "2025-01-10T08:00:00Z"
}

Create Issue

POST /api/v1/issues

Request Body

{
  "issue": {
    "subject": "Weekly Newsletter #43",
    "content_markdown": "# Hello Subscribers\n\nHere's what happened this week...",
    "status": "draft"
  }
}

Parameters

Parameter	Type	Required	Description
`issue[subject]`	string	Yes	Email subject line
`issue[content_markdown]`	string	No	Full newsletter content in Markdown
`issue[scheduled_for]`	datetime	No	ISO 8601 datetime to schedule send
`issue[status]`	string	No	Defaults to `draft`. Accepted: `draft`, `scheduled`, `approved`.

Response

Returns the created issue object (201 Created).

Update Issue

PATCH /api/v1/issues/:id

Request Body

{
  "issue": {
    "subject": "Updated Subject Line",
    "content_markdown": "# Updated Content\n\n...",
    "status": "approved"
  }
}

Parameters

Parameter	Type	Required	Description
`issue[subject]`	string	No	Email subject line
`issue[content_markdown]`	string	No	Full newsletter content in Markdown
`issue[status]`	string	No	Accepted: `draft`, `scheduled`, `approved`. Passing null leaves the current status unchanged.
`issue[scheduled_for]`	datetime	No	ISO 8601 datetime to schedule send

Note: You can only update issues that haven't been sent yet.

Delete Issue

DELETE /api/v1/issues/:id

Returns 204 No Content on success.

Note: You can only delete draft issues. Sent issues cannot be deleted.

Send Issue

Queue an approved issue for immediate sending to all active subscribers:

POST /api/v1/issues/:id/send_now

Response

{
  "message": "Newsletter queued for sending",
  "issue": {
    "id": 520,
    "newsletter_id": 59,
    "subject": "My Newsletter",
    "status": "approved",
    "scheduled_for": null,
    "sent_at": null,
    "articles_count": 3,
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-10T09:00:00Z"
  },
  "subscribers": 1500
}

Async: Sending is asynchronous. The issue status in this response reflects the current value at queue time (e.g. approved). It transitions to sending then sent as the background job runs.

Requirements (validated before queuing):

Issue must have status approved or scheduled
Newsletter must have at least one active subscriber
Newsletter must be on a paid plan
Issue must have content (content_markdown or articles)

All checks return a 422 with a descriptive error before any background job is queued.

Publish to Web

Make an issue publicly viewable on your newsletter archive:

POST /api/v1/issues/:id/publish

Response

{
  "message": "Issue published to web",
  "issue": {
    "id": 1,
    "newsletter_id": 12,
    "subject": "Weekly Tech Digest #42",
    "status": "sent",
    "scheduled_for": null,
    "sent_at": "2025-01-10T09:00:00Z",
    "articles_count": 5,
    "created_at": "2025-01-09T12:00:00Z",
    "updated_at": "2025-01-10T09:05:00Z"
  },
  "web_url": "https://your-newsletter.dailydraft.ai/p/weekly-tech-digest-42"
}

Issue Status Values

Status	Description
`draft`	Not yet approved, can be edited freely
`scheduled`	Approved and scheduled for a future send time
`approved`	Approved and ready to send via `send_now`
`sending`	Background job is actively dispatching emails
`sent`	All emails dispatched successfully

Error Codes

Code	Description
`402`	Newsletter is not on a paid plan
`422`	Issue is not in `approved` or `scheduled` status, or has no active subscribers

Still need help?

Can't find what you're looking for? Chat with our AI assistant or create a support ticket.