Aveiro API
Authentication
Sites
List Sites
List Templates
Create Site
Pages
Create a Page
Delete a Page
List Pages
Reorder Pages
Update a Page
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
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
Audience
Newsletter API Overview
Newsletter Campaigns
Social
Social API Overview
Social Accounts
Social Media
Social Posts
TrademarkTrademark
AveiroBlogContact
© Aveiro. All rights reserved.
Built with Aveiro
Audience

Newsletter Campaigns

GET/POST /api/v1/campaigns and GET/PATCH /api/v1/campaigns/{campaignId} — list, create, read, and revise email campaign drafts.
Updated 7d ago
Newsletter API Overview
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 sending, sent, or failed campaigns.

List campaigns

GET /api/v1/campaigns?status=&limit=&offset=
Authorization: Bearer av_live_…
Required scope: newsletter:read

Query parameters

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

Example response

{
  "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"
    }
  ]
}

Create draft

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
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
textContentnoPlain-text fallback; omit to derive from htmlContent on send
styleJsonnoEditor style settings (fonts, brand color) applied to HTML blocks
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.

Update draft

Required scope: newsletter:write
Only campaigns in draft status can be patched. Returns 409 CONFLICT if the campaign is sending, sent, or failed.
Patch accepts any subset of: name, subject, previewText, fromName, fromEmail, replyTo, htmlContent, textContent, styleJson, footerNotice, senderContact, unsubscribeLabel.

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.

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/{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", "count": 45 }]
  },
  "openRate": 0.35,
  "clickRate": 0.0817,
  "unsubscribes": { "total": 2, "reasons": {}, "rate": 0.0017 }
}