API Overview

The DailyDraft API is a RESTful API that allows you to programmatically manage your newsletters, issues, and subscribers.

Base URL

All API endpoints are relative to:

https://www.dailydraft.ai/api/v1

API Scope

Each API key is scoped to a single newsletter. When you make requests, you're operating on the newsletter that owns the API key.

Available Resources

Resource	Endpoints	Description
Newsletter	GET, PATCH	View and update newsletter settings, get stats
Issues	GET, POST, PATCH, DELETE	Create, update, delete, send, and publish issues
Subscriptions	GET, POST, PATCH, DELETE	Add, update, remove subscribers, manage tags, bulk import
Webhook Subscriptions	GET, POST, DELETE	Subscribe to real-time event notifications

Complete Endpoint Reference

Method	Endpoint	Description
Newsletter
GET	/newsletter	Get newsletter details
PATCH	/newsletter	Update newsletter settings
GET	/newsletter/stats	Get newsletter statistics
Issues
GET	/issues	List all issues
POST	/issues	Create an issue
GET	/issues/:id	Get an issue
PATCH	/issues/:id	Update an issue
DELETE	/issues/:id	Delete a draft issue
POST	/issues/:id/send_now	Send issue immediately
POST	/issues/:id/publish	Publish issue to web
Subscriptions
GET	/subscribers	List all subscribers
POST	/subscribers	Create a subscriber
GET	/subscribers/:id	Get a subscriber
PATCH	/subscribers/:id	Update a subscriber
DELETE	/subscribers/:id	Remove a subscriber
POST	/subscribers/:id/add_tag	Add a tag to subscriber
DELETE	/subscribers/:id/remove_tag	Remove a tag from subscriber
POST	/subscribers/bulk_create	Bulk import subscribers
Webhook Subscriptions
GET	/webhook_subscriptions	List webhook subscriptions
POST	/webhook_subscriptions	Create a webhook subscription
PATCH	/webhook_subscriptions/:id	Update a webhook subscription
POST	/webhook_subscriptions/:id/rotate_secret	Rotate webhook signing secret
DELETE	/webhook_subscriptions/:id	Delete a webhook subscription

Request Format

Send JSON in request bodies:

Content-Type: application/json

Response Format

Success Response

{
  "data": {
    "id": 123,
    "email": "[email protected]",
    "name": "John Doe",
    "status": "active",
    "created_at": "2025-01-10T12:00:00Z"
  }
}

List Response (Paginated)

{
  "data": [
    { "id": 1, ... },
    { "id": 2, ... }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 25,
    "total_pages": 6
  }
}

Error Response

{
  "error": {
    "code": "validation_error",
    "message": "Email is invalid",
    "details": {
      "email": ["is invalid"]
    }
  }
}

HTTP Methods

Method	Description
GET	Retrieve a resource or list
POST	Create a new resource
PATCH	Update an existing resource
DELETE	Remove a resource

Pagination

List endpoints support pagination:

GET /api/v1/subscribers?page=2&per_page=50

Parameter	Default	Max
page	1	—
per_page	25	100

Filtering

Some endpoints support filtering:

# Get active subscribers
GET /api/v1/subscribers?status=active

# Get subscribers with a specific tag
GET /api/v1/subscribers?tag=vip

Rate Limiting

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704931200

When rate limited, you'll receive a 429 Too Many Requests response.

Versioning

The API version is included in the URL path (/api/v1/). We'll maintain backwards compatibility within a version and announce deprecations in advance.

Next Steps

• Authentication
• Newsletter Endpoints
• Issue Endpoints
• Subscriber Endpoints
• Webhooks
• Error Handling