Newsletter Campaigns
Create campaigns, manage recipients, queue sends, inspect stats, and control suppression lists.
Newsletter API
The Newsletter API exposes campaign lifecycle, recipient synchronization, dispatch queue controls, analytics, and suppression list management.
List Newsletter Campaigns
GET
Required permission
newsletters:readApiAccessPermission::NEWSLETTERS_READQuery Parameters
sizeintegerRecords per page (max 100).
pageintegerPage index (starting from 1).
Responses
Newsletter list returned.
{
"entities": "Newsletter",
"count": 1,
"per_page": 100,
"pages": {
"current": 1,
"max": 1
},
"elements": [
{
"id": "672489...",
"title": "Launch Campaign",
"subject": "New release",
"template_id": "welcome.html",
"total_recipients": 210,
"status": "draft",
"created_at": 1704067200
}
]
}Create Newsletter Campaign
POST
Required permission
newsletters:writeApiAccessPermission::NEWSLETTERS_WRITEQuery Parameters
No query parameters required.
Request Body
{
"newsletter": {
"title": "Launch Campaign",
"subject": "New release",
"template_id": "welcome.html",
"contact_ids": [
"cust_1",
"cust_2"
]
}
}newsletter.titlestringRequiredInternal campaign name.
newsletter.subjectstringRequiredSubject line used during sending.
newsletter.template_idstringRequiredTemplate filename to use for this campaign.
newsletter.contact_idsarrayOptional initial recipients list.
Responses
Newsletter draft created.
{
"id": "672489...",
"status": "draft",
"skipped_suppressed": 0,
"skipped_not_found": 1
}Retrieve Campaign Details
GET
Required permission
newsletters:readApiAccessPermission::NEWSLETTERS_READQuery Parameters
newsletterIdstringRequiredNewsletter identifier.
Responses
Campaign details returned.
{
"id": "672489...",
"title": "Launch Campaign",
"subject": "New release",
"template_id": "welcome.html",
"total_recipients": 210,
"status": "queued",
"scheduled_at": null,
"created_at": 1704067200
}Update Campaign Metadata
PUT
Required permission
newsletters:writeApiAccessPermission::NEWSLETTERS_WRITEQuery Parameters
newsletterIdstringRequiredNewsletter identifier.
Request Body
{
"newsletter": {
"title": "Launch Campaign v2",
"subject": "Release update",
"template_id": "welcome-v2.html"
}
}newsletter.titlestringUpdated title. Allowed only in draft status.
newsletter.subjectstringUpdated subject. Allowed only in draft status.
newsletter.template_idstringUpdated template id. Allowed only in draft status.
Responses
Campaign metadata updated.
{
"id": "672489...",
"title": "Launch Campaign v2",
"subject": "Release update",
"template_id": "welcome-v2.html",
"total_recipients": 210,
"status": "draft",
"scheduled_at": null,
"created_at": 1704067200
}Campaign is not in draft status.
{
"error": "Only newsletters in draft status can be updated"
}Delete Campaign
DELETE
Required permission
newsletters:writeApiAccessPermission::NEWSLETTERS_WRITEQuery Parameters
newsletterIdstringRequiredNewsletter identifier.
Responses
Campaign and related queue entries deleted.
{
"id": "672489...",
"deleted": true
}Get Campaign Recipients Snapshot
GET
Required permission
newsletters:readApiAccessPermission::NEWSLETTERS_READQuery Parameters
newsletterIdstringRequiredNewsletter identifier.
searchstringOptional search filter by customer name or email.
Responses
Recipients snapshot returned.
{
"newsletter_status": "draft",
"selected_ids": [
"cust_1",
"cust_2"
],
"all_customers": [
{
"id": "cust_1",
"name": "Alex Doe",
"email": "alex@example.com",
"tags": [
"beta"
],
"subscription_count": 1,
"has_consent": true,
"is_suppressed": false
}
]
}Set Campaign Recipients
PUT
Required permission
newsletters:writeApiAccessPermission::NEWSLETTERS_WRITEQuery Parameters
newsletterIdstringRequiredNewsletter identifier.
Request Body
{
"newsletter": {
"contact_ids": [
"cust_1",
"cust_2",
"cust_3"
]
}
}newsletter.contact_idsarrayRequiredRecipient customer IDs to store on the campaign.
Responses
Recipients synchronized.
{
"newsletter_id": "672489...",
"saved_recipients": 2,
"skipped_suppressed": 1,
"skipped_not_found": 0
}Queue Campaign Dispatch
POST
Required permission
newsletters:writeApiAccessPermission::NEWSLETTERS_WRITEQuery Parameters
newsletterIdstringRequiredNewsletter identifier.
Responses
Campaign queued for sending.
{
"newsletter_id": "672489...",
"status": "queued",
"queued_recipients": 150,
"skipped_suppressed": 0,
"skipped_not_found": 0
}Invalid state or usage limit reached.
{
"error": "This newsletter is already queued and cannot be queued again"
}Send Test Email
POST
Required permission
newsletters:writeApiAccessPermission::NEWSLETTERS_WRITEQuery Parameters
newsletterIdstringRequiredNewsletter identifier.
Request Body
{
"newsletter": {
"test_email": "qa@example.com"
}
}newsletter.test_emailstringRequiredTarget email for test send.
Responses
Test email sent.
{
"newsletter_id": "672489...",
"test_email": "qa@example.com",
"sent": true
}Get Campaign Stats
GET
Required permission
newsletters:readApiAccessPermission::NEWSLETTERS_READQuery Parameters
newsletterIdstringRequiredNewsletter identifier.
failure_limitintegerMaximum failed/skipped items to include.
Responses
Campaign stats returned.
{
"newsletter": {
"id": "672489...",
"title": "Launch Campaign",
"subject": "New release",
"template_id": "welcome.html",
"total_recipients": 150,
"status": "queued",
"scheduled_at": null,
"created_at": 1704067200
},
"stats": {
"pending": 12,
"processing": 3,
"sent": 120,
"failed": 10,
"skipped": 5,
"total": 150
},
"progress": {
"processed": 135,
"total": 150,
"overall_progress": 90,
"delivery_rate": 80
},
"failures": []
}Suppression List
List Unsubscribes
GET
Required permission
newsletter_unsubscribes:readApiAccessPermission::NEWSLETTER_UNSUBSCRIBES_READQuery Parameters
sizeintegerRecords per page (max 100).
pageintegerPage index.
Responses
Suppression list returned.
{
"entities": "Unsubscribes",
"count": 1,
"per_page": 100,
"pages": {
"current": 1,
"max": 1
},
"elements": [
{
"email": "user@example.com",
"reason": "Manual unsubscribe via API",
"unsubscribed_at": 1704067200
}
]
}Add Unsubscribe
POST
Required permission
newsletter_unsubscribes:writeApiAccessPermission::NEWSLETTER_UNSUBSCRIBES_WRITEQuery Parameters
No query parameters required.
Request Body
{
"unsubscribe": {
"email": "user@example.com",
"reason": "Support request"
}
}unsubscribe.emailstringRequiredEmail to suppress.
unsubscribe.reasonstringOptional reason for audit trail.
Responses
Email added to suppression list.
{
"email": "user@example.com",
"unsubscribed": true
}Resubscribe Email
POST
Required permission
newsletter_unsubscribes:writeApiAccessPermission::NEWSLETTER_UNSUBSCRIBES_WRITEQuery Parameters
No query parameters required.
Request Body
{
"unsubscribe": {
"email": "user@example.com"
}
}unsubscribe.emailstringRequiredEmail to remove from suppression list.
Responses
Email removed from suppression list.
{
"email": "user@example.com",
"resubscribed": true
}Email not found in suppression list.
{
"error": "Email not found in suppression list"
}