API Overview

The Internal Newsletter API is a JSON REST API at /api/v1/. All requests and responses use JSON.

Base URL

https://your-app.com/api/v1

Request format

• Include Content-Type: application/json for POST/PATCH requests
• Include Authorization: Bearer inl_your_key on every request
• All resource IDs in URLs are public IDs (hex strings), not database integers

Response format

Successful responses return JSON with the resource wrapped in a key:

{
  "newsletter": {
    "id": "a1b2c3d4e5f6",
    "title": "Weekly Update",
    "status": "draft",
    ...
  }
}

List endpoints include pagination metadata:

{
  "newsletters": [...],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}

Pagination

List endpoints support these query parameters:

Parameter	Default	Max	Description
page	1	—	Page number
per_page	20	100	Items per page

Error handling

Errors return a JSON object with an error key or errors array:

{"error": "Newsletter not found"}

{"errors": ["Title can't be blank", "Block type is invalid"]}

Status	Meaning
200	Success
201	Created
204	Deleted (no body)
401	Unauthorized — invalid API key
403	Forbidden — missing scope
404	Resource not found
422	Validation error
429	Rate limit exceeded or plan limit reached

Endpoints at a glance

Method	Path	Description
GET	/team	Team info, plan, usage
GET	/newsletters	List newsletters
POST	/newsletters	Create a newsletter
GET	/newsletters/:id	Get newsletter with blocks
PATCH	/newsletters/:id	Update a newsletter
DELETE	/newsletters/:id	Delete a newsletter
GET	/newsletters/:id/preview	Rendered HTML preview
POST	/newsletters/:id/send_preview	Send preview email
POST	/newsletters/:id/blocks	Add block to newsletter
DELETE	/newsletters/:id/blocks/:id	Remove block
PATCH	/newsletters/:id/blocks/reorder	Reorder blocks
GET	/content_blocks	List content blocks
POST	/content_blocks	Create a block
GET	/content_blocks/:id	Get block details
PATCH	/content_blocks/:id	Update a block
DELETE	/content_blocks/:id	Delete a block
POST	/content_blocks/ai_draft	AI-generate a block
GET	/templates	List templates
GET	/templates/:slug	Get template details
GET	/events	List events
GET	/events/:slug	Get event details
POST	/webhooks/ingest	Push external content

See individual endpoint docs for request/response details: - Newsletters - Content Blocks - Newsletter Blocks - Templates - Events - Team - Webhooks