Issues API

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

Endpoints

Method	Endpoint	Description
GET	/issues	List all issues
GET	/issues/:id	Get an issue
POST	/issues	Create an issue
PATCH	/issues/:id	Update an issue
DELETE	/issues/:id	Delete an issue
POST	/issues/:id/send_now	Send immediately
POST	/issues/:id/publish	Publish to web

---

List Issues

GET /api/v1/issues

Parameters

Parameter	Type	Description
page	integer	Page number
per_page	integer	Results per page
status	string	Filter: draft, scheduled, sent

Response

{
  "data": [
    {
      "id": 1,
      "subject": "Weekly Tech Digest #42",
      "status": "sent",
      "sent_at": "2025-01-10T09:00:00Z",
      "published_to_web": true,
      "path": "weekly-tech-digest-42",
      "metrics": {
        "total_sent": 1500,
        "opens": 450,
        "clicks": 120,
        "open_rate": 30.0,
        "click_rate": 8.0
      },
      "created_at": "2025-01-09T12:00:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 25
  }
}

---

Get Issue

GET /api/v1/issues/:id

Response

{
  "data": {
    "id": 1,
    "subject": "Weekly Tech Digest #42",
    "pre_headline": "This week in tech...",
    "post_script": "See you next week!",
    "content_markdown": "# This Week in Tech\n\n...",
    "status": "draft",
    "scheduled_for": null,
    "sent_at": null,
    "published_to_web": false,
    "path": "weekly-tech-digest-42",
    "articles": [
      {
        "id": 101,
        "title": "AI Breakthrough...",
        "url": "https://example.com/article",
        "summary": "Researchers announce...",
        "position": 1
      }
    ],
    "metrics": null,
    "created_at": "2025-01-10T12:00:00Z",
    "updated_at": "2025-01-10T12:00:00Z"
  }
}

---

Create Issue

POST /api/v1/issues

Request Body

{
  "subject": "Weekly Newsletter #43",
  "pre_headline": "Welcome to this week's edition",
  "content_markdown": "# Hello Subscribers\n\nHere's what happened this week..."
}

Parameters

Parameter	Type	Required	Description
subject	string	Yes	Email subject line
pre_headline	string	No	Intro text before content
post_script	string	No	Outro text after content
content_markdown	string	No	Full newsletter content in Markdown
scheduled_for	datetime	No	ISO 8601 datetime to schedule send

---

Update Issue

PATCH /api/v1/issues/:id

Request Body

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

---

Delete Issue

DELETE /api/v1/issues/:id

---

Send Issue

Send an issue immediately to all active subscribers:

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

Response

{
  "data": {
    "id": 1,
    "status": "sending",
    "message": "Issue is being sent to 1,500 subscribers"
  }
}

---

Publish to Web

Make an issue publicly viewable on your newsletter archive:

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

Request Body (Optional)

{
  "path": "custom-url-slug"
}

Response

{
  "data": {
    "id": 1,
    "published_to_web": true,
    "path": "custom-url-slug",
    "public_url": "https://your-newsletter.dailydraft.ai/issues/custom-url-slug"
  }
}

---

Issue Status Values

Status	Description
draft	Not yet sent, can be edited
scheduled	Scheduled for future send
approved	Approved and ready to send
sending	Currently being sent
sent	Successfully sent

Error Codes

Code	Description
already_sent	Issue has already been sent
no_subscribers	Newsletter has no active subscribers
sending_disabled	Newsletter is on free tier