Agent-facing REST routes for drafting email campaigns and reading analytics. Requires newsletter:read / newsletter:write — send and schedule stay in the dashboard.
The /api/v1/campaigns routes let agents list campaigns, read full HTML content, draft and revise unsent campaigns, and pull send/open/click metrics. There is no API route to send or schedule — those are dashboard-only.
What this API is for
Use the newsletter API when an automation or AI agent should:
List past campaigns — filter by status (draft, scheduled, sending, sent, failed)
Read campaign content — subject, preview text, HTML body, from line, footer fields
Create and revise draft campaigns — agents never create scheduled or sending campaigns over the API
Read analytics — sends, opens, clicks, top clicked links, unsubscribes (same math as the dashboard stats page)
Typical workflow: agent drafts copy → human reviews in Audience → Campaigns → human sends or schedules from the dashboard.Platform guide: Audience agents and API.
Authentication
Requests require bearer tokens with newsletter:read (GET) or newsletter:write (POST/PATCH):
Authorization: Bearer av_live_…
Create tokens in Organization → API tokens. Granting newsletter:read requires Audience manage; newsletter:write requires Campaign create. See Authentication.There is no scope that grants send or schedule — those actions use the dashboard and the Audience send capability, which neither newsletter scope checks.
Base URL
https://help.aveiro.app/api/v1/campaigns
Replace the host with your own app URL when self-hosting.
Endpoints
Guide
Method
Route
List campaigns
GET
/api/v1/campaigns
Create draft
POST
/api/v1/campaigns
Get campaign
GET
/api/v1/campaigns/{campaignId}
Update draft
PATCH
/api/v1/campaigns/{campaignId}
Campaign analytics
GET
/api/v1/campaigns/{campaignId}/analytics
Campaign statuses
Agents can create campaigns only in draft status. They can edit only draft campaigns. Campaigns in scheduled, sending, sent, or failed return 409 CONFLICT on PATCH — draft a new campaign instead of mutating sent history.
Filter GET /api/v1/campaigns?status=sent to review past sends before drafting a follow-up.
MCP tools
The Aveiro MCP server exposes matching tools (aveiro_newsletter_*) that call these routes. OAuth MCP connections can include newsletter:read and newsletter:write when newsletter drafting is authorized.
