DEVELOPER GUIDE
Your letters.
Your workflows.
The dashboard, REST API and MCP server use the same 44 actions, validation and account boundaries.
OpenAPI 3.1 · Agent reference · Deploy Littera · Product home · Open Littera
Connect an agent
MCP endpoint: https://littera.genedai.me/mcp. Use OAuth with PKCE, or send Authorization: Bearer lt_… with an API key created in Settings. Read keys cannot mutate data; signup keys can only subscribe readers.
curl 'https://littera.genedai.me/api/v1/newsletters' \ -H 'Authorization: Bearer YOUR_API_KEY'
list_newsletters — List newsletters
GET /api/v1/newsletters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {}
}get_newsletter — Read newsletter settings
GET /api/v1/newsletters/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}create_newsletter — Create newsletter
POST /api/v1/newsletters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 1000
},
"slug": {
"type": "string",
"maxLength": 80,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
},
"fromEmail": {
"type": "string",
"maxLength": 254
},
"replyTo": {
"type": "string",
"maxLength": 254
},
"postalAddress": {
"type": "string",
"maxLength": 1000
},
"authorName": {
"type": "string",
"maxLength": 100
},
"authorBio": {
"type": "string",
"maxLength": 2000
},
"archiveHost": {
"type": "string",
"maxLength": 253
},
"authorLinks": {
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"maxLength": 50
},
"url": {
"type": "string",
"maxLength": 1000,
"format": "uri"
}
},
"required": [
"label",
"url"
]
}
},
"logoUrl": {
"type": "string",
"maxLength": 2000
},
"accent": {
"type": "string",
"maxLength": 10,
"pattern": "^#[a-f0-9]{6}$"
},
"doubleOptIn": {
"type": "boolean"
},
"welcomeEnabled": {
"type": "boolean"
},
"welcomeSubject": {
"type": "string",
"maxLength": 200
},
"welcomeHtml": {
"type": "string",
"maxLength": 90000
},
"cleanupEnabled": {
"type": "boolean"
},
"cleanupIssues": {
"type": "integer",
"minimum": 3,
"maximum": 100
}
},
"required": [
"name"
]
}update_newsletter — Save newsletter settings
PATCH /api/v1/newsletters/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 1000
},
"slug": {
"type": "string",
"maxLength": 80,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
},
"fromEmail": {
"type": "string",
"maxLength": 254
},
"replyTo": {
"type": "string",
"maxLength": 254
},
"postalAddress": {
"type": "string",
"maxLength": 1000
},
"authorName": {
"type": "string",
"maxLength": 100
},
"authorBio": {
"type": "string",
"maxLength": 2000
},
"archiveHost": {
"type": "string",
"maxLength": 253
},
"authorLinks": {
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"maxLength": 50
},
"url": {
"type": "string",
"maxLength": 1000,
"format": "uri"
}
},
"required": [
"label",
"url"
]
}
},
"logoUrl": {
"type": "string",
"maxLength": 2000
},
"accent": {
"type": "string",
"maxLength": 10,
"pattern": "^#[a-f0-9]{6}$"
},
"doubleOptIn": {
"type": "boolean"
},
"welcomeEnabled": {
"type": "boolean"
},
"welcomeSubject": {
"type": "string",
"maxLength": 200
},
"welcomeHtml": {
"type": "string",
"maxLength": 90000
},
"cleanupEnabled": {
"type": "boolean"
},
"cleanupIssues": {
"type": "integer",
"minimum": 3,
"maximum": 100
}
},
"required": [
"id"
]
}check_newsletter_slug — Check newsletter address
GET /api/v1/newsletters/slug
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"slug"
]
}send_welcome_test_email — Preview welcome email in your inbox
POST /api/v1/newsletters/{id}/welcome-test
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}list_contacts — List contacts
GET /api/v1/contacts
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"limit": {
"default": 50,
"type": "integer",
"minimum": 1,
"maximum": 200
},
"cursor": {
"type": "string",
"maxLength": 200
},
"newsletter": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "string",
"enum": [
"active",
"pending",
"dormant",
"unsubscribed",
"bounced",
"complained"
]
},
"search": {
"type": "string",
"maxLength": 200
}
}
}get_contact — Get contact
GET /api/v1/contacts/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"newsletter": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}add_contact — Add or subscribe a contact
POST /api/v1/contacts
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"newsletter": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"email": {
"type": "string",
"minLength": 3,
"maxLength": 254
},
"name": {
"type": "string",
"maxLength": 200
},
"signup": {
"default": false,
"type": "boolean"
},
"resubscribe": {
"default": false,
"type": "boolean"
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"newsletter",
"email"
]
}update_contact_status — Change contact status
PATCH /api/v1/contacts/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "string",
"enum": [
"unsubscribed",
"active"
]
}
},
"required": [
"id",
"status"
]
}delete_contact — Delete contact
DELETE /api/v1/contacts/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}import_contacts — Import a CSV or contact rows
POST /api/v1/contacts/import
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"newsletter": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"csv": {
"type": "string",
"maxLength": 2000000
},
"contacts": {
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"maxLength": 254
},
"name": {
"type": "string",
"maxLength": 200
},
"status": {
"type": "string",
"maxLength": 30
},
"subscribedAt": {
"type": "string",
"maxLength": 200
}
},
"required": [
"email"
]
}
},
"consent": {
"type": "boolean",
"const": true
},
"importId": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"newsletter",
"consent"
]
}export_contacts — Export contacts as CSV
GET /api/v1/contacts/export
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"limit": {
"default": 50,
"type": "integer",
"minimum": 1,
"maximum": 200
},
"cursor": {
"type": "string",
"maxLength": 200
},
"newsletter": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "string",
"maxLength": 20
}
}
}list_campaigns — List campaigns
GET /api/v1/campaigns
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"limit": {
"default": 50,
"type": "integer",
"minimum": 1,
"maximum": 200
},
"cursor": {
"type": "string",
"maxLength": 200
},
"newsletter": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"status": {
"type": "string",
"enum": [
"draft",
"scheduled",
"sending",
"paused",
"sent"
]
}
}
}get_campaign — Read a campaign and its sending checks
GET /api/v1/campaigns/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}get_campaign_report — Read campaign performance
GET /api/v1/campaigns/{id}/report
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}create_campaign — Create a draft letter
POST /api/v1/campaigns
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"newsletter": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"title": {
"type": "string",
"maxLength": 200
},
"subject": {
"type": "string",
"maxLength": 200
},
"preview": {
"type": "string",
"maxLength": 300
},
"html": {
"type": "string",
"maxLength": 95000
},
"markdown": {
"type": "string",
"maxLength": 95000
}
},
"required": [
"newsletter"
]
}update_campaign — Save a draft letter
PATCH /api/v1/campaigns/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"title": {
"type": "string",
"maxLength": 200
},
"subject": {
"type": "string",
"maxLength": 200
},
"preview": {
"type": "string",
"maxLength": 300
},
"html": {
"type": "string",
"maxLength": 95000
},
"markdown": {
"type": "string",
"maxLength": 95000
}
},
"required": [
"id"
]
}delete_campaign — Delete draft letter
DELETE /api/v1/campaigns/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}duplicate_campaign — Duplicate a letter
POST /api/v1/campaigns/{id}/duplicate
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}send_test_email — Send a test to your own inbox
POST /api/v1/campaigns/{id}/test
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}schedule_campaign — Schedule a letter
POST /api/v1/campaigns/{id}/schedule
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"audienceLimit": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"required": [
"id",
"at"
]
}unschedule_campaign — Cancel a scheduled letter
POST /api/v1/campaigns/{id}/unschedule
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}send_campaign — Send a letter now
POST /api/v1/campaigns/{id}/send
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"audienceLimit": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"required": [
"id"
]
}send_campaign_to_more — Send to more readers
POST /api/v1/campaigns/{id}/send-more
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"audienceLimit": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"required": [
"id"
]
}pause_campaign — Pause delivery
POST /api/v1/campaigns/{id}/pause
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}resume_campaign — Resume delivery
POST /api/v1/campaigns/{id}/resume
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}update_campaign_archive — Publish or update an archive page
PATCH /api/v1/campaigns/{id}/archive
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"listed": {
"type": "boolean"
},
"pinned": {
"type": "boolean"
},
"slug": {
"type": "string",
"maxLength": 120,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
}
},
"required": [
"id"
]
}preview_campaign_cleanup — Preview inactive reader cleanup
GET /api/v1/campaigns/{id}/cleanup-preview
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}get_overview — Read delivery and audience analytics
GET /api/v1/overview
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"newsletter": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"days": {
"default": 30,
"type": "integer",
"minimum": 1,
"maximum": 365
}
}
}list_domains — List sender domains
GET /api/v1/domains
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {}
}add_domain — Add a sending domain
POST /api/v1/domains
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"domain": {
"type": "string",
"minLength": 4,
"maxLength": 253
}
},
"required": [
"domain"
]
}check_domain — Check domain verification
POST /api/v1/domains/{id}/check
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}remove_domain — Remove a sender domain
DELETE /api/v1/domains/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}list_api_keys — List API keys
GET /api/v1/api-keys
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {}
}create_api_key — Create an API key
POST /api/v1/api-keys
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"level": {
"default": "full",
"type": "string",
"enum": [
"read",
"full",
"signups"
]
}
},
"required": [
"name"
]
}revoke_api_key — Revoke an API key
DELETE /api/v1/api-keys/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}list_connected_apps — List connected agent applications
GET /api/v1/connected-apps
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {}
}revoke_connected_app — Disconnect an agent application
DELETE /api/v1/connected-apps/{id}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"required": [
"id"
]
}get_billing — Read plan and usage
GET /api/v1/billing
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {}
}change_plan — Change subscription plan
POST /api/v1/billing/change-plan
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"plan": {
"type": "string",
"enum": [
"starter",
"growth",
"pro",
"scale",
"max"
]
},
"interval": {
"default": "month",
"type": "string",
"enum": [
"month",
"year"
]
}
},
"required": [
"plan"
]
}open_billing_portal — Open subscription settings
POST /api/v1/billing/portal
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {}
}list_images — Browse uploaded images
GET /api/v1/images
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"limit": {
"default": 50,
"type": "integer",
"minimum": 1,
"maximum": 200
},
"cursor": {
"type": "string",
"maxLength": 200
}
}
}upload_image — Upload an image to your library
POST /api/v1/images
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"default": "image",
"type": "string",
"maxLength": 100
},
"contentType": {
"type": "string",
"enum": [
"image/png",
"image/jpeg",
"image/gif",
"image/webp"
]
},
"base64": {
"type": "string",
"maxLength": 5600000
},
"url": {
"type": "string",
"maxLength": 2000,
"format": "uri"
}
}
}