List campaigns with optional status filter, create drafts for human review, fetch one campaign with full HTML content, or PATCH to revise before send. Agents cannot edit scheduled, sending, sent, or failed campaigns.
List campaigns
GET /api/v1/campaigns?status=&limit=&offset=
Authorization: Bearer av_live_…
POST /api/v1/campaigns
Authorization: Bearer av_live_…
Content-Type: application/json
{
"name": "July product update",
"subject": "What's new this month",
"fromName": "Aveiro",
"fromEmail": "hello@yourdomain.com",
"previewText": "A short inbox snippet after the subject",
"htmlContent": "<p>Hello — here is the update.</p>",
"siteId": null
}
Required scope:newsletter:write
Body fields
Field
Required
Description
name
yes
Internal campaign name (not shown to recipients, max 200 chars)
subject
yes
Email subject line (max 500 chars)
fromName
yes
Sender display name (max 200 chars)
fromEmail
yes
siteId
no
replyTo
no
Reply-to address; null clears
previewText
no
Inbox preview snippet (max 500 chars)
htmlContent
no
textContent
no
styleJson
no
footerNotice
no
senderContact
no
unsubscribeLabel
no
Sender email address — must match verified domain setup
Site UUID to associate the campaign with; null for org-level
Full HTML body. Reference images with canonical /api/media/… paths from Site media docs — not signed displayUrl values. Share grants are applied at dashboard send time; this API cannot trigger a send.
Plain-text alternative; omit to derive from htmlContent on create and whenever htmlContent changes on PATCH. Supply textContent to keep a custom plain-text version.
Editor style settings applied to HTML blocks: fonts, brand color, maxWidth, bodyAlign (left|center), outerBackground (white|light|dark), containerBorder, hideBranding, imageRadius, buttonRadius
Compliance footer below the unsubscribe link (max 2000 chars)
Physical mailing address or contact info in footer (max 500 chars)
Unsubscribe link label (max 200 chars; defaults to Unsubscribe)
Always creates with status: "draft". Returns 201 with { campaign }.
Get campaign
Required scope:newsletter:read
Returns { campaign } including full htmlContent, textContent, styleJson, and footer fields.
Images in HTML
Reference uploaded images with canonical /api/media/… paths from the Site media API — not signed displayUrl values. Share grants are applied at dashboard send time; this API cannot trigger a send. See https://api.aveiro.app/site-media and https://help.aveiro.app/audience/campaigns#images-in-campaigns.
Update draft
Required scope:newsletter:write
Only campaigns in draft status can be patched. Returns 409 CONFLICT if the campaign is scheduled, sending, sent, or failed.
When htmlContent changes and you omit textContent, Aveiro re-derives the plain-text part from the blocks so the two halves cannot drift after a dashboard edit or agent PATCH. Unchanged htmlContent leaves an existing textContent alone. POST and PATCH also canonicalize media paths in htmlContent the same way the dashboard does.
Campaign analytics
Required scope:newsletter:read
Returns send counts, open/click engagement, top clicked links, and unsubscribe totals — computed the same way as Audience → Campaigns → Stats in the dashboard.
Each topUrls entry is a destination plus the element that was clicked (kind: image, button, link, text, or footer), so an image and a button pointing at the same page are reported separately. Clicks recorded before link-kind tracking existed report as link.
Example response (sent campaign)
For draft campaigns, engagement metrics are zeroed out.
