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.
/api/developer/email-marketing/settings
Fetch marketing settings.
- Auth
- Account Bearer session token
- 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."
},
"spending": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"monthlyLimitCents": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Null means no developer spending limit, not free sending."
},
"monthStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"monthEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"acceptedQuantity": {
"type": "integer",
"minimum": 0
},
"reservedQuantity": {
"type": "integer",
"minimum": 0
},
"usedCents": {
"type": "integer",
"minimum": 0
},
"committedCents": {
"type": "integer",
"minimum": 0
},
"remainingCents": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"includedQuantity": {
"type": "integer",
"minimum": 0
},
"rateCentsPer1000": {
"type": "integer",
"minimum": 0
},
"nearLimit": {
"type": "boolean"
},
"platformPlanningQuantity": {
"type": "integer",
"minimum": 0
},
"platformCommittedQuantity": {
"type": "integer",
"minimum": 0
},
"platformCapacityWarning": {
"type": "boolean"
},
"platformLimitEnforced": {
"type": "boolean"
},
"platformRemainingQuantity": {
"type": "integer",
"minimum": 0
},
"canManageLimit": {
"type": "boolean"
},
"canReviewPlatformCapacity": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/email-marketing/settings
Update marketing settings.
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- marketingEnabled: boolean
- fromName: string
- fromEmail: string
- replyToEmail: string
- defaultFooterCompanyName: string
- monthlySpendLimitUsd: string,number,null. USD with up to two decimal places. Omit to preserve, clear with an empty string or null for unlimited, or use 0 for included sends only. Changing this field requires account-owner authority.
- Returns
- updated settings.
- Side effects
- Writes marketing settings.
- Notes
- From address must be verified. Requires marketing.manage and all-products scope. Only the account owner or authorized platform owner can set or clear monthlySpendLimitUsd; other authorized teammates may retain their ordinary sender-setting edits without that field. Budgets are optional, unlimited by default, shared by campaigns and Growth Flows, and not a credit against the Full Store minimum. This setting does not bypass billing readiness, 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"
},
"monthlySpendLimitUsd": {
"type": [
"string",
"number",
"null"
],
"description": "USD with up to two decimal places. Omit to preserve, clear with an empty string or null for unlimited, or use 0 for included sends only. Changing this field requires account-owner authority."
}
},
"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."
},
"spending": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"monthlyLimitCents": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Null means no developer spending limit, not free sending."
},
"monthStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"monthEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"acceptedQuantity": {
"type": "integer",
"minimum": 0
},
"reservedQuantity": {
"type": "integer",
"minimum": 0
},
"usedCents": {
"type": "integer",
"minimum": 0
},
"committedCents": {
"type": "integer",
"minimum": 0
},
"remainingCents": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"includedQuantity": {
"type": "integer",
"minimum": 0
},
"rateCentsPer1000": {
"type": "integer",
"minimum": 0
},
"nearLimit": {
"type": "boolean"
},
"platformPlanningQuantity": {
"type": "integer",
"minimum": 0
},
"platformCommittedQuantity": {
"type": "integer",
"minimum": 0
},
"platformCapacityWarning": {
"type": "boolean"
},
"platformLimitEnforced": {
"type": "boolean"
},
"platformRemainingQuantity": {
"type": "integer",
"minimum": 0
},
"canManageLimit": {
"type": "boolean"
},
"canReviewPlatformCapacity": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
Operation errors: MARKETING_SPEND_OWNER_REQUIRED, MARKETING_SPEND_LIMIT_INVALID.
/api/developer/email-marketing/contacts
List marketing contacts.
- Auth
- Account Bearer session token
- 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.
/api/developer/email-marketing/contacts/import/preview
Preview contact import.
- Auth
- Account Bearer session token
- 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.
/api/developer/email-marketing/contacts/import
Import subscribers.
- Auth
- Account Bearer session token
- 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.
/api/developer/email-marketing/suppressions
List suppressions.
- Auth
- Account Bearer session token
- 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.
/api/developer/email-marketing/campaigns
List campaigns.
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before 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": ""
},
{
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"additionalProperties": true
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"pageSize": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
/api/developer/email-marketing/campaigns
Create campaign draft.
- Auth
- Account Bearer session token
- 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
- Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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.
Operation errors: MARKETING_CAMPAIGN_EXCLUSION_INVALID, MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE, MARKETING_CAMPAIGN_SELF_EXCLUSION.
/api/developer/email-marketing/campaigns/:campaignId
Update campaign.
- Auth
- Account Bearer session token
- 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. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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: MARKETING_CAMPAIGN_EXCLUSION_INVALID, MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE, MARKETING_CAMPAIGN_SELF_EXCLUSION, CAMPAIGN_NOT_EDITABLE.
/api/developer/email-marketing/campaigns/:campaignId/test
Send test email.
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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.
/api/developer/email-marketing/campaigns/:campaignId/send-now
Send campaign now.
- Auth
- Account Bearer session token
- 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. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"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, 401, 402, 403, 404, 409, 500, 503.
Operation errors: MARKETING_CAMPAIGN_EXCLUSION_INVALID, MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE, MARKETING_CAMPAIGN_SELF_EXCLUSION, MARKETING_SPEND_LIMIT_REACHED, MARKETING_PLATFORM_LIMIT_REACHED, MARKETING_DELIVERY_UNCONFIRMED, DEVELOPER_COST_PAYMENT_METHOD_REQUIRED, DEVELOPER_COST_BILLING_RESTRICTED, DEVELOPER_COST_BILLING_UNAVAILABLE, DEVELOPER_COST_FUNDING_UNAVAILABLE, 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.
/api/developer/email-marketing/campaigns/:campaignId/schedule
Schedule campaign.
- Auth
- Account Bearer session token
- 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. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 402, 403, 404, 409, 500, 503.
Operation errors: MARKETING_SPEND_LIMIT_REACHED, MARKETING_PLATFORM_LIMIT_REACHED, MARKETING_DELIVERY_UNCONFIRMED, DEVELOPER_COST_PAYMENT_METHOD_REQUIRED, DEVELOPER_COST_BILLING_RESTRICTED, DEVELOPER_COST_BILLING_UNAVAILABLE, DEVELOPER_COST_FUNDING_UNAVAILABLE, 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.
/api/developer/email-marketing/usage
Fetch email marketing usage.
- Auth
- Account Bearer session token
- 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.
- Notes
- Current live usage estimates use one shared allowance per Eastern calendar month, including campaigns and automation. total_cents is a current-policy estimate, not a finalized invoice, historical payment or waiver. Campaign reports allocate overage blocks in actual send order instead of giving each campaign a separate allowance.
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"
},
"costBasis": {
"const": "current_policy_estimate"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/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.
/api/developer/marketing/summary
Read marketing home totals and current activity.
- Auth
- Account Bearer session token
- Scope
- marketing.view in the effective developer workspace; operation-specific audience checks still apply.
- 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."
},
"spending": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"monthlyLimitCents": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Null means no developer spending limit, not free sending."
},
"monthStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"monthEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"acceptedQuantity": {
"type": "integer",
"minimum": 0
},
"reservedQuantity": {
"type": "integer",
"minimum": 0
},
"usedCents": {
"type": "integer",
"minimum": 0
},
"committedCents": {
"type": "integer",
"minimum": 0
},
"remainingCents": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"includedQuantity": {
"type": "integer",
"minimum": 0
},
"rateCentsPer1000": {
"type": "integer",
"minimum": 0
},
"nearLimit": {
"type": "boolean"
},
"platformPlanningQuantity": {
"type": "integer",
"minimum": 0
},
"platformCommittedQuantity": {
"type": "integer",
"minimum": 0
},
"platformCapacityWarning": {
"type": "boolean"
},
"platformLimitEnforced": {
"type": "boolean"
},
"platformRemainingQuantity": {
"type": "integer",
"minimum": 0
},
"canManageLimit": {
"type": "boolean"
},
"canReviewPlatformCapacity": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"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.
/api/developer/marketing/audience/estimate
Estimate eligible recipients before sending.
- Auth
- Account Bearer session token
- Scope
- marketing.view and assigned-product audience/segment access in the effective workspace.
- 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. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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.
Operation errors: MARKETING_CAMPAIGN_EXCLUSION_INVALID, MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE, MARKETING_CAMPAIGN_SELF_EXCLUSION.
/api/developer/marketing/contacts/import/demo.csv
Download the contact-import sample.
- Auth
- Account Bearer session token
- Scope
- marketing.view in the effective developer workspace; operation-specific audience checks still apply.
- 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.
/api/developer/marketing/segments
List saved segments.
- Auth
- Account Bearer session token
- Scope
- marketing.view and assigned-product audience/segment access in the effective workspace.
- 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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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.
/api/developer/marketing/segments
Create a scoped saved segment.
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and assigned-product audience/segment access in the effective workspace.
- 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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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.
/api/developer/marketing/segments/:segmentId
Update a saved segment.
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and assigned-product audience/segment access in the effective workspace.
- 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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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.
/api/developer/marketing/segments/:segmentId
Remove a saved segment.
- Auth
- Account Bearer session token
- 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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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.
/api/developer/marketing/contacts/bulk-suppress
Suppress a selected audience under all-products permission.
- Auth
- Account Bearer session token
- 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.
/api/developer/marketing/contacts/:id/consent
Record a permitted consent change.
- Auth
- Account Bearer session token
- 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.
/api/developer/marketing/contacts/:id/suppress
Suppress or resolve the selected contact under the permitted workflow.
- Auth
- Account Bearer session token
- 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.
/api/developer/marketing/scheduled-deals/:dealId/campaign-draft
Prepare a campaign draft from a deal; does not send it.
- Auth
- Account Bearer session token
- 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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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.
/api/developer/marketing/ai/generate-draft
Prepare an AI-assisted campaign draft.
- Auth
- Account Bearer session token
- 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.
/api/developer/marketing/ai/generate-subjects
Generate subject suggestions.
- Auth
- Account Bearer session token
- 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.
/api/developer/marketing/ai/generate-preview-text
Generate preview-text suggestions.
- Auth
- Account Bearer session token
- 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.
/api/developer/marketing/ai/rewrite
Rewrite supplied draft content.
- Auth
- Account Bearer session token
- 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.
/api/developer/marketing/ai/generate-banner
Request campaign banner assistance.
- Auth
- Account Bearer session token
- 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.
/api/developer/marketing/ai/generate-scheduled-deal-draft
Prepare an AI-assisted deal campaign draft.
- Auth
- Account Bearer session token
- 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.
/api/developer/marketing/campaigns/:campaignId
Read a campaign and its current state.
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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.
/api/developer/marketing/campaigns/:campaignId
Delete a campaign when its state allows.
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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.
/api/developer/marketing/campaigns/:campaignId/duplicate
Duplicate for review with a new schedule.
- Auth
- Account Bearer session token
- 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. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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.
Operation errors: MARKETING_CAMPAIGN_EXCLUSION_INVALID, MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE, MARKETING_CAMPAIGN_SELF_EXCLUSION.
/api/developer/marketing/campaigns/:campaignId/preview
Render content without sending to an audience.
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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.
/api/developer/marketing/campaigns/:campaignId/resume-send
Resume supported interrupted sending after checking recipient outcomes.
- Auth
- Account Bearer session token
- 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. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"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, 401, 402, 403, 404, 409, 500, 503.
Operation errors: MARKETING_CAMPAIGN_EXCLUSION_INVALID, MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE, MARKETING_CAMPAIGN_SELF_EXCLUSION, MARKETING_SPEND_LIMIT_REACHED, MARKETING_PLATFORM_LIMIT_REACHED, MARKETING_DELIVERY_UNCONFIRMED, DEVELOPER_COST_PAYMENT_METHOD_REQUIRED, DEVELOPER_COST_BILLING_RESTRICTED, DEVELOPER_COST_BILLING_UNAVAILABLE, DEVELOPER_COST_FUNDING_UNAVAILABLE, CAMPAIGN_NOT_SENDING.
/api/developer/marketing/campaigns/:campaignId/cancel
Cancel supported pending campaign work.
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 409, 503.
Operation errors: CAMPAIGN_NOT_CANCELABLE.
/api/developer/marketing/campaigns/latest/report
Read the latest campaign report.
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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.
/api/developer/marketing/campaigns/:campaignId/recipients
Inspect per-recipient outcomes with query filters.
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before 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": ""
},
{
"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.
/api/developer/marketing/campaigns/:campaignId/report
Read campaign delivery, engagement, and attribution context.
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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.
/api/developer/marketing/campaigns/:campaignId/name
Rename a current or sent campaign
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
/api/developer/marketing/campaigns/:campaignId/retry-summary
Inspect safe and uncertain failures
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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.
/api/developer/marketing/campaigns/:campaignId/retry-failed
Retry failed recipients only
- Auth
- Account Bearer session token
- 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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. |
A cart button is campaign content
Custom cart link builds a configured storefront /cart URL with ss_cart product IDs. Copy link is a clipboard action; Add cart button to email adds an ordinary editable button block to the current campaign content.
Use the existing campaign save, preview, test and send operations. Creating a URL does not create a payment, send email, grant access or bypass audience checks. Storefront checkout verifies the current product offer when the customer proceeds.
SoundSync
Build and test the email button
Campaign and cart-link guide
Copy or insert the link and verify the actual destination before sending.
SoundSync
Product ownership matching
| Choice | Selection |
|---|---|
| productMatch:any | Matches customers owning at least one selected product. |
| productMatch:all | Matches customers owning every selected product. |
| Does not own | Uses the corresponding inverse ownership test; review the audience estimate with the same product set and match mode. |
| Before sending | An estimate is not a fixed recipient entitlement. Eligibility and suppression are checked again for delivery. |
Duplicate a campaign without sending it twice
Duplicating a campaign keeps its earlier campaign links. The Already sent the original campaign control excludes recipients whose earlier delivery was accepted, is still queued or sending, or has an uncertain outcome. A confirmed failure before provider acceptance can remain eligible. The audience estimate, send snapshot and delivery worker apply the exclusion.
A known customer relationship stays linked to its earlier delivery history even when its contact email is corrected. Matching stays inside the same developer workspace. Email-only contacts still use their recorded addresses; names are never used to guess that two contacts are the same person.
Review the linked campaigns before sending. You can deliberately turn the exclusion off in the duplicate; saved unsubscribes, complaints, hard bounces and other restrictions still apply. Editing the control refreshes the audience estimate. Duplicating a campaign does not itself send mail.
Campaign-history exclusion input
audienceFilter.excludeCampaignIds accepts at most 50 positive campaign IDs from the same workspace. The filter also accepts the exclude_campaign_ids alias. Saved-segment and campaign exclusions are combined. Self-exclusion and missing or other-workspace campaigns fail with MARKETING_CAMPAIGN_SELF_EXCLUSION or MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE; malformed IDs return MARKETING_CAMPAIGN_EXCLUSION_INVALID.
Duplicate metadata keeps previousCampaignIds, duplicatedFromCampaignId and the source name. Older clients that retain excludeAlreadyReceived:true cannot silently drop those linked exclusions. To remove the campaign-history filter deliberately, set metadata.excludeAlreadyReceived:false and audienceFilter.excludeCampaignIds:[] together. This never overrides consent or suppression.
SoundSync
Primary marketing routes and supported compatibility aliases
/api/developer/marketing/settings
Read sender and marketing settings
- Auth
- Account Bearer session token
- Scope
- marketing.view in the effective developer workspace; operation-specific audience checks still apply.
- Returns
- HTTP 200: settings.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks.
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."
},
"spending": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"monthlyLimitCents": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Null means no developer spending limit, not free sending."
},
"monthStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"monthEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"acceptedQuantity": {
"type": "integer",
"minimum": 0
},
"reservedQuantity": {
"type": "integer",
"minimum": 0
},
"usedCents": {
"type": "integer",
"minimum": 0
},
"committedCents": {
"type": "integer",
"minimum": 0
},
"remainingCents": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"includedQuantity": {
"type": "integer",
"minimum": 0
},
"rateCentsPer1000": {
"type": "integer",
"minimum": 0
},
"nearLimit": {
"type": "boolean"
},
"platformPlanningQuantity": {
"type": "integer",
"minimum": 0
},
"platformCommittedQuantity": {
"type": "integer",
"minimum": 0
},
"platformCapacityWarning": {
"type": "boolean"
},
"platformLimitEnforced": {
"type": "boolean"
},
"platformRemainingQuantity": {
"type": "integer",
"minimum": 0
},
"canManageLimit": {
"type": "boolean"
},
"canReviewPlatformCapacity": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/marketing/settings
Update workspace-wide sender settings
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and all-products workspace scope.
- Request fields
- marketingEnabled: boolean
- fromName: string
- fromEmail: string
- replyToEmail: string
- defaultFooterCompanyName: string
- monthlySpendLimitUsd: string,number,null. USD with up to two decimal places. Omit to preserve, clear with an empty string or null for unlimited, or use 0 for included sends only. Changing this field requires account-owner authority.
- Returns
- HTTP 200: settings.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. From address must be verified. Requires marketing.manage and all-products scope. Only the account owner or authorized platform owner can set or clear monthlySpendLimitUsd; other authorized teammates may retain their ordinary sender-setting edits without that field. Budgets are optional, unlimited by default, shared by campaigns and Growth Flows, and not a credit against the Full Store minimum. This setting does not bypass billing readiness, 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"
},
"monthlySpendLimitUsd": {
"type": [
"string",
"number",
"null"
],
"description": "USD with up to two decimal places. Omit to preserve, clear with an empty string or null for unlimited, or use 0 for included sends only. Changing this field requires account-owner authority."
}
},
"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."
},
"spending": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"monthlyLimitCents": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Null means no developer spending limit, not free sending."
},
"monthStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"monthEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"acceptedQuantity": {
"type": "integer",
"minimum": 0
},
"reservedQuantity": {
"type": "integer",
"minimum": 0
},
"usedCents": {
"type": "integer",
"minimum": 0
},
"committedCents": {
"type": "integer",
"minimum": 0
},
"remainingCents": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"includedQuantity": {
"type": "integer",
"minimum": 0
},
"rateCentsPer1000": {
"type": "integer",
"minimum": 0
},
"nearLimit": {
"type": "boolean"
},
"platformPlanningQuantity": {
"type": "integer",
"minimum": 0
},
"platformCommittedQuantity": {
"type": "integer",
"minimum": 0
},
"platformCapacityWarning": {
"type": "boolean"
},
"platformLimitEnforced": {
"type": "boolean"
},
"platformRemainingQuantity": {
"type": "integer",
"minimum": 0
},
"canManageLimit": {
"type": "boolean"
},
"canReviewPlatformCapacity": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
Operation errors: MARKETING_SPEND_OWNER_REQUIRED, MARKETING_SPEND_LIMIT_INVALID.
/api/developer/marketing/contacts
List permitted marketing contacts
- Auth
- Account Bearer session token
- Scope
- marketing.view in the effective developer workspace; operation-specific audience checks still apply.
- 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
- HTTP 200: rows, total, page, pageSize, canExclude.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks.
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.
/api/developer/marketing/contacts/import
Import a confirmed contact list
- Auth
- Account Bearer session token
- 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
- HTTP 201: rowsUploaded, validRows, imported, updated, duplicates, skippedInvalidEmail, skippedMissingEmail, skippedUnsubscribed, skippedSuppressed, productAssociationsAdded, skipped, errors.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. 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.
/api/developer/marketing/contacts/import/preview
Preview a contact import without sending
- Auth
- Account Bearer session token
- 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
- HTTP 200: headers, suggestedMapping, previewRows, report.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. 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.
/api/developer/marketing/suppressions
List saved marketing suppressions
- Auth
- Account Bearer session token
- Scope
- marketing.view in the effective developer workspace; operation-specific audience checks still apply.
- Request fields
- query page: integer
- query limit: integer
- query search: string
- Returns
- HTTP 200: suppressions.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks.
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.
/api/developer/marketing/campaigns
List permitted campaigns
- Auth
- Account Bearer session token
- 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
- HTTP 200: campaigns, total, page, pageSize.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before 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": ""
},
{
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"additionalProperties": true
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"pageSize": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
/api/developer/marketing/campaigns
Create a campaign draft
- Auth
- Account Bearer session token
- 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
- HTTP 201: campaign, audience.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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.
Operation errors: MARKETING_CAMPAIGN_EXCLUSION_INVALID, MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE, MARKETING_CAMPAIGN_SELF_EXCLUSION.
/api/developer/marketing/campaigns/{campaignId}
Update an editable campaign draft
- Auth
- Account Bearer session token
- 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
- HTTP 200: campaign, audience.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. Only draft or scheduled content is editable; sent content is not rewritten. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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: MARKETING_CAMPAIGN_EXCLUSION_INVALID, MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE, MARKETING_CAMPAIGN_SELF_EXCLUSION, CAMPAIGN_NOT_EDITABLE.
/api/developer/marketing/campaigns/{campaignId}/test
Send a campaign test to its permitted test recipient
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- email: string
- to: string
- Returns
- HTTP 200: sent, provider, transactionId, recipientEmail, recipients.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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.
/api/developer/marketing/campaigns/{campaignId}/send-now
Queue and process the campaign audience
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Returns
- HTTP 200: campaign, queued, processed, sent, failed, deferred, skipped, remainingQueued, pausedUntil, async.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. The route can queue asynchronous work or report a processing batch. HTTP success is not inbox delivery; inspect recipients and reports. Campaign-history exclusions use earlier campaigns owned by this workspace. Accepted, pending and uncertain previous deliveries are excluded by recorded email or known customer identity within that workspace, so correcting a known contact email does not reset its history. Proven pre-acceptance failures can remain eligible. Duplicate metadata retains the source links. Clearing the filter deliberately requires metadata.excludeAlreadyReceived:false with audienceFilter.excludeCampaignIds:[]. Suppressions still apply. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"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, 401, 402, 403, 404, 409, 500, 503.
Operation errors: MARKETING_CAMPAIGN_EXCLUSION_INVALID, MARKETING_CAMPAIGN_EXCLUSION_UNAVAILABLE, MARKETING_CAMPAIGN_SELF_EXCLUSION, MARKETING_SPEND_LIMIT_REACHED, MARKETING_PLATFORM_LIMIT_REACHED, MARKETING_DELIVERY_UNCONFIRMED, DEVELOPER_COST_PAYMENT_METHOD_REQUIRED, DEVELOPER_COST_BILLING_RESTRICTED, DEVELOPER_COST_BILLING_UNAVAILABLE, DEVELOPER_COST_FUNDING_UNAVAILABLE, 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.
/api/developer/marketing/campaigns/{campaignId}/schedule
Schedule an editable campaign
- Auth
- Account Bearer session token
- Scope
- marketing.view + marketing.manage and assigned-product campaign/audience access.
- Request fields
- scheduledAt: string (required)
- deliveryTimezone: string
- Returns
- HTTP 200: campaign.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. Use a future date and valid IANA timezone. scheduled_at and timezone aliases are accepted. A developer budget is optional and unlimited by default. Campaigns and automation share accepted and reserved usage in the planned Eastern month. Paid sends require a verified payment method; unpaid live bills and verification failures can pause marketing, including included sends. A platform planning warning alone is not a cap. Uncertain sends retain their reservation and must be reviewed rather than blindly resent. These holds do not revoke licenses or downloads. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
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
}
},
"productMatch": {
"type": "string",
"enum": [
"any",
"all"
]
},
"excludeCampaignIds": {
"type": "array",
"maxItems": 50,
"items": {
"type": "integer",
"minimum": 1
},
"description": "Earlier campaign IDs owned by this workspace. Excludes accepted, pending and uncertain earlier deliveries; cannot contain this draft campaign."
},
"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"
},
"costCents": {
"type": "integer",
"minimum": 0
},
"costBasis": {
"const": "current_policy_estimate"
},
"emailsSentCount": {
"type": "integer"
},
"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
},
"audienceEstimateStatus": {
"type": "string",
"enum": [
"ready",
"unavailable"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 402, 403, 404, 409, 500, 503.
Operation errors: MARKETING_SPEND_LIMIT_REACHED, MARKETING_PLATFORM_LIMIT_REACHED, MARKETING_DELIVERY_UNCONFIRMED, DEVELOPER_COST_PAYMENT_METHOD_REQUIRED, DEVELOPER_COST_BILLING_RESTRICTED, DEVELOPER_COST_BILLING_UNAVAILABLE, DEVELOPER_COST_FUNDING_UNAVAILABLE, 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.
/api/developer/marketing/usage
Read monthly marketing usage
- Auth
- Account Bearer session token
- Scope
- marketing.view in the effective developer workspace; operation-specific audience checks still apply.
- Returns
- HTTP 200: usage, includedMonthlyEmails, costBasis.
- Notes
- The primary /api/developer/marketing mount and /api/developer/email-marketing compatibility mount expose the same router. These are alternate addresses for the same action, not separate sends. Follow the operation-specific sender, audience, suppression and test-recipient checks. Current live usage estimates use one shared allowance per Eastern calendar month, including campaigns and automation. total_cents is a current-policy estimate, not a finalized invoice, historical payment or waiver. Campaign reports allocate overage blocks in actual send order instead of giving each campaign a separate allowance.
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"
},
"costBasis": {
"const": "current_policy_estimate"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
SoundSync
Preview campaign spending without sending
/api/developer/marketing/campaigns/{campaignId}/cost-preview
Estimate the eligible audience against planned monthly spend
- Auth
- Account Bearer session token
- Scope
- marketing.view and assigned-product campaign/audience access.
- Request fields
- query scheduledAt: string. Optional planned date within the next year.
- query deliveryTimezone: string. IANA timezone for a planned local date; defaults to UTC.
- Returns
- HTTP 200: enabled, monthlyLimitCents, monthStart, monthEnd, acceptedQuantity, reservedQuantity, usedCents, committedCents, remainingCents, includedQuantity, rateCentsPer1000, nearLimit, platformPlanningQuantity, platformCommittedQuantity, platformCapacityWarning, platformLimitEnforced, platformRemainingQuantity, canManageLimit, canReviewPlatformCapacity, recipientCount, additionalCents, projectedCents, withinLimit.
- Notes
- Requires marketing.view and assigned-product access to the campaign. Estimates the eligible current audience against the planned Eastern billing month, including existing accepted and reserved usage. No provider message or payment is sent, but monthly accounting counters can be initialized; this is not a zero-side-effect health probe. A preview is not a final invoice or a reservation. Billing, chosen budgets and suppression are checked again at dispatch. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
Request, response and error reference
Query and header parameters
[
{
"name": "scheduledAt",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Optional planned date within the next year."
},
{
"name": "deliveryTimezone",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "IANA timezone for a planned local date; defaults to UTC."
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"monthlyLimitCents": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Null means no developer spending limit, not free sending."
},
"monthStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"monthEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"acceptedQuantity": {
"type": "integer",
"minimum": 0
},
"reservedQuantity": {
"type": "integer",
"minimum": 0
},
"usedCents": {
"type": "integer",
"minimum": 0
},
"committedCents": {
"type": "integer",
"minimum": 0
},
"remainingCents": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"includedQuantity": {
"type": "integer",
"minimum": 0
},
"rateCentsPer1000": {
"type": "integer",
"minimum": 0
},
"nearLimit": {
"type": "boolean"
},
"platformPlanningQuantity": {
"type": "integer",
"minimum": 0
},
"platformCommittedQuantity": {
"type": "integer",
"minimum": 0
},
"platformCapacityWarning": {
"type": "boolean"
},
"platformLimitEnforced": {
"type": "boolean"
},
"platformRemainingQuantity": {
"type": "integer",
"minimum": 0
},
"canManageLimit": {
"type": "boolean"
},
"canReviewPlatformCapacity": {
"type": "boolean"
},
"recipientCount": {
"type": "integer",
"minimum": 0
},
"additionalCents": {
"type": "integer",
"minimum": 0
},
"projectedCents": {
"type": "integer",
"minimum": 0
},
"withinLimit": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
Operation errors: MARKETING_COST_DATE_INVALID.
/api/developer/email-marketing/campaigns/{campaignId}/cost-preview
Use the supported compatibility mount for the same cost preview
- Auth
- Account Bearer session token
- Scope
- marketing.view and assigned-product campaign/audience access.
- Request fields
- query scheduledAt: string. Optional planned date within the next year.
- query deliveryTimezone: string. IANA timezone for a planned local date; defaults to UTC.
- Returns
- HTTP 200: enabled, monthlyLimitCents, monthStart, monthEnd, acceptedQuantity, reservedQuantity, usedCents, committedCents, remainingCents, includedQuantity, rateCentsPer1000, nearLimit, platformPlanningQuantity, platformCommittedQuantity, platformCapacityWarning, platformLimitEnforced, platformRemainingQuantity, canManageLimit, canReviewPlatformCapacity, recipientCount, additionalCents, projectedCents, withinLimit.
- Notes
- Requires marketing.view and assigned-product access to the campaign. Estimates the eligible current audience against the planned Eastern billing month, including existing accepted and reserved usage. No provider message or payment is sent, but monthly accounting counters can be initialized; this is not a zero-side-effect health probe. A preview is not a final invoice or a reservation. Billing, chosen budgets and suppression are checked again at dispatch. 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. audienceEstimateStatus:unavailable means the optional draft count timed out; a displayed zero is not evidence of an empty audience. A valid draft may still save. Fresh audience eligibility, suppression, sender and funding checks remain required before sending.
Request, response and error reference
Query and header parameters
[
{
"name": "scheduledAt",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Optional planned date within the next year."
},
{
"name": "deliveryTimezone",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "IANA timezone for a planned local date; defaults to UTC."
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"monthlyLimitCents": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Null means no developer spending limit, not free sending."
},
"monthStart": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"monthEnd": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"acceptedQuantity": {
"type": "integer",
"minimum": 0
},
"reservedQuantity": {
"type": "integer",
"minimum": 0
},
"usedCents": {
"type": "integer",
"minimum": 0
},
"committedCents": {
"type": "integer",
"minimum": 0
},
"remainingCents": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"includedQuantity": {
"type": "integer",
"minimum": 0
},
"rateCentsPer1000": {
"type": "integer",
"minimum": 0
},
"nearLimit": {
"type": "boolean"
},
"platformPlanningQuantity": {
"type": "integer",
"minimum": 0
},
"platformCommittedQuantity": {
"type": "integer",
"minimum": 0
},
"platformCapacityWarning": {
"type": "boolean"
},
"platformLimitEnforced": {
"type": "boolean"
},
"platformRemainingQuantity": {
"type": "integer",
"minimum": 0
},
"canManageLimit": {
"type": "boolean"
},
"canReviewPlatformCapacity": {
"type": "boolean"
},
"recipientCount": {
"type": "integer",
"minimum": 0
},
"additionalCents": {
"type": "integer",
"minimum": 0
},
"projectedCents": {
"type": "integer",
"minimum": 0
},
"withinLimit": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 401, 403, 404, 503.
Operation errors: MARKETING_COST_DATE_INVALID.
Read and change an optional budget
GET /api/developer/marketing/settings returns settings.spending, including monthlyLimitCents, usedCents, committedCents, remainingCents and canManageLimit. Null monthlyLimitCents means unlimited spending. PATCH /settings accepts monthlySpendLimitUsd: omit it to preserve the budget, use 0 for included sends only, or clear it to return to unlimited. Only the account owner or authorized platform owner can change this field; ordinary settings edits retain their existing marketing.manage and all-products checks.
The campaign cost-preview accepts scheduledAt and deliveryTimezone. additionalCents and projectedCents are estimates, not a final invoice. It can initialize monthly counters, but sends no email and collects no payment. Delivery rechecks budget, billing, audience and suppression. platformCapacityWarning is advisory unless the separate operator hard limit is enabled.
The email-marketing mount is the same queue, not a second send path
These active /api/developer/email-marketing aliases use the same router as /api/developer/marketing. They retain the preferred operation's request/response fields, marketing permissions, audience/product restrictions, workspace-wide write rules, sender readiness, suppression, billing checks and send-state behavior. Use the preferred contract for each call.
An alias does not create a separate allowance, retry guarantee or idempotency boundary. Previewing, importing, editing, generating AI content and resuming queued recipients keep their original side effects; do not repeat an uncertain mutation through another mount. Existing Growth Flow alias mappings remain in the Growth Flow API reference.
SoundSync
Additional email-marketing compatibility operation map
| Method | Compatibility path | Contract or result |
|---|---|---|
| GET | /api/developer/email-marketing/summary | GET /api/developer/marketing/summary |
| POST | /api/developer/email-marketing/audience/estimate | POST /api/developer/marketing/audience/estimate |
| GET | /api/developer/email-marketing/contacts/import/demo.csv | GET /api/developer/marketing/contacts/import/demo.csv |
| GET | /api/developer/email-marketing/segments | GET /api/developer/marketing/segments |
| POST | /api/developer/email-marketing/segments | POST /api/developer/marketing/segments |
| PATCH | /api/developer/email-marketing/segments/{segmentId} | PATCH /api/developer/marketing/segments/{segmentId} |
| DELETE | /api/developer/email-marketing/segments/{segmentId} | DELETE /api/developer/marketing/segments/{segmentId} |
| PATCH | /api/developer/email-marketing/contacts/bulk-suppress | PATCH /api/developer/marketing/contacts/bulk-suppress |
| PATCH | /api/developer/email-marketing/contacts/{id}/consent | PATCH /api/developer/marketing/contacts/{id}/consent |
| PATCH | /api/developer/email-marketing/contacts/{id}/suppress | PATCH /api/developer/marketing/contacts/{id}/suppress |
| POST | /api/developer/email-marketing/scheduled-deals/{dealId}/campaign-draft | POST /api/developer/marketing/scheduled-deals/{dealId}/campaign-draft |
| POST | /api/developer/email-marketing/ai/generate-draft | POST /api/developer/marketing/ai/generate-draft |
| POST | /api/developer/email-marketing/ai/generate-subjects | POST /api/developer/marketing/ai/generate-subjects |
| POST | /api/developer/email-marketing/ai/generate-preview-text | POST /api/developer/marketing/ai/generate-preview-text |
| POST | /api/developer/email-marketing/ai/rewrite | POST /api/developer/marketing/ai/rewrite |
| POST | /api/developer/email-marketing/ai/generate-banner | POST /api/developer/marketing/ai/generate-banner |
| POST | /api/developer/email-marketing/ai/generate-scheduled-deal-draft | POST /api/developer/marketing/ai/generate-scheduled-deal-draft |
| GET | /api/developer/email-marketing/campaigns/{campaignId} | GET /api/developer/marketing/campaigns/{campaignId} |
| PATCH | /api/developer/email-marketing/campaigns/{campaignId}/name | PATCH /api/developer/marketing/campaigns/{campaignId}/name |
| DELETE | /api/developer/email-marketing/campaigns/{campaignId} | DELETE /api/developer/marketing/campaigns/{campaignId} |
| POST | /api/developer/email-marketing/campaigns/{campaignId}/duplicate | POST /api/developer/marketing/campaigns/{campaignId}/duplicate |
| POST | /api/developer/email-marketing/campaigns/{campaignId}/preview | POST /api/developer/marketing/campaigns/{campaignId}/preview |
| POST | /api/developer/email-marketing/campaigns/{campaignId}/resume-send | POST /api/developer/marketing/campaigns/{campaignId}/resume-send |
| POST | /api/developer/email-marketing/campaigns/{campaignId}/retry-failed | POST /api/developer/marketing/campaigns/{campaignId}/retry-failed |
| POST | /api/developer/email-marketing/campaigns/{campaignId}/cancel | POST /api/developer/marketing/campaigns/{campaignId}/cancel |
| GET | /api/developer/email-marketing/campaigns/{campaignId}/retry-summary | GET /api/developer/marketing/campaigns/{campaignId}/retry-summary |
| GET | /api/developer/email-marketing/campaigns/latest/report | GET /api/developer/marketing/campaigns/latest/report |
| GET | /api/developer/email-marketing/campaigns/{campaignId}/recipients | GET /api/developer/marketing/campaigns/{campaignId}/recipients |
| GET | /api/developer/email-marketing/campaigns/{campaignId}/report | GET /api/developer/marketing/campaigns/{campaignId}/report |
A slow count must not lose your draft
Campaign creation, duplication and draft saves can retain a valid draft when its optional audience estimate times out. audienceEstimateStatus:unavailable means the count is unavailable, not that the audience is empty. Refresh the count before sending. Scheduling and sending retain fresh eligibility, suppression, sender and funding checks; a saved draft is never send approval.
SoundSync
