Skip to content
SoundSyncAudio software platform

API Reference

Email Marketing API

Developer-authenticated contacts, suppressions, campaigns, automation, AI draft, usage, and unsubscribe endpoints.

SoundSync

Verified endpoints

These endpoints are route-backed in the current platform.

GET /api/developer/email-marketing/settings

Fetch marketing settings.

Auth
Account Bearer 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.

PATCH /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.

GET /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.

POST /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.

POST /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.

GET /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.

GET /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.

POST /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.

PATCH /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.

POST /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.

POST /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.

POST /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.

GET /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.

GET /unsubscribe

Marketing unsubscribe entry route.

Auth
Public unsubscribe token/link context.
Scope
Use the authentication and resource scope specified for this operation.
Request fields
  • token/query context as implemented
Returns
Unsubscribe page/action response.
Side effects
May record unsubscribe/suppression when valid.

SoundSync

Campaigns, contacts, reporting, and assistance

Current route and service contracts. Examples below are illustrative; live provider outcomes and client-host testing are separate checks.

GET /api/developer/marketing/summary

Read marketing home totals and current activity.

Auth
Account Bearer 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.

POST /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.

GET /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.

GET /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.

POST /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.

PATCH /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.

DELETE /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.

PATCH /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.

PATCH /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.

PATCH /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.

POST /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.

POST /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.

POST /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.

POST /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.

POST /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.

POST /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.

POST /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.

GET /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.

DELETE /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.

POST /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.

POST /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.

POST /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.

POST /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.

GET /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.

GET /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.

GET /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

Growth flow and automation API

All current flow, sequence, test, trigger, suppression, and queue routes.

Usage guide

Provider acceptance, included sends, started blocks, and tests.

SoundSync

Campaign names and retries

Developer marketing automation permission and all-product scope apply. This is not the plugin licensing API.

PATCH /api/developer/marketing/campaigns/:campaignId/name

Rename a current or sent campaign

Auth
Account Bearer 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.

GET /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.

POST /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

Audience and suppression guide

Automatic enrollment, sending permission, and protected preferences.

Privacy policy

How customer and contact information is used.

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

StatusWhat the report knows
not_sentNo sends for this report; no provider-history conclusion is implied.
pendingNo usable provider snapshot yet. Pending sync is not a confirmed zero.
retryingProvider lookup failed without a usable snapshot. Known events remain while sync retries; no completion deadline is promised.
readyA usable provider snapshot is available. providerStatsCheckedAt identifies the observation, not inbox certainty or payout revenue.
staleLast usable provider totals remain after a newer lookup failure. These are last-known values, not current confirmed totals. Inspect providerStatsError.
unavailableProvider 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

FieldInterpretation
deliveredComplete provider-channel delivery total when available; null means unavailable, not zero.
recordedDeliveredCount of saved, matched individual delivery receipts. This can be incomplete; zero does not prove no delivery.
deliverySource: provider_channelUse the complete provider total for that campaign; do not add its receipt count again.
deliverySource: recorded_receiptsOnly individually recorded delivery evidence is available; do not present it as the full campaign total.
deliverySource: not_sent / unavailableNo sends yet / no usable delivery evidence. Read providerStatsStatus separately for sync availability.
lastDeliveryAtLatest matched receipt timestamp where available, otherwise null. It is not the time of a new provider lookup.
performanceSourceelastic_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 / codeNext step
send-now: CAMPAIGN_SEND_STATE_INVALID, CAMPAIGN_STATE_CHANGEDReload the campaign. Only send from a supported current state; do not repeat a completed send.
send-now: CAMPAIGN_SCHEDULED_NOT_DUEWait for the scheduled time or deliberately change the schedule through supported controls.
send-now: MARKETING_AUDIENCE_EMPTYReview 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_DISABLEDResolve 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_REQUIREDComplete the verified sender, reply-to and required business identity/footer before trying again.
MARKETING_SUBJECT_REQUIRED / MARKETING_CONTENT_REQUIREDComplete the message, preview it and then deliberately retry the intended action.
schedule: CAMPAIGN_NOT_SCHEDULABLE; INVALID_SCHEDULED_AT / INVALID_DELIVERY_TIMEZONEReload state for a 409 conflict. For a 400 input error, use a future date and a valid IANA timezone.
resume-send: CAMPAIGN_NOT_SENDINGReload progress. Resume is for an existing sending campaign, not a resend command.
retry-failed: CAMPAIGN_RETRY_STATE_INVALIDReload. Retry supports campaigns that started sending, not a new draft or analytics repair.
retry-failed: CAMPAIGN_RETRY_SCOPE_INVALID / CAMPAIGN_RETRY_CONFIRMATION_REQUIREDUse 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_DELETABLEReload current state; an active send cannot be erased by deleting its campaign.
test: TEST_RECIPIENT_REQUIREDSave the developer support recipient before testing. This 400 response does not allow arbitrary bulk recipients.

SoundSync

Campaign access is operation-specific

OperationRequired workspace access
Campaign reads and reportsmarketing.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 actionsmarketing.view + marketing.manage, with campaign product/audience access.
GET retry-summary; POST retry-failed; PATCH campaign name; DELETE campaignmarketing.view + marketing.manage and all-products scope, including the GET retry summary.
Sender settings, contact import/consent/suppression writes and segment archivalmarketing.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

ChoiceSelection
productMatch:anyMatches customers owning at least one selected product.
productMatch:allMatches customers owning every selected product.
Does not ownUses the corresponding inverse ownership test; review the audience estimate with the same product set and match mode.
Before sendingAn 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

GET /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.

PATCH /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.

GET /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.

POST /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.

POST /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.

GET /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.

GET /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.

POST /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.

PATCH /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.

POST /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.

POST /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.

POST /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.

GET /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

GET /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.

GET /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

MethodCompatibility pathContract or result
GET/api/developer/email-marketing/summaryGET /api/developer/marketing/summary
POST/api/developer/email-marketing/audience/estimatePOST /api/developer/marketing/audience/estimate
GET/api/developer/email-marketing/contacts/import/demo.csvGET /api/developer/marketing/contacts/import/demo.csv
GET/api/developer/email-marketing/segmentsGET /api/developer/marketing/segments
POST/api/developer/email-marketing/segmentsPOST /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-suppressPATCH /api/developer/marketing/contacts/bulk-suppress
PATCH/api/developer/email-marketing/contacts/{id}/consentPATCH /api/developer/marketing/contacts/{id}/consent
PATCH/api/developer/email-marketing/contacts/{id}/suppressPATCH /api/developer/marketing/contacts/{id}/suppress
POST/api/developer/email-marketing/scheduled-deals/{dealId}/campaign-draftPOST /api/developer/marketing/scheduled-deals/{dealId}/campaign-draft
POST/api/developer/email-marketing/ai/generate-draftPOST /api/developer/marketing/ai/generate-draft
POST/api/developer/email-marketing/ai/generate-subjectsPOST /api/developer/marketing/ai/generate-subjects
POST/api/developer/email-marketing/ai/generate-preview-textPOST /api/developer/marketing/ai/generate-preview-text
POST/api/developer/email-marketing/ai/rewritePOST /api/developer/marketing/ai/rewrite
POST/api/developer/email-marketing/ai/generate-bannerPOST /api/developer/marketing/ai/generate-banner
POST/api/developer/email-marketing/ai/generate-scheduled-deal-draftPOST /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}/namePATCH /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}/duplicatePOST /api/developer/marketing/campaigns/{campaignId}/duplicate
POST/api/developer/email-marketing/campaigns/{campaignId}/previewPOST /api/developer/marketing/campaigns/{campaignId}/preview
POST/api/developer/email-marketing/campaigns/{campaignId}/resume-sendPOST /api/developer/marketing/campaigns/{campaignId}/resume-send
POST/api/developer/email-marketing/campaigns/{campaignId}/retry-failedPOST /api/developer/marketing/campaigns/{campaignId}/retry-failed
POST/api/developer/email-marketing/campaigns/{campaignId}/cancelPOST /api/developer/marketing/campaigns/{campaignId}/cancel
GET/api/developer/email-marketing/campaigns/{campaignId}/retry-summaryGET /api/developer/marketing/campaigns/{campaignId}/retry-summary
GET/api/developer/email-marketing/campaigns/latest/reportGET /api/developer/marketing/campaigns/latest/report
GET/api/developer/email-marketing/campaigns/{campaignId}/recipientsGET /api/developer/marketing/campaigns/{campaignId}/recipients
GET/api/developer/email-marketing/campaigns/{campaignId}/reportGET /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.