Appearance
email-newsletters
26 endpoints.
GET /api/v1/email-newsletters/groups
List Groups
200 — Successful Response
json
{}GET /api/v1/email-newsletters/customer-groups
List Customer Groups
Always empty on the portal: customer-group live groups read the books, and a portal's books are Lubb's (see email_newsletters_group_sync). Kept so the Compose page shared with Bulk Email gets the shape it expects and simply shows no picker.
200 — Successful Response
json
{}GET /api/v1/email-newsletters/lead-segments
List Lead Segments
Live CRM lead status segments for the "+ Add lead segment" picker.
200 — Successful Response
json
{}POST /api/v1/email-newsletters/groups/live
Create Live Group
Request body
json
{
"properties": {
"title": {
"type": "string",
"title": "Title"
},
"source_type": {
"type": "string",
"title": "Source Type"
},
"source_filter": {
"additionalProperties": true,
"type": "object",
"title": "Source Filter"
}
},
"type": "object",
"required": [
"title",
"source_type"
],
"title": "LiveGroupIn"
}201 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/email-newsletters/groups/{group_id}/sync
Sync Live Group
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
group_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/email-newsletters/smtp
Get Org Smtp
This org's SMTP override (password withheld) — unset fields mean the org falls back to the platform's own SMTP.
200 — Successful Response
json
{}PUT /api/v1/email-newsletters/smtp
Update Org Smtp
Upsert this org's SMTP override, then return the refreshed (masked) view. clear: true removes the override entirely.
Request body
json
{
"properties": {
"host": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "Host"
},
"port": {
"anyOf": [
{
"type": "integer",
"maximum": 65535,
"minimum": 1
},
{
"type": "null"
}
],
"title": "Port"
},
"user": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "User"
},
"password": {
"anyOf": [
{
"type": "string",
"maxLength": 512
},
{
"type": "null"
}
],
"title": "Password"
},
"security": {
"anyOf": [
{
"type": "string",
"pattern": "^(starttls|ssl|none)$"
},
{
"type": "null"
}
],
"title": "Security"
},
"from": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "From"
},
"from_name": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "From Name"
},
"timeout": {
"anyOf": [
{
"type": "number",
"maximum": 300,
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"title": "Timeout"
},
"clear": {
"type": "boolean",
"title": "Clear",
"default": false
}
},
"type": "object",
"title": "OrgSmtpIn",
"description": "Partial update for this org's own SMTP override. A field omitted\n(``None``) is left untouched; an empty string clears just that field."
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/email-newsletters/smtp/test
Test Org Smtp
Live connect + authenticate using this org's currently-saved SMTP override. Sends nothing. Returns {ok, detail}; ok=False with a "not configured" detail when no override is saved (nothing to test — the org is using the platform default).
200 — Successful Response
json
{}POST /api/v1/email-newsletters/campaigns
Create Campaign
Request body
json
{
"properties": {
"subject": {
"type": "string",
"title": "Subject"
},
"sender_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sender Name"
},
"sender_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"title": "Sender Email"
},
"content_type": {
"type": "string",
"title": "Content Type",
"default": "rich_text"
},
"message": {
"type": "string",
"title": "Message",
"default": ""
},
"email_group_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Email Group Ids"
},
"include_tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Include Tags"
},
"exclude_tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Exclude Tags"
},
"send_unsubscribe_link": {
"type": "boolean",
"title": "Send Unsubscribe Link",
"default": true
},
"schedule_send": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Schedule Send"
}
},
"type": "object",
"required": [
"subject"
],
"title": "CampaignIn"
}201 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/email-newsletters/campaigns/{campaign_id}
Get Campaign
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}PATCH /api/v1/email-newsletters/campaigns/{campaign_id}
Update Campaign
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
Request body
json
{
"properties": {
"subject": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Subject"
},
"sender_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sender Name"
},
"sender_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"title": "Sender Email"
},
"content_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content Type"
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Message"
},
"email_group_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Email Group Ids"
},
"include_tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Include Tags"
},
"exclude_tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Exclude Tags"
},
"send_unsubscribe_link": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Send Unsubscribe Link"
},
"schedule_send": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Schedule Send"
},
"clear_schedule": {
"type": "boolean",
"title": "Clear Schedule",
"default": false
}
},
"type": "object",
"title": "CampaignPatch"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/email-newsletters/campaigns/{campaign_id}/attachments
Upload Attachment
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
201 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}DELETE /api/v1/email-newsletters/campaigns/{campaign_id}/attachments/{attachment_id}
Delete Attachment
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string | |
attachment_id | path | yes | string |
204 — Successful Response
422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/email-newsletters/campaigns/{campaign_id}/send-preview
Send Preview
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/email-newsletters/campaigns/{campaign_id}/send-test
Send Test
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
Request body
json
{
"properties": {
"to": {
"type": "string",
"format": "email",
"title": "To"
}
},
"type": "object",
"required": [
"to"
],
"title": "SendTestIn"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/email-newsletters/campaigns/{campaign_id}/send
Send Now
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/email-newsletters/campaigns/{campaign_id}/send-progress
Send Progress
Polled by the Compose page's Send modal while a send is in flight. Uses its own request-scoped session (not the one running the send), so it sees only what email_newsletters_send.send_newsletter has committed so far — which is why that loop commits per-recipient rather than once at the end.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
campaign_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/email-newsletters/unsubscribe/{token}
Unsubscribe
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
200 — Successful Response
422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/email-newsletters/track/open/{token}.png
Track Open
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/email-newsletters/track/click/{link_token}/{rec_token}
Track Click
Click redirect: sent-mail hrefs are rewritten to this URL (see email_newsletters_send.rewrite_click_links). Records the click against both the link and the recipient, then 302s to the real destination. An unknown link token 404s; an unknown recipient token still redirects (the destination matters more than the stats).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
link_token | path | yes | string | |
rec_token | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/email-newsletters/templates
List Templates
200 — Successful Response
json
{}POST /api/v1/email-newsletters/templates
Create Template
Request body
json
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"content_type": {
"type": "string",
"title": "Content Type",
"default": "rich_text"
},
"body": {
"type": "string",
"title": "Body",
"default": ""
},
"design_json": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Design Json"
}
},
"type": "object",
"required": [
"name"
],
"title": "TemplateIn"
}201 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/email-newsletters/templates/{template_id}
Get Template
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
template_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}PUT /api/v1/email-newsletters/templates/{template_id}
Update Template
Update a template in place (the drag-and-drop Template Builder's Save) — unlike POST's upsert-by-name, renames stay on this row.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
template_id | path | yes | string |
Request body
json
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"content_type": {
"type": "string",
"title": "Content Type",
"default": "rich_text"
},
"body": {
"type": "string",
"title": "Body",
"default": ""
},
"design_json": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Design Json"
}
},
"type": "object",
"required": [
"name"
],
"title": "TemplateIn"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/email-newsletters/template-images
Upload Template Image
Store an image for use in a template/campaign body and return its public URL. The URL is absolute (https://<site host>/api/v1/email-newsletters/image/…) because it is embedded in outgoing email, where a relative path is meaningless.
201 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/email-newsletters/image/{token}
Serve Template Image
PUBLIC (no auth): serves an uploaded body image to mail clients.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
token | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}