Aveiro API
Authentication
Sites
List Sites
List Templates
Create Site
Pages
Create a Page
Delete a Page
List Pages
Reorder Pages
Update a Page
Site Media
Publish Site
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
Social Performance
Website Mockup Video
TrademarkTrademark
Ctrl k
Search…
Sign up
Aveiro API
Authentication
Sites
List Sites
List Templates
Create Site
Pages
Create a Page
Delete a Page
List Pages
Reorder Pages
Update a Page
Site Media
Publish Site
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
Social Performance
Website Mockup Video

Newsletter Campaigns

GET/POST /api/v1/campaigns and GET/PATCH /api/v1/campaigns/{campaignId} — list, create, read, and revise email campaign drafts.
Updated 10d ago
Newsletter API Overview
Sponsored
Aveiro
aveiro.app
Sponsored
Aveiro
aveiro.app
TrademarkTrademark
AveiroBlogContact
© Aveiro. All rights reserved.
Built with Aveiro
In short
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

Required scope: newsletter:read

Query parameters

Param
Description
statusOptional filter: draft, scheduled, sending, sent, failed
limitMax rows (default 50, max 100)
offsetPagination offset (default 0)

Example response

Create draft

Required scope: newsletter:write

Body fields

Field
Required
Description
nameyesInternal campaign name (not shown to recipients, max 200 chars)
subjectyesEmail subject line (max 500 chars)
fromNameyesSender display name (max 200 chars)
fromEmailyesSender email address — must match verified domain setup
siteIdnoSite UUID to associate the campaign with; null for org-level
replyTonoReply-to address; null clears
previewTextnoInbox preview snippet (max 500 chars)
htmlContentnoFull 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.
textContentnoPlain-text alternative; omit to derive from htmlContent on create and whenever htmlContent changes on PATCH. Supply textContent to keep a custom plain-text version.
styleJsonnoEditor style settings applied to HTML blocks: fonts, brand color, maxWidth, bodyAlign (left|center), outerBackground (white|light|dark), containerBorder, hideBranding, imageRadius, buttonRadius
footerNoticenoCompliance footer below the unsubscribe link (max 2000 chars)
senderContactnoPhysical mailing address or contact info in footer (max 500 chars)
unsubscribeLabelnoUnsubscribe 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. Patch accepts any subset of: name, subject, previewText, fromName, fromEmail, replyTo, htmlContent, textContent, styleJson, footerNotice, senderContact, unsubscribeLabel.
Plain-text and HTML writes
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.

Errors

HTTP
Code
When
400VALIDATION_ERRORInvalid body or empty patch
401UNAUTHORIZEDMissing or invalid token
403FORBIDDENToken lacks newsletter:read or newsletter:write
404NOT_FOUNDCampaign or site not found
409CONFLICTCampaign status cannot be edited by agents

Related

  • Newsletter API overview
  • Authentication
  • Platform docs: Audience agents and API
GET /api/v1/campaigns?status=&limit=&offset=
Authorization: Bearer av_live_…
{
  "campaigns": [
    {
      "id": "campaign-uuid",
      "name": "July product update",
      "subject": "What's new this month",
      "status": "draft",
      "siteId": null,
      "scheduledAt": null,
      "sentAt": null,
      "createdAt": "2026-07-30T12:00:00+00:00",
      "updatedAt": "2026-07-30T12:00:00+00:00"
    }
  ]
}
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
}
GET /api/v1/campaigns/{campaignId}
Authorization: Bearer av_live_…
PATCH /api/v1/campaigns/{campaignId}
Authorization: Bearer av_live_…
Content-Type: application/json

{
  "subject": "Revised subject after review",
  "htmlContent": "<p>Updated body copy.</p>"
}
GET /api/v1/campaigns/{campaignId}/analytics
Authorization: Bearer av_live_…
{
  "campaign": {
    "id": "campaign-uuid",
    "name": "July product update",
    "subject": "What's new this month",
    "status": "sent",
    "sentAt": "2026-07-28T10:00:00+00:00"
  },
  "sent": 1200,
  "failed": 3,
  "opens": { "total": 890, "unique": 420 },
  "clicks": {
    "total": 156,
    "unique": 98,
    "topUrls": [
      { "url": "https://example.com/changelog", "kind": "button", "count": 45 },
      { "url": "https://example.com/changelog", "kind": "image", "count": 31 }
    ]
  },
  "openRate": 0.35,
  "clickRate": 0.0817,
  "unsubscribes": { "total": 2, "reasons": {}, "rate": 0.0017 }
}