API Reference
Email Marketing API
Developer-authenticated contacts, suppressions, campaigns, automation, AI draft, usage, and unsubscribe endpoints.
SoundSync
Verified endpoints
These endpoints are route-backed in the current platform.
GET
/api/developer/email-marketing/settings
Fetch marketing settings.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- settings.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"settings": {
"type": "object",
"properties": {
"developerId": {
"type": "integer",
"minimum": 1
},
"marketingEnabled": {
"type": "boolean"
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"replyToEmail": {
"type": "string"
},
"defaultFooterCompanyName": {
"type": "string"
},
"defaultFooterAddress": {
"type": "string"
},
"providerEnabled": {
"type": "boolean"
},
"testMode": {
"type": "boolean"
},
"pricePer1000Cents": {
"type": "integer",
"minimum": 0
},
"includedMonthlyEmails": {
"type": "integer"
},
"clickTrackingEnabled": {
"type": "boolean"
},
"emailSettings": {
"type": "object",
"properties": {
"supportEmail": {
"type": "string"
},
"supportEmailPresent": {
"type": "boolean"
},
"brandDomainOwnershipReady": {
"type": "boolean"
},
"customDomain": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"domain": {
"type": "string"
},
"fromLocalPart": {
"type": "string"
},
"senderEmail": {
"type": "string"
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"elasticStatus": {
"type": "string"
},
"elasticVerified": {
"type": "boolean"
},
"unifiedVerified": {
"type": "boolean"
},
"dnsRecords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"record": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"ttl": {
"type": [
"string",
"number"
]
},
"priority": {
"type": [
"number",
"null"
]
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"providerVerification": {
"type": "object",
"properties": {
"resend": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"dnsRecords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"record": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"ttl": {
"type": [
"string",
"number"
]
},
"priority": {
"type": [
"number",
"null"
]
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastError": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"properties": {
"sendingEnabled": {
"type": "boolean"
},
"sendingReady": {
"type": "boolean"
},
"trackingReady": {
"type": "boolean"
},
"trackingCertificateReady": {
"type": "boolean"
},
"certificateExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"elastic": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"dnsRecords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"record": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"ttl": {
"type": [
"string",
"number"
]
},
"priority": {
"type": [
"number",
"null"
]
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastError": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"properties": {
"sendingEnabled": {
"type": "boolean"
},
"sendingReady": {
"type": "boolean"
},
"trackingReady": {
"type": "boolean"
},
"trackingCertificateReady": {
"type": "boolean"
},
"certificateExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"providerReadErrors": {
"type": "object",
"properties": {
"resend": {
"type": "string"
},
"elastic": {
"type": "string"
}
},
"additionalProperties": true
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastError": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"domainStatus": {
"type": [
"string",
"null"
]
},
"marketingDomainStatus": {
"type": [
"string",
"null"
]
},
"senderProfiles": {
"type": "object",
"properties": {
"licensing": {
"type": "object",
"properties": {
"purpose": {
"enum": [
"licensing",
"notifications",
"marketing"
]
},
"label": {
"type": "string"
},
"localPart": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"editable": {
"type": "boolean"
}
},
"additionalProperties": true
},
"notifications": {
"type": "object",
"properties": {
"purpose": {
"enum": [
"licensing",
"notifications",
"marketing"
]
},
"label": {
"type": "string"
},
"localPart": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"editable": {
"type": "boolean"
}
},
"additionalProperties": true
},
"marketing": {
"type": "object",
"properties": {
"purpose": {
"enum": [
"licensing",
"notifications",
"marketing"
]
},
"label": {
"type": "string"
},
"localPart": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"editable": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"customSendingUsable": {
"type": "boolean"
},
"transactionalSendingUsable": {
"type": "boolean"
},
"marketingSendingUsable": {
"type": "boolean"
},
"marketingTrackingUsable": {
"type": "boolean"
},
"trackClicks": {
"type": "boolean"
},
"trackOpens": {
"type": "boolean"
},
"canDisableUnsafeMarketingTracking": {
"type": "boolean"
},
"unifiedDomainVerified": {
"type": "boolean"
},
"providerReadiness": {
"type": "object",
"properties": {
"configured": {
"type": "boolean"
},
"transactional": {
"type": "boolean"
},
"marketing": {
"type": "boolean"
},
"tracking": {
"type": "boolean"
},
"ready": {
"type": "boolean"
}
},
"additionalProperties": true
},
"blockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"transactionalBlockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"marketingBlockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"trackingBlockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"fallbackSender": {
"type": "string"
}
},
"additionalProperties": true
},
"branding": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
PATCH
/api/developer/email-marketing/settings
Update marketing settings.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- marketingEnabled: boolean
- fromName: string
- fromEmail: string
- replyToEmail: string
- defaultFooterCompanyName: string
- Returns
- updated settings.
- Side effects
- Writes marketing settings.
- Notes
- From address must be verified. This account setting does not bypass provider configuration, sender readiness or suppression. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"marketingEnabled": {
"type": "boolean"
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"defaultFooterCompanyName": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"settings": {
"type": "object",
"properties": {
"developerId": {
"type": "integer",
"minimum": 1
},
"marketingEnabled": {
"type": "boolean"
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"replyToEmail": {
"type": "string"
},
"defaultFooterCompanyName": {
"type": "string"
},
"defaultFooterAddress": {
"type": "string"
},
"providerEnabled": {
"type": "boolean"
},
"testMode": {
"type": "boolean"
},
"pricePer1000Cents": {
"type": "integer",
"minimum": 0
},
"includedMonthlyEmails": {
"type": "integer"
},
"clickTrackingEnabled": {
"type": "boolean"
},
"emailSettings": {
"type": "object",
"properties": {
"supportEmail": {
"type": "string"
},
"supportEmailPresent": {
"type": "boolean"
},
"brandDomainOwnershipReady": {
"type": "boolean"
},
"customDomain": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"domain": {
"type": "string"
},
"fromLocalPart": {
"type": "string"
},
"senderEmail": {
"type": "string"
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"elasticStatus": {
"type": "string"
},
"elasticVerified": {
"type": "boolean"
},
"unifiedVerified": {
"type": "boolean"
},
"dnsRecords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"record": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"ttl": {
"type": [
"string",
"number"
]
},
"priority": {
"type": [
"number",
"null"
]
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"providerVerification": {
"type": "object",
"properties": {
"resend": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"dnsRecords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"record": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"ttl": {
"type": [
"string",
"number"
]
},
"priority": {
"type": [
"number",
"null"
]
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastError": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"properties": {
"sendingEnabled": {
"type": "boolean"
},
"sendingReady": {
"type": "boolean"
},
"trackingReady": {
"type": "boolean"
},
"trackingCertificateReady": {
"type": "boolean"
},
"certificateExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"elastic": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"dnsRecords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"record": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"ttl": {
"type": [
"string",
"number"
]
},
"priority": {
"type": [
"number",
"null"
]
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastError": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"properties": {
"sendingEnabled": {
"type": "boolean"
},
"sendingReady": {
"type": "boolean"
},
"trackingReady": {
"type": "boolean"
},
"trackingCertificateReady": {
"type": "boolean"
},
"certificateExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"providerReadErrors": {
"type": "object",
"properties": {
"resend": {
"type": "string"
},
"elastic": {
"type": "string"
}
},
"additionalProperties": true
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastError": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"domainStatus": {
"type": [
"string",
"null"
]
},
"marketingDomainStatus": {
"type": [
"string",
"null"
]
},
"senderProfiles": {
"type": "object",
"properties": {
"licensing": {
"type": "object",
"properties": {
"purpose": {
"enum": [
"licensing",
"notifications",
"marketing"
]
},
"label": {
"type": "string"
},
"localPart": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"editable": {
"type": "boolean"
}
},
"additionalProperties": true
},
"notifications": {
"type": "object",
"properties": {
"purpose": {
"enum": [
"licensing",
"notifications",
"marketing"
]
},
"label": {
"type": "string"
},
"localPart": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"editable": {
"type": "boolean"
}
},
"additionalProperties": true
},
"marketing": {
"type": "object",
"properties": {
"purpose": {
"enum": [
"licensing",
"notifications",
"marketing"
]
},
"label": {
"type": "string"
},
"localPart": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"editable": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"customSendingUsable": {
"type": "boolean"
},
"transactionalSendingUsable": {
"type": "boolean"
},
"marketingSendingUsable": {
"type": "boolean"
},
"marketingTrackingUsable": {
"type": "boolean"
},
"trackClicks": {
"type": "boolean"
},
"trackOpens": {
"type": "boolean"
},
"canDisableUnsafeMarketingTracking": {
"type": "boolean"
},
"unifiedDomainVerified": {
"type": "boolean"
},
"providerReadiness": {
"type": "object",
"properties": {
"configured": {
"type": "boolean"
},
"transactional": {
"type": "boolean"
},
"marketing": {
"type": "boolean"
},
"tracking": {
"type": "boolean"
},
"ready": {
"type": "boolean"
}
},
"additionalProperties": true
},
"blockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"transactionalBlockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"marketingBlockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"trackingBlockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"fallbackSender": {
"type": "string"
}
},
"additionalProperties": true
},
"branding": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
GET
/api/developer/email-marketing/contacts
List marketing contacts.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query status: string
- query source: string
- query productId: integer
- query segmentId: integer
- query filter: string
- Returns
- contacts[].
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "source",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "productId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "segmentId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "filter",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"consent_status": {
"type": "string"
},
"status": {
"type": "string"
},
"source": {
"type": "string"
}
},
"additionalProperties": true
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"pageSize": {
"type": "integer"
},
"canExclude": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/email-marketing/contacts/import/preview
Preview contact import.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- csv: string
- text: string
- importText: string
- rows: array
- contacts: array
- mapping: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- confirmed: boolean
- confirm: boolean
- source: string
- Returns
- preview rows/errors.
- Side effects
- Changes or processes the authorized resource: Preview contact import.
- Notes
- Preview reads the CSV header and mapped rows; use csv/importText/text for header suggestions. It does not import or send. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"csv": {
"type": "string"
},
"text": {
"type": "string"
},
"importText": {
"type": "string"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"source": {
"type": "string"
}
},
"additionalProperties": true
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
}
},
"additionalProperties": true
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"confirmed": {
"type": "boolean"
},
"confirm": {
"type": "boolean"
},
"source": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"headers": {
"type": "array",
"items": {
"type": "string"
}
},
"suggestedMapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"previewRows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"consent_status": {
"type": "string"
},
"status": {
"type": "string"
},
"source": {
"type": "string"
}
},
"additionalProperties": true
}
},
"report": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/email-marketing/contacts/import
Import subscribers.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- csv: string
- text: string
- importText: string
- rows: array
- contacts: array
- mapping: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- confirmed: boolean
- confirm: boolean
- source: string
- Returns
- import result.
- Side effects
- Creates/updates subscribers with consent metadata.
- Notes
- Send confirmed:true (or confirm:true). Confirm that the contacts belong to your customer/audience list. Import activity uses the current audience policy and cannot override an unsubscribe or suppression. Inspect each row error and skipped count. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"csv": {
"type": "string"
},
"text": {
"type": "string"
},
"importText": {
"type": "string"
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"source": {
"type": "string"
}
},
"additionalProperties": true
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
}
},
"additionalProperties": true
}
},
"mapping": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"confirmed": {
"type": "boolean"
},
"confirm": {
"type": "boolean"
},
"source": {
"type": "string"
}
},
"additionalProperties": true,
"anyOf": [
{
"properties": {
"confirmed": {
"const": true
}
},
"required": [
"confirmed"
]
},
{
"properties": {
"confirm": {
"const": true
}
},
"required": [
"confirm"
]
}
]
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"rowsUploaded": {
"type": "integer"
},
"validRows": {
"type": "integer"
},
"imported": {
"type": "integer"
},
"updated": {
"type": "integer"
},
"duplicates": {
"type": "integer"
},
"skippedInvalidEmail": {
"type": "integer"
},
"skippedMissingEmail": {
"type": "integer"
},
"skippedUnsubscribed": {
"type": "integer"
},
"skippedSuppressed": {
"type": "integer"
},
"productAssociationsAdded": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row": {
"type": "integer"
},
"email": {
"type": "string",
"format": "email"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
GET
/api/developer/email-marketing/suppressions
List suppressions.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- Returns
- suppression rows.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"suppressions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"reason": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/email-marketing/campaigns
List campaigns.
- Auth
- Account Bearer JWT
- Scope
- marketing.view and assigned-product campaign/audience access.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query status: string
- query sourceType: string
- Returns
- campaigns[].
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
- Notes
- marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "sourceType",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaigns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"pageSize": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/email-marketing/campaigns
Create campaign draft.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- name: string (required)
- subject: string
- preheader: string
- bodyHtml: string
- bodyText: string
- audienceFilter: object
- fromName: string
- fromEmail: string
- replyToEmail: string
- primaryProductId: integer
- heroImageUrl: string
- ctaLabel: string
- ctaUrl: string
- sourceType: string
- sourceId: string
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- 201 campaign.
- Side effects
- Creates campaign draft.
- Notes
- marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true,
"required": [
"name"
]
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"audience": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
PATCH
/api/developer/email-marketing/campaigns/:campaignId
Update campaign.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- name: string
- subject: string
- preheader: string
- bodyHtml: string
- bodyText: string
- audienceFilter: object
- fromName: string
- fromEmail: string
- replyToEmail: string
- primaryProductId: integer
- heroImageUrl: string
- ctaLabel: string
- ctaUrl: string
- sourceType: string
- sourceId: string
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- updated campaign.
- Side effects
- Updates campaign draft/scheduled campaign when allowed.
- Notes
- Only draft or scheduled content is editable; sent content is not rewritten. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"audience": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 409, 503.
Operation errors: CAMPAIGN_NOT_EDITABLE.
POST
/api/developer/email-marketing/campaigns/:campaignId/test
Send test email.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- email: string
- to: string
- Returns
- test-send result.
- Side effects
- Sends test email when provider configured.
- Notes
- Test routing uses the saved developer support recipient. It is not an arbitrary bulk audience send. The saved sender/footer must be ready. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"to": {
"type": "string",
"format": "email"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"sent": {
"type": "boolean"
},
"provider": {
"type": "string"
},
"transactionId": {
"type": [
"string",
"null"
]
},
"recipientEmail": {
"type": "string",
"format": "email"
},
"recipients": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 409, 503.
Operation errors: MARKETING_PROVIDER_DISABLED, MARKETING_PROVIDER_LOCKED, DEVELOPER_MARKETING_DISABLED, MARKETING_FROM_EMAIL_REQUIRED, MARKETING_BUSINESS_ADDRESS_REQUIRED, MARKETING_BRANDING_REQUIRED, MARKETING_REPLY_TO_REQUIRED, MARKETING_SUBJECT_REQUIRED, MARKETING_CONTENT_REQUIRED, TEST_RECIPIENT_REQUIRED.
POST
/api/developer/email-marketing/campaigns/:campaignId/send-now
Send campaign now.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Returns
- send result.
- Side effects
- Queues/sends campaign.
- Notes
- The route can queue asynchronous work or report a processing batch. HTTP success is not inbox delivery; inspect recipients and reports. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"queued": {
"type": "integer"
},
"processed": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"deferred": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"remainingQueued": {
"type": "integer"
},
"pausedUntil": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"async": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 409, 503.
Operation errors: MARKETING_PROVIDER_DISABLED, MARKETING_PROVIDER_LOCKED, DEVELOPER_MARKETING_DISABLED, MARKETING_FROM_EMAIL_REQUIRED, MARKETING_BUSINESS_ADDRESS_REQUIRED, MARKETING_BRANDING_REQUIRED, MARKETING_REPLY_TO_REQUIRED, MARKETING_SUBJECT_REQUIRED, MARKETING_CONTENT_REQUIRED, CAMPAIGN_SEND_STATE_INVALID, CAMPAIGN_SCHEDULED_NOT_DUE, CAMPAIGN_STATE_CHANGED, MARKETING_AUDIENCE_EMPTY.
POST
/api/developer/email-marketing/campaigns/:campaignId/schedule
Schedule campaign.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- scheduledAt: string (required)
- deliveryTimezone: string
- Returns
- schedule result.
- Side effects
- Schedules campaign.
- Notes
- Use a future date and valid IANA timezone. scheduled_at and timezone aliases are accepted. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"scheduledAt": {
"type": "string"
},
"deliveryTimezone": {
"type": "string"
}
},
"required": [
"scheduledAt"
],
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 409, 503.
Operation errors: MARKETING_PROVIDER_DISABLED, MARKETING_PROVIDER_LOCKED, DEVELOPER_MARKETING_DISABLED, MARKETING_FROM_EMAIL_REQUIRED, MARKETING_BUSINESS_ADDRESS_REQUIRED, MARKETING_BRANDING_REQUIRED, MARKETING_REPLY_TO_REQUIRED, MARKETING_SUBJECT_REQUIRED, MARKETING_CONTENT_REQUIRED, CAMPAIGN_SEND_STATE_INVALID, CAMPAIGN_NOT_SCHEDULABLE, INVALID_SCHEDULED_AT, INVALID_DELIVERY_TIMEZONE.
GET
/api/developer/email-marketing/usage
Fetch email marketing usage.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- usage summary.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"usage": {
"type": "array",
"items": {
"type": "object",
"properties": {
"usage_month": {
"type": "string"
},
"emails_sent_count": {
"type": "integer"
},
"total_cents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
},
"includedMonthlyEmails": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/unsubscribe
Marketing unsubscribe entry route.
- Auth
- Public unsubscribe token/link context.
- Scope
- Use the authentication and resource scope specified for this operation.
- Request fields
- token/query context as implemented
- Returns
- Unsubscribe page/action response.
- Side effects
- May record unsubscribe/suppression when valid.
SoundSync
Campaigns, contacts, reporting, and assistance
Current route and service contracts. Examples below are illustrative; live provider outcomes and client-host testing are separate checks.
GET
/api/developer/marketing/summary
Read marketing home totals and current activity.
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- Returns
- Operation result or scoped records.
- Side effects
- Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"settings": {
"type": "object",
"properties": {
"developerId": {
"type": "integer",
"minimum": 1
},
"marketingEnabled": {
"type": "boolean"
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"replyToEmail": {
"type": "string"
},
"defaultFooterCompanyName": {
"type": "string"
},
"defaultFooterAddress": {
"type": "string"
},
"providerEnabled": {
"type": "boolean"
},
"testMode": {
"type": "boolean"
},
"pricePer1000Cents": {
"type": "integer",
"minimum": 0
},
"includedMonthlyEmails": {
"type": "integer"
},
"clickTrackingEnabled": {
"type": "boolean"
},
"emailSettings": {
"type": "object",
"properties": {
"supportEmail": {
"type": "string"
},
"supportEmailPresent": {
"type": "boolean"
},
"brandDomainOwnershipReady": {
"type": "boolean"
},
"customDomain": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"domain": {
"type": "string"
},
"fromLocalPart": {
"type": "string"
},
"senderEmail": {
"type": "string"
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"elasticStatus": {
"type": "string"
},
"elasticVerified": {
"type": "boolean"
},
"unifiedVerified": {
"type": "boolean"
},
"dnsRecords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"record": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"ttl": {
"type": [
"string",
"number"
]
},
"priority": {
"type": [
"number",
"null"
]
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"providerVerification": {
"type": "object",
"properties": {
"resend": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"dnsRecords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"record": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"ttl": {
"type": [
"string",
"number"
]
},
"priority": {
"type": [
"number",
"null"
]
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastError": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"properties": {
"sendingEnabled": {
"type": "boolean"
},
"sendingReady": {
"type": "boolean"
},
"trackingReady": {
"type": "boolean"
},
"trackingCertificateReady": {
"type": "boolean"
},
"certificateExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"elastic": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"status": {
"type": "string"
},
"verified": {
"type": "boolean"
},
"dnsRecords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string"
},
"record": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"ttl": {
"type": [
"string",
"number"
]
},
"priority": {
"type": [
"number",
"null"
]
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastError": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"properties": {
"sendingEnabled": {
"type": "boolean"
},
"sendingReady": {
"type": "boolean"
},
"trackingReady": {
"type": "boolean"
},
"trackingCertificateReady": {
"type": "boolean"
},
"certificateExpiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"providerReadErrors": {
"type": "object",
"properties": {
"resend": {
"type": "string"
},
"elastic": {
"type": "string"
}
},
"additionalProperties": true
},
"verifiedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastError": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"domainStatus": {
"type": [
"string",
"null"
]
},
"marketingDomainStatus": {
"type": [
"string",
"null"
]
},
"senderProfiles": {
"type": "object",
"properties": {
"licensing": {
"type": "object",
"properties": {
"purpose": {
"enum": [
"licensing",
"notifications",
"marketing"
]
},
"label": {
"type": "string"
},
"localPart": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"editable": {
"type": "boolean"
}
},
"additionalProperties": true
},
"notifications": {
"type": "object",
"properties": {
"purpose": {
"enum": [
"licensing",
"notifications",
"marketing"
]
},
"label": {
"type": "string"
},
"localPart": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"editable": {
"type": "boolean"
}
},
"additionalProperties": true
},
"marketing": {
"type": "object",
"properties": {
"purpose": {
"enum": [
"licensing",
"notifications",
"marketing"
]
},
"label": {
"type": "string"
},
"localPart": {
"type": "string"
},
"fromEmail": {
"type": "string"
},
"editable": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"customSendingUsable": {
"type": "boolean"
},
"transactionalSendingUsable": {
"type": "boolean"
},
"marketingSendingUsable": {
"type": "boolean"
},
"marketingTrackingUsable": {
"type": "boolean"
},
"trackClicks": {
"type": "boolean"
},
"trackOpens": {
"type": "boolean"
},
"canDisableUnsafeMarketingTracking": {
"type": "boolean"
},
"unifiedDomainVerified": {
"type": "boolean"
},
"providerReadiness": {
"type": "object",
"properties": {
"configured": {
"type": "boolean"
},
"transactional": {
"type": "boolean"
},
"marketing": {
"type": "boolean"
},
"tracking": {
"type": "boolean"
},
"ready": {
"type": "boolean"
}
},
"additionalProperties": true
},
"blockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"transactionalBlockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"marketingBlockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"trackingBlockingReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"fallbackSender": {
"type": "string"
}
},
"additionalProperties": true
},
"branding": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"optedInContacts": {
"type": "integer"
},
"activeMarketingContacts": {
"type": "integer"
},
"suppressedContacts": {
"type": "integer"
},
"campaignsTotal": {
"type": "integer"
},
"campaignsSent": {
"type": "integer"
},
"sentThisMonth": {
"type": "integer"
},
"includedMonthlyEmails": {
"type": "integer"
},
"includedRemainingThisMonth": {
"type": "integer"
},
"billableThisMonth": {
"type": "integer"
},
"currentMonthCostCents": {
"type": "integer",
"minimum": 0
},
"audienceTrend": {
"type": "array",
"items": {
"type": "object",
"properties": {
"day": {
"type": "string"
},
"contacts": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"audienceHealth": {
"type": "object",
"properties": {
"totalDeveloperCustomers": {
"type": "integer"
},
"activeMarketingContacts": {
"type": "integer"
},
"pendingContacts": {
"type": "integer"
},
"transactionalOnlyCustomers": {
"type": "integer"
},
"unscopedTransactionalOnlyContacts": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"syncMayBeNeeded": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/marketing/audience/estimate
Estimate eligible recipients before sending.
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- Request fields
- audienceFilter: object
- Returns
- Operation result or scoped records.
- Side effects
- Estimate eligible recipients before sending. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/marketing/contacts/import/demo.csv
Download the contact-import sample.
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- Returns
- CSV sample.
- Side effects
- Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (text/csv)
{
"type": "string",
"format": "binary"
}Documented failures: 400, 500, 503.
GET
/api/developer/marketing/segments
List saved segments.
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- Returns
- Operation result or scoped records.
- Side effects
- Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"segments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"status": {
"type": "string"
},
"estimate": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/marketing/segments
Create a scoped saved segment.
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- Request fields
- name: string (required)
- description: string
- filter: object
- Returns
- Operation result or scoped records.
- Side effects
- Create a scoped saved segment. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
}
},
"required": [
"name"
],
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"segment": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"status": {
"type": "string"
},
"estimate": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
PATCH
/api/developer/marketing/segments/:segmentId
Update a saved segment.
- Auth
- Account Bearer JWT
- Scope
- Effective developer marketing permissions and the assigned product audience; workspace-wide operations require all-products scope.
- Request fields
- name: string
- description: string
- filter: object
- Returns
- Operation result or scoped records.
- Side effects
- Update a saved segment. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"segment": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"status": {
"type": "string"
},
"estimate": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
DELETE
/api/developer/marketing/segments/:segmentId
Remove a saved segment.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Returns
- Operation result or scoped records.
- Side effects
- Remove a saved segment. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"segment": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"status": {
"type": "string"
},
"estimate": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
PATCH
/api/developer/marketing/contacts/bulk-suppress
Suppress a selected audience under all-products permission.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- ids: array
- contactIds: array
- reason: string
- filter: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- scope: string
- expectedTotal: integer
- jobId: string
- Returns
- Operation result or scoped records.
- Side effects
- Suppress a selected audience under all-products permission. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires marketing.manage and all-products scope. Selected IDs and all-matching cleanup use different checks. All-matching requires a current active-contact filter and expectedTotal; continue using the returned jobId until complete. Changed selection fails rather than silently excluding a new audience. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"contactIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"reason": {
"type": "string"
},
"filter": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"scope": {
"type": "string"
},
"expectedTotal": {
"type": "integer"
},
"jobId": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"suppressed": {
"type": "integer"
},
"requested": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"consent_status": {
"type": "string"
},
"status": {
"type": "string"
},
"source": {
"type": "string"
}
},
"additionalProperties": true
}
},
"jobId": {
"type": "string"
},
"advanced": {
"type": "integer"
},
"totalCount": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"cumulativeSuppressed": {
"type": "integer"
},
"cumulativeSkipped": {
"type": "integer"
},
"complete": {
"type": "boolean"
},
"verificationPending": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
PATCH
/api/developer/marketing/contacts/:id/consent
Record a permitted consent change.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- customerId: integer
- email: string
- firstName: string
- lastName: string
- marketingOptIn: boolean
- productId: integer
- orderId: integer
- entitlementId: integer
- serialId: integer
- campaignId: integer
- eventType: string
- consentSource: string
- sourceEventId: string
- occurredAt: string,null
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- Returns
- Operation result or scoped records.
- Side effects
- Record a permitted consent change. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. The path ID is the fallback customer ID. Eligible customer activity is required. This does not override a sticky unsubscribe or suppression. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"customerId": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"marketingOptIn": {
"type": "boolean"
},
"productId": {
"type": "integer",
"minimum": 1
},
"orderId": {
"type": "integer",
"minimum": 1
},
"entitlementId": {
"type": "integer",
"minimum": 1
},
"serialId": {
"type": "integer",
"minimum": 1
},
"campaignId": {
"type": "integer",
"minimum": 1
},
"eventType": {
"type": "string"
},
"consentSource": {
"type": "string"
},
"sourceEventId": {
"type": "string"
},
"occurredAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"contact": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"consent_status": {
"type": "string"
},
"status": {
"type": "string"
},
"source": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
PATCH
/api/developer/marketing/contacts/:id/suppress
Suppress or resolve the selected contact under the permitted workflow.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- reason: string
- Returns
- Operation result or scoped records.
- Side effects
- Suppress or resolve the selected contact under the permitted workflow. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires marketing.manage and all-products scope. Suppression is not deletion of financial records. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"reason": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"contact": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"consent_status": {
"type": "string"
},
"status": {
"type": "string"
},
"source": {
"type": "string"
}
},
"additionalProperties": true
},
"suppressed": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/marketing/scheduled-deals/:dealId/campaign-draft
Prepare a campaign draft from a deal; does not send it.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- name: string
- subject: string
- preheader: string
- bodyHtml: string
- bodyText: string
- audienceFilter: object
- fromName: string
- fromEmail: string
- replyToEmail: string
- primaryProductId: integer
- heroImageUrl: string
- ctaLabel: string
- ctaUrl: string
- sourceType: string
- sourceId: string
- metadata: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- useAi: boolean
- Returns
- Operation result or scoped records.
- Side effects
- Prepare a campaign draft from a deal; does not send it. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Creates a draft, not an approved or sent campaign. AI configuration may fall back to the supported non-AI draft path. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"useAi": {
"type": "boolean"
}
},
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"audience": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"deal": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"imageUrl": {
"type": "string"
},
"url": {
"type": "string"
}
},
"additionalProperties": true
},
"warnings": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"ai": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/marketing/ai/generate-draft
Prepare an AI-assisted campaign draft.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- productId: integer
- dealId: integer
- campaignId: integer
- campaignType: string
- tone: string
- audienceType: string
- desiredLength: string
- instructions: string
- prompt: string
- existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- count: integer
- selectedText: string
- fullDraft: string
- instruction: string
- visualDirection: string
- aspectRatio: string
- Returns
- Operation result or scoped records.
- Side effects
- Prepare an AI-assisted campaign draft. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"dealId": {
"type": "integer",
"minimum": 1
},
"campaignId": {
"type": "integer",
"minimum": 1
},
"campaignType": {
"type": "string"
},
"tone": {
"type": "string"
},
"audienceType": {
"type": "string"
},
"desiredLength": {
"type": "string"
},
"instructions": {
"type": "string"
},
"prompt": {
"type": "string"
},
"existingDraft": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"count": {
"type": "integer"
},
"selectedText": {
"type": "string"
},
"fullDraft": {
"type": "string"
},
"instruction": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"subjectLines": {
"type": "array",
"items": {
"type": "string"
}
},
"previewText": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyMarkdown": {
"type": "string"
},
"ctaText": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"provider": {
"type": "string"
},
"model": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/marketing/ai/generate-subjects
Generate subject suggestions.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- productId: integer
- dealId: integer
- campaignId: integer
- campaignType: string
- tone: string
- audienceType: string
- desiredLength: string
- instructions: string
- prompt: string
- existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- count: integer
- selectedText: string
- fullDraft: string
- instruction: string
- visualDirection: string
- aspectRatio: string
- Returns
- Operation result or scoped records.
- Side effects
- Generate subject suggestions. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"dealId": {
"type": "integer",
"minimum": 1
},
"campaignId": {
"type": "integer",
"minimum": 1
},
"campaignType": {
"type": "string"
},
"tone": {
"type": "string"
},
"audienceType": {
"type": "string"
},
"desiredLength": {
"type": "string"
},
"instructions": {
"type": "string"
},
"prompt": {
"type": "string"
},
"existingDraft": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"count": {
"type": "integer"
},
"selectedText": {
"type": "string"
},
"fullDraft": {
"type": "string"
},
"instruction": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"subjectLines": {
"type": "array",
"items": {
"type": "string"
}
},
"previewTextOptions": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"provider": {
"type": "string"
},
"model": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/marketing/ai/generate-preview-text
Generate preview-text suggestions.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- productId: integer
- dealId: integer
- campaignId: integer
- campaignType: string
- tone: string
- audienceType: string
- desiredLength: string
- instructions: string
- prompt: string
- existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- count: integer
- selectedText: string
- fullDraft: string
- instruction: string
- visualDirection: string
- aspectRatio: string
- Returns
- Operation result or scoped records.
- Side effects
- Generate preview-text suggestions. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"dealId": {
"type": "integer",
"minimum": 1
},
"campaignId": {
"type": "integer",
"minimum": 1
},
"campaignType": {
"type": "string"
},
"tone": {
"type": "string"
},
"audienceType": {
"type": "string"
},
"desiredLength": {
"type": "string"
},
"instructions": {
"type": "string"
},
"prompt": {
"type": "string"
},
"existingDraft": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"count": {
"type": "integer"
},
"selectedText": {
"type": "string"
},
"fullDraft": {
"type": "string"
},
"instruction": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"previewTextOptions": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"provider": {
"type": "string"
},
"model": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/marketing/ai/rewrite
Rewrite supplied draft content.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- productId: integer
- dealId: integer
- campaignId: integer
- campaignType: string
- tone: string
- audienceType: string
- desiredLength: string
- instructions: string
- prompt: string
- existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- count: integer
- selectedText: string
- fullDraft: string
- instruction: string
- visualDirection: string
- aspectRatio: string
- Returns
- Operation result or scoped records.
- Side effects
- Rewrite supplied draft content. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"dealId": {
"type": "integer",
"minimum": 1
},
"campaignId": {
"type": "integer",
"minimum": 1
},
"campaignType": {
"type": "string"
},
"tone": {
"type": "string"
},
"audienceType": {
"type": "string"
},
"desiredLength": {
"type": "string"
},
"instructions": {
"type": "string"
},
"prompt": {
"type": "string"
},
"existingDraft": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"count": {
"type": "integer"
},
"selectedText": {
"type": "string"
},
"fullDraft": {
"type": "string"
},
"instruction": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true,
"anyOf": [
{
"required": [
"selectedText"
]
},
{
"required": [
"fullDraft"
]
}
]
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"rewrittenText": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"provider": {
"type": "string"
},
"model": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/marketing/ai/generate-banner
Request campaign banner assistance.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- productId: integer
- dealId: integer
- campaignId: integer
- campaignType: string
- tone: string
- audienceType: string
- desiredLength: string
- instructions: string
- prompt: string
- existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- count: integer
- selectedText: string
- fullDraft: string
- instruction: string
- visualDirection: string
- aspectRatio: string
- Returns
- Operation result or scoped records.
- Side effects
- Request campaign banner assistance. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"dealId": {
"type": "integer",
"minimum": 1
},
"campaignId": {
"type": "integer",
"minimum": 1
},
"campaignType": {
"type": "string"
},
"tone": {
"type": "string"
},
"audienceType": {
"type": "string"
},
"desiredLength": {
"type": "string"
},
"instructions": {
"type": "string"
},
"prompt": {
"type": "string"
},
"existingDraft": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"count": {
"type": "integer"
},
"selectedText": {
"type": "string"
},
"fullDraft": {
"type": "string"
},
"instruction": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"generatedAssetId": {
"type": "integer",
"minimum": 1
},
"imageUrl": {
"type": "string"
},
"assetUrl": {
"type": "string"
},
"thumbnailUrl": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"fileSize": {
"type": "integer"
},
"format": {
"type": "string"
},
"promptUsed": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/marketing/ai/generate-scheduled-deal-draft
Prepare an AI-assisted deal campaign draft.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- productId: integer
- dealId: integer (required)
- campaignId: integer
- campaignType: string
- tone: string
- audienceType: string
- desiredLength: string
- instructions: string
- prompt: string
- existingDraft: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
- count: integer
- selectedText: string
- fullDraft: string
- instruction: string
- visualDirection: string
- aspectRatio: string
- Returns
- Operation result or scoped records.
- Side effects
- Prepare an AI-assisted deal campaign draft. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Requires enabled AI configuration and authorized product/deal context. Text field shapes describe the requested provider output, not an enforced guarantee; validate generated content before use. Output is a draft or asset to review, never permission to publish/send or a performance guarantee. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"dealId": {
"type": "integer",
"minimum": 1
},
"campaignId": {
"type": "integer",
"minimum": 1
},
"campaignType": {
"type": "string"
},
"tone": {
"type": "string"
},
"audienceType": {
"type": "string"
},
"desiredLength": {
"type": "string"
},
"instructions": {
"type": "string"
},
"prompt": {
"type": "string"
},
"existingDraft": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"count": {
"type": "integer"
},
"selectedText": {
"type": "string"
},
"fullDraft": {
"type": "string"
},
"instruction": {
"type": "string"
},
"visualDirection": {
"type": "string"
},
"aspectRatio": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"dealId"
]
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"subjectLines": {
"type": "array",
"items": {
"type": "string"
}
},
"previewText": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyMarkdown": {
"type": "string"
},
"ctaText": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
GET
/api/developer/marketing/campaigns/:campaignId
Read a campaign and its current state.
- Auth
- Account Bearer JWT
- Scope
- marketing.view and assigned-product campaign/audience access.
- Returns
- Operation result or scoped records.
- Side effects
- Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"audience": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
DELETE
/api/developer/marketing/campaigns/:campaignId
Delete a campaign when its state allows.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Returns
- Operation result or scoped records.
- Side effects
- Delete a campaign when its state allows. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Sending campaigns cannot be deleted. Usage, accounting and suppression records remain; prior unsubscribe links stay valid. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
},
"campaignId": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 409, 503.
Operation errors: CAMPAIGN_NOT_DELETABLE.
POST
/api/developer/marketing/campaigns/:campaignId/duplicate
Duplicate for review with a new schedule.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Returns
- Operation result or scoped records.
- Side effects
- Duplicate for review with a new schedule. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
No request body fields are read by this operation.
HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"audience": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"resolvedFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"totalMatchingContacts": {
"type": "integer"
},
"finalSendableEstimate": {
"type": "integer"
},
"selectedProductOwnerCount": {
"type": [
"integer",
"null"
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"excluded": {
"type": "object",
"properties": {
"noMarketingConsent": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"suppressed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"invalid": {
"type": "integer"
},
"missingEmail": {
"type": "integer"
},
"duplicateEmail": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/marketing/campaigns/:campaignId/preview
Render content without sending to an audience.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Returns
- Operation result or scoped records.
- Side effects
- Render content without sending to an audience. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"html": {
"type": "string"
},
"text": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/marketing/campaigns/:campaignId/resume-send
Resume supported interrupted sending after checking recipient outcomes.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Returns
- Operation result or scoped records.
- Side effects
- Resume supported interrupted sending after checking recipient outcomes. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Resume remaining work, not a new campaign or resend of accepted recipients. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"processed": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"deferred": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"remainingQueued": {
"type": "integer"
},
"pausedUntil": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 409, 503.
Operation errors: CAMPAIGN_NOT_SENDING.
POST
/api/developer/marketing/campaigns/:campaignId/cancel
Cancel supported pending campaign work.
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Returns
- Operation result or scoped records.
- Side effects
- Cancel supported pending campaign work. Review the confirmation and retry requirements before repeating the request.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view + marketing.manage and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 409, 503.
Operation errors: CAMPAIGN_NOT_CANCELABLE.
GET
/api/developer/marketing/campaigns/latest/report
Read the latest campaign report.
- Auth
- Account Bearer JWT
- Scope
- marketing.view and assigned-product campaign/audience access.
- Returns
- Operation result or scoped records.
- Side effects
- Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. Same availability fields and nullable provider totals as the campaign-specific report. Reports are reads, not provider-history sync or resend commands. marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "number"
},
"clickRate": {
"type": "number"
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
GET
/api/developer/marketing/campaigns/:campaignId/recipients
Inspect per-recipient outcomes with query filters.
- Auth
- Account Bearer JWT
- Scope
- marketing.view and assigned-product campaign/audience access.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- query status: string
- Returns
- Operation result or scoped records.
- Side effects
- Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Query and header parameters
[
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "search",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string"
},
"sent_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"skip_reason": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
GET
/api/developer/marketing/campaigns/:campaignId/report
Read campaign delivery, engagement, and attribution context.
- Auth
- Account Bearer JWT
- Scope
- marketing.view and assigned-product campaign/audience access.
- Returns
- Operation result or scoped records.
- Side effects
- Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.
- Notes
- Marketing-view access is required; applicable mutation, contact, consent, and all-products checks remain enforced. AI, preview, and draft creation do not authorize sending. providerStatsStatus separates not_sent, pending, retrying, ready, stale and unavailable. Missing delivered/provider totals are null, not confirmed zeros. stale retains the last usable provider snapshot; unavailable retains recorded events without promising recoverable provider history. Do not resend a campaign to repair reporting. openRate/clickRate are raw ratios; UI availability labels and list-report rate objects must be interpreted separately. marketing.view and assigned-product campaign/audience access. Selected-product access cannot read or act on campaigns covering unassigned products or a workspace-wide audience. Product and deal context sent to AI must be assigned. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "number"
},
"clickRate": {
"type": "number"
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
SoundSync
Full automation reference
SoundSync
Campaign names and retries
Developer marketing automation permission and all-product scope apply. This is not the plugin licensing API.
PATCH
/api/developer/marketing/campaigns/:campaignId/name
Rename a current or sent campaign
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- name: string (required)
- Returns
- Updated campaign; this does not rewrite the sent message.
- Notes
- Rename does not edit a sent message. Requires marketing.manage and all-products scope. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaign": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developerId": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"preheader": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyText": {
"type": "string"
},
"audienceFilter": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all_active",
"owns_products",
"does_not_own_products",
"purchased_between",
"imported",
"saved_segment"
]
},
"productIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
}
},
"purchasedFrom": {
"type": "string"
},
"purchasedTo": {
"type": "string"
},
"segmentId": {
"type": "integer",
"minimum": 1
},
"noOpenDays": {
"type": "integer"
},
"noClickDays": {
"type": "integer"
},
"openedDays": {
"type": "integer"
},
"clickedDays": {
"type": "integer"
},
"sentDays": {
"type": "integer"
},
"minSentCount": {
"type": "integer"
},
"source": {
"type": "string"
},
"lastActivityFrom": {
"type": "string"
},
"lastActivityTo": {
"type": "string"
}
},
"additionalProperties": true
},
"fromName": {
"type": "string"
},
"fromEmail": {
"type": "string",
"format": "email"
},
"replyToEmail": {
"type": "string",
"format": "email"
},
"primaryProductId": {
"type": "integer",
"minimum": 1
},
"heroImageUrl": {
"type": "string"
},
"ctaLabel": {
"type": "string"
},
"ctaUrl": {
"type": "string"
},
"sourceType": {
"type": "string"
},
"sourceId": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"status": {
"type": "string"
},
"audienceEstimateCount": {
"type": "integer"
},
"audienceSnapshotCount": {
"type": "integer"
},
"testSentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"approvedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sendStartedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sentAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"canceledAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failureReason": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"report": {
"type": "object",
"properties": {
"recipients": {
"type": "integer"
},
"queued": {
"type": "integer"
},
"sending": {
"type": "integer"
},
"sent": {
"type": "integer"
},
"skipped": {
"type": "integer"
},
"failed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"opened": {
"type": "integer"
},
"clicked": {
"type": "integer"
},
"uniqueOpened": {
"type": "integer"
},
"uniqueClicked": {
"type": "integer"
},
"delivered": {
"type": [
"integer",
"null"
]
},
"recordedDelivered": {
"type": "integer"
},
"deliverySource": {
"type": "string",
"enum": [
"not_sent",
"provider_channel",
"recorded_receipts",
"unavailable"
]
},
"lastDeliveryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"recordedOpenEvents": {
"type": "integer"
},
"recordedClickEvents": {
"type": "integer"
},
"engagementUnchecked": {
"type": "integer"
},
"engagementDenominator": {
"type": "integer"
},
"providerBounced": {
"type": [
"integer",
"null"
]
},
"providerUnsubscribed": {
"type": [
"integer",
"null"
]
},
"providerComplaints": {
"type": [
"integer",
"null"
]
},
"performanceSource": {
"type": "string",
"enum": [
"elastic_channel",
"recorded_events"
]
},
"providerStatsCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"providerStatsError": {
"type": [
"string",
"null"
]
},
"providerStatsStatus": {
"type": "string",
"enum": [
"not_sent",
"pending",
"retrying",
"ready",
"stale",
"unavailable"
]
},
"attributedOrders": {
"type": "integer"
},
"revenueCents": {
"type": "integer"
},
"openRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickRate": {
"type": "object",
"properties": {
"percent": {
"type": [
"number",
"null"
]
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"clickToOpenRate": {
"type": "number"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"accepted": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"remaining": {
"type": "integer"
},
"percentComplete": {
"type": "number"
}
},
"additionalProperties": true
},
"denominatorSource": {
"type": "string",
"enum": [
"sent",
"delivered"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
GET
/api/developer/marketing/campaigns/:campaignId/retry-summary
Inspect safe and uncertain failures
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Returns
- Current retry summary; inspect it before selecting a scope.
- Notes
- marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaignId": {
"type": "integer",
"minimum": 1
},
"safeCount": {
"type": "integer"
},
"uncertainCount": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 503.
POST
/api/developer/marketing/campaigns/:campaignId/retry-failed
Retry failed recipients only
- Auth
- Account Bearer JWT
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- scope: safe | uncertain
- confirmUncertain: boolean
- Returns
- Retry result; successful recipients are not resent.
- Notes
- scope defaults to safe. uncertain requires confirmUncertain: true and accepts duplicate-delivery risk. Successful recipients remain excluded. marketing.view + marketing.manage and all-products workspace scope. Selected-product teammates cannot perform this workspace-wide operation, including GET retry-summary. Sender readiness, suppressions, provider configuration and send-state checks still apply. On a state conflict, reload the campaign and choose an action allowed by its current state. Readiness errors require correcting the named sender/content/provider condition, not bypassing the guard. Missing reporting is not a reason to resend.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"scope": {
"type": "string",
"enum": [
"safe",
"uncertain"
]
},
"confirmUncertain": {
"type": "boolean"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"campaignId": {
"type": "integer",
"minimum": 1
},
"scope": {
"type": "string"
},
"requeued": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 401, 403, 404, 409, 503.
Operation errors: MARKETING_PROVIDER_DISABLED, MARKETING_PROVIDER_LOCKED, DEVELOPER_MARKETING_DISABLED, MARKETING_FROM_EMAIL_REQUIRED, MARKETING_BUSINESS_ADDRESS_REQUIRED, MARKETING_BRANDING_REQUIRED, MARKETING_REPLY_TO_REQUIRED, MARKETING_SUBJECT_REQUIRED, MARKETING_CONTENT_REQUIRED, CAMPAIGN_RETRY_SCOPE_INVALID, CAMPAIGN_RETRY_CONFIRMATION_REQUIRED, CAMPAIGN_RETRY_STATE_INVALID.
Retry the failed send, not the whole campaign
SoundSync automatically retries eligible failures that happened before provider acceptance, within a bounded retry policy. Retry failed sends handles the remaining safe failures without resending successful recipients.
If a connection fails after the provider may have accepted a message, its outcome needs review. An uncertain-send retry requires a separate confirmation because it can duplicate a message. Provider acceptance is not proof of inbox delivery.
Campaign deletion
DELETE /api/developer/marketing/campaigns/:campaignId rejects active sending. Deletion removes the campaign recipient report but preserves usage/accounting and suppression records; prior unsubscribe links remain valid.
Purchases and marketing preferences
A contact created by purchase-based enrollment is not automatically evidence of affirmative consent. Preserve unsubscribes and suppressions, use the relevant developer audience, and establish the applicable sending permission before queueing a campaign.
SoundSync
Marketing information and choices
Who can read, change and send a campaign
Campaign reads require marketing.view. Creating or editing a campaign, previewing it, duplicating it, sending a test, scheduling, sending now, resuming or canceling requires marketing.manage as well. Product Managers with view-only marketing access can inspect permitted campaigns but cannot send or change them. Both /marketing and /email-marketing API mounts enforce these checks.
Selected-product teammates can access only campaigns whose primary product and complete product-ownership audience are within their assignments. Workspace-wide audiences, negative-ownership audiences and mixed assigned/unassigned campaigns are not exposed through a matching primary product. New scoped campaign audiences are limited to assigned-product owners. AI product and scheduled-deal context must be assigned before generation; a client-supplied product list cannot expand scope.
Workspace sender-setting writes, contact imports and previews, contact-consent changes and segment archival require marketing.manage and all-products scope. Existing automation, growth-flow and bulk-suppression restrictions remain. Permissions do not bypass suppression, sending readiness, approval or provider checks.
Audience health separates customers from imported contacts
The marketing summary exposes pendingContacts separately from activeMarketingContacts. transactionalOnlyCustomers is derived from linked developer-customer records; imported standalone contacts do not reduce that population by simple subtraction. unscopedTransactionalOnlyContacts is a separate contact count. Pending, unsubscribed, suppressed, bounced, complained and invalid records are not interchangeable, and none is permission to send.
Sending readiness is specific to the email purpose
Use transactionalSendingUsable and transactionalBlockingReasons for receipts/licensing notices; use marketingSendingUsable and marketingBlockingReasons for campaigns and Growth Flows. Legacy combined blockingReasons can include the other provider. A transactional-provider problem alone does not prove verified marketing sending is blocked.
marketingTrackingUsable is separate from sending. If tracking TLS is not ready, the service sets trackClicks:false and trackOpens:false. Marketing can proceed without that tracking only when the configured provider supports explicitly disabling it; otherwise sending remains blocked. A local checkbox cannot bypass provider TLS checks. This guide does not enable or change provider configuration.
Full Brand Domain readiness still requires complete DNS, website SSL, email/tracking and identity checks. A usable single sending purpose is not completion of the whole wizard. A tracking certificate must be trusted and unexpired; missing certificate status is not readiness. Email tracking is separate from GA4.
SoundSync
Read providerStatsStatus before interpreting a zero
| Status | What the report knows |
|---|---|
| not_sent | No sends for this report; no provider-history conclusion is implied. |
| pending | No usable provider snapshot yet. Pending sync is not a confirmed zero. |
| retrying | Provider lookup failed without a usable snapshot. Known events remain while sync retries; no completion deadline is promised. |
| ready | A usable provider snapshot is available. providerStatsCheckedAt identifies the observation, not inbox certainty or payout revenue. |
| stale | Last usable provider totals remain after a newer lookup failure. These are last-known values, not current confirmed totals. Inspect providerStatsError. |
| unavailable | Provider channel/history is unavailable without a usable snapshot. History unavailable is not zero delivery/engagement or a promise that future sync can recover it. Recorded events and attributed sales remain. |
Keep partial totals separate from delivery failures
delivered, providerBounced, providerUnsubscribed and providerComplaints can be null. Do not replace null with zero. performanceSource distinguishes elastic_channel from recorded_events; recordedOpenEvents and recordedClickEvents remain independent of a provider snapshot.
Recorded deliveries counts saved, matched delivery receipts when a complete provider total is unavailable; Report details explains coverage. Do not treat that incomplete count as total delivery or add it to the same campaign provider total. Rates use delivered messages when available, otherwise sent messages, never the incomplete receipt count; inspect engagementDenominator and availability. Detail report openRate/clickRate are raw ratios. Campaign list reports use {percent,status} rate objects. The UI can show Pending sync, History unavailable, Not tracked or Awaiting consistent data instead of a percentage.
Unavailable history is not a failed recipient and must not cause a resend. Preserve accepted sends, consent/suppression rules, known events and attributed net sales. Guarded delivery review/retries concern supported recipient states, not missing analytics. Open/click measurements are not proof of inbox placement or permission to send.
SoundSync
Delivery evidence in campaign reports
| Field | Interpretation |
|---|---|
| delivered | Complete provider-channel delivery total when available; null means unavailable, not zero. |
| recordedDelivered | Count of saved, matched individual delivery receipts. This can be incomplete; zero does not prove no delivery. |
| deliverySource: provider_channel | Use the complete provider total for that campaign; do not add its receipt count again. |
| deliverySource: recorded_receipts | Only individually recorded delivery evidence is available; do not present it as the full campaign total. |
| deliverySource: not_sent / unavailable | No sends yet / no usable delivery evidence. Read providerStatsStatus separately for sync availability. |
| lastDeliveryAt | Latest matched receipt timestamp where available, otherwise null. It is not the time of a new provider lookup. |
| performanceSource | elastic_channel or recorded_events describes broader performance data; it is separate from deliverySource. |
Read coverage before comparing campaigns
Campaign reporting uses saved provider snapshots and recorded events. Delivery receipts are matched to the developer, campaign and recipient using provider identifiers and timing; provider acceptance, opens and clicks do not count as delivery receipts.
Recorded deliveries and Report details make incomplete coverage visible. Across campaigns, use provider totals where available and receipt evidence only for campaigns without a complete provider total. Never double-count both sources for one campaign or relabel a partial aggregate as complete.
Open/click rate denominators use complete delivered totals when available, otherwise sent counts. They never use incomplete recordedDelivered counts. Reporting reads do not send emails, fetch provider history or change recipients, consent, usage charges or financial records. Missing history is not a reason to retry delivery.
SoundSync
Campaign action errors: recover without duplicate sends
| Operation / code | Next step |
|---|---|
| send-now: CAMPAIGN_SEND_STATE_INVALID, CAMPAIGN_STATE_CHANGED | Reload the campaign. Only send from a supported current state; do not repeat a completed send. |
| send-now: CAMPAIGN_SCHEDULED_NOT_DUE | Wait for the scheduled time or deliberately change the schedule through supported controls. |
| send-now: MARKETING_AUDIENCE_EMPTY | Review the eligible audience and exclusions. Do not override suppression or unsubscribe choices. |
| test, send-now, schedule, retry-failed: MARKETING_PROVIDER_DISABLED / MARKETING_PROVIDER_LOCKED / DEVELOPER_MARKETING_DISABLED | Resolve the named sending configuration or account readiness condition. These 409 responses do not authorize bypassing a gate. |
| MARKETING_FROM_EMAIL_REQUIRED / MARKETING_REPLY_TO_REQUIRED / MARKETING_BUSINESS_ADDRESS_REQUIRED / MARKETING_BRANDING_REQUIRED | Complete the verified sender, reply-to and required business identity/footer before trying again. |
| MARKETING_SUBJECT_REQUIRED / MARKETING_CONTENT_REQUIRED | Complete the message, preview it and then deliberately retry the intended action. |
| schedule: CAMPAIGN_NOT_SCHEDULABLE; INVALID_SCHEDULED_AT / INVALID_DELIVERY_TIMEZONE | Reload state for a 409 conflict. For a 400 input error, use a future date and a valid IANA timezone. |
| resume-send: CAMPAIGN_NOT_SENDING | Reload progress. Resume is for an existing sending campaign, not a resend command. |
| retry-failed: CAMPAIGN_RETRY_STATE_INVALID | Reload. Retry supports campaigns that started sending, not a new draft or analytics repair. |
| retry-failed: CAMPAIGN_RETRY_SCOPE_INVALID / CAMPAIGN_RETRY_CONFIRMATION_REQUIRED | Use safe or uncertain scope; uncertain requires confirmUncertain:true and accepts duplicate-delivery risk. Both input errors are 400. |
| cancel: CAMPAIGN_NOT_CANCELABLE / delete: CAMPAIGN_NOT_DELETABLE | Reload current state; an active send cannot be erased by deleting its campaign. |
| test: TEST_RECIPIENT_REQUIRED | Save the developer support recipient before testing. This 400 response does not allow arbitrary bulk recipients. |
SoundSync
Campaign access is operation-specific
| Operation | Required workspace access |
|---|---|
| Campaign reads and reports | marketing.view and access to the campaign products/audience. A selected-product teammate cannot use an unassigned or workspace-wide audience. |
| Campaign content, preview, test, schedule and send actions | marketing.view + marketing.manage, with campaign product/audience access. |
| GET retry-summary; POST retry-failed; PATCH campaign name; DELETE campaign | marketing.view + marketing.manage and all-products scope, including the GET retry summary. |
| Sender settings, contact import/consent/suppression writes and segment archival | marketing.view + marketing.manage and all-products scope. |
SoundSync