{ "openapi": "3.1.0", "info": { "title": "Sequenzy API", "description": "Sequenzy API for managing subscribers, tags, events, sequences, and transactional emails", "version": "1.0.0" }, "servers": [ { "url": "https://api.sequenzy.com/api/v1", "description": "Production server" }, { "url": "https://api.sequenzy.com/v1", "description": "Legacy production server alias" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key passed as Bearer token" } }, "headers": { "RetryAfter": { "description": "Number of seconds to wait before retrying the request.", "schema": { "type": "integer", "minimum": 1, "example": 1 } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Unauthorized" } } } } } }, "NotFound": { "description": "The requested resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Account not found" } } } } } }, "ValidationError": { "description": "The request body or parameters are invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" } } } } } }, "TransientDatabaseUnavailable": { "description": "The database was temporarily unavailable. The request may be retried after the delay in Retry-After.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "The service could not reach its database for a moment. Retry the request.", "code": "SERVICE_UNAVAILABLE" } } } }, "SegmentReferenceLimitExceeded": { "description": "The segment's filters follow too many segment-to-segment references: more than 16 levels in one chain (SEGMENT_REFERENCE_DEPTH_EXCEEDED), or more than 1,000 references in total, counting a segment again each time it is referenced (SEGMENT_REFERENCE_COUNT_EXCEEDED). Nested filter groups inside a segment do not count. Retrying does not help; reduce the nesting or the number of references first. title and howToFix differ per code.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SEGMENT_REFERENCE_DEPTH_EXCEEDED", "SEGMENT_REFERENCE_COUNT_EXCEEDED" ] }, "title": { "type": "string", "example": "Segment references nested too deeply" }, "description": { "type": "string", "description": "Same explanation as error." }, "howToFix": { "type": "string" }, "docsUrl": { "type": "string" }, "details": { "type": "object", "properties": { "limit": { "type": "string", "enum": [ "depth", "total" ] }, "segmentId": { "type": "string", "description": "Referenced segment that exceeded the limit." }, "referenceChain": { "type": "array", "items": { "type": "string" }, "description": "Segment IDs already followed to reach segmentId, outermost first. Does not include the segment being counted." }, "maxDepth": { "type": "integer", "example": 16 }, "maxReferences": { "type": "integer", "example": 1000 } } } } } ] }, "example": { "success": false, "error": "Segment references are nested too deeply. A segment filter can reference other segments up to 16 levels deep, and the reference to segment seg_r would be level 17 (chain: seg_b > seg_c > ... > seg_q > seg_r). Retrying does not help. Copy the conditions of an inner segment into its parent instead of referencing it to reduce the nesting.", "code": "SEGMENT_REFERENCE_DEPTH_EXCEEDED", "title": "Segment references nested too deeply", "description": "Segment references are nested too deeply. A segment filter can reference other segments up to 16 levels deep, and the reference to segment seg_r would be level 17 (chain: seg_b > seg_c > ... > seg_q > seg_r). Retrying does not help. Copy the conditions of an inner segment into its parent instead of referencing it to reduce the nesting.", "howToFix": "Retrying does not help. Copy the conditions of an inner segment into its parent instead of referencing it to reduce the nesting.", "docsUrl": "https://docs.sequenzy.com/api-reference/segments/count", "details": { "limit": "depth", "segmentId": "seg_r", "referenceChain": [ "seg_b", "seg_c", "seg_d", "seg_e", "seg_f", "seg_g", "seg_h", "seg_i", "seg_j", "seg_k", "seg_l", "seg_m", "seg_n", "seg_o", "seg_p", "seg_q" ], "maxDepth": 16, "maxReferences": 1000 } } } } } }, "schemas": { "SequenceTestRunResponse": { "type": "object", "required": [ "run" ], "properties": { "run": { "type": "object", "required": [ "id", "automationId", "companyId", "subscriberId", "status", "recipientEmails", "speedMultiplier", "steps", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Test run ID." }, "automationId": { "type": "string", "description": "Sequence ID." }, "companyId": { "type": "string" }, "subscriberId": { "type": [ "string", "null" ], "description": "Subscriber ID, or null on historical runs." }, "initiatedByUserId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "recipientEmails": { "type": "array", "items": { "type": "string" } }, "speedMultiplier": { "type": "integer" }, "steps": { "type": "array", "description": "Step execution logs including nodeId, status, message, timing and action-specific metadata when available.", "items": { "type": "object", "additionalProperties": true } }, "errorMessage": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "jobId": { "type": "string", "description": "Queue job ID on creation only. Empty if unavailable." } } } } }, "SubscriberOperation": { "type": "object", "required": [ "id", "companyId", "kind", "status", "total", "processed", "succeeded", "failed", "error", "failures", "createdAt", "completedAt", "expiresAt" ], "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "kind": { "type": "string", "enum": [ "add_tags" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "total": { "type": "integer", "minimum": 0, "description": "Selected contacts; grows while selection is queued." }, "processed": { "type": "integer", "minimum": 0 }, "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "error": { "type": [ "string", "null" ] }, "failures": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "subscriberId", "error" ], "properties": { "subscriberId": { "type": "string" }, "error": { "type": "string" } } } }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Processing deadline while active; retention deadline after completion." } } }, "SubscriberOperationResponse": { "type": "object", "required": [ "success", "operation" ], "properties": { "success": { "type": "boolean" }, "operation": { "$ref": "#/components/schemas/SubscriberOperation" } } }, "SubscriberOperationStart": { "type": "object", "additionalProperties": false, "required": [ "kind", "requestKey", "tags" ], "properties": { "kind": { "type": "string", "enum": [ "add_tags" ] }, "requestKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Reuse after an uncertain response. Different normalized settings with the same company/key return 409." }, "audience": { "type": "object", "additionalProperties": false, "description": "Defaults to all contacts. Selection walks live pages before mutations, excludes contacts created after the request, and is not a point-in-time database snapshot. Provide root or filters, never both.", "properties": { "subscriberIds": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "filters": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/FilterLeaf" } }, "root": { "$ref": "#/components/schemas/FilterGroup" }, "filterJoinOperator": { "type": "string", "enum": [ "and", "or" ] }, "activeOnly": { "type": "boolean", "default": false }, "search": { "type": "string", "maxLength": 500 }, "listId": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "tags": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Tag names, normalized like single-contact tags." }, "triggerAutomations": { "type": "boolean", "default": false, "description": "Requires automations:trigger." } } }, "EmailAiStyleState": { "type": "object", "required": [ "success", "style", "revisionId", "canManage" ], "properties": { "success": { "type": "boolean" }, "style": { "type": [ "object", "null" ], "description": "Independent version 1 appearance snapshot. No source copy, links or bindings are stored in block styles. Unsupported versions are returned as null.", "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "id": { "type": "string" }, "sourceEmailId": { "type": "string" }, "sourceName": { "type": "string" }, "savedAt": { "type": "string", "format": "date-time" }, "theme": { "type": "object", "additionalProperties": true }, "fontFamily": { "type": "string" }, "emailPreset": { "type": "string", "enum": [ "branded", "minimal" ] }, "blocks": { "type": "array", "description": "Appearance records keyed by block type and discriminator, not source email blocks.", "items": { "type": "object", "additionalProperties": true } }, "layout": { "type": "object", "description": "Structure guidance captured with the appearance. Absent on snapshots saved before layout habits existed.", "properties": { "outline": { "type": "array", "description": "Top-level block descriptors in source order (for example heading:1, divider:dots, button:pill), excluding logo and footer scaffolding.", "items": { "type": "string" } }, "rules": { "type": "array", "description": "Confirmed layout habits. Generation follows them in prompts and inserts content-free companions (dividers, spacers) deterministically.", "items": { "$ref": "#/components/schemas/EmailAiStyleLayoutRule" } } } }, "notes": { "type": "string", "description": "Free-text design notes supplied when saving, up to 500 characters." } } }, "revisionId": { "type": [ "string", "null" ], "description": "Pass this as expectedStyleId on the next write. An unsupported style version still returns its revision for replacement or clearing." }, "canManage": { "type": "boolean", "description": "Whether your key scopes and workspace role permit saving or clearing." } } }, "EmailAiStyleLayoutRule": { "type": "object", "required": [ "id", "kind", "block", "description" ], "properties": { "id": { "type": "string", "description": "Stable rule identifier, for example around|button|divider:dots. Pass it in layoutRuleIds to keep the habit." }, "kind": { "type": "string", "enum": [ "opener", "around", "before", "after" ] }, "block": { "type": "string", "description": "Target block type, for example button or video." }, "companion": { "type": "string", "description": "Content-free companion descriptor for around/before/after rules, for example divider:dots." }, "description": { "type": "string", "example": "Dotted divider above and below every button" } } }, "EmailAiStyleCanvas": { "type": "object", "required": [ "blocks", "theme", "fontFamily", "emailPreset" ], "properties": { "blocks": { "type": "array", "maxItems": 500, "description": "Native blocks JSON, limited to 500,000 serialized characters. Must contain substantive email content.", "items": { "type": "object", "additionalProperties": true } }, "theme": { "type": "object", "description": "Complete editor theme. Required color keys are primary, background, surface, text, mutedText, heading, border and link. Required typography keys are baseFontSize, leadFontSize, baseLineHeight, heading1Size, heading2Size, heading3Size and buttonFontSize. Required layout keys are contentWidth, containerPaddingX, containerPaddingY, blockSpacing, baseRadius, sectionPadding, buttonPaddingX, buttonPaddingY and borderedBlockPadding. Optional theme fields match the editor, including content color, heading font, button radius and weight.", "required": [ "presetId", "colors", "typography", "layout" ], "properties": { "presetId": { "type": "string", "enum": [ "default", "soft", "editorial", "bold" ] }, "colors": { "type": "object", "additionalProperties": { "type": "string" } }, "typography": { "type": "object", "additionalProperties": true }, "layout": { "type": "object", "additionalProperties": { "type": "number" } } }, "additionalProperties": true }, "fontFamily": { "type": "string", "minLength": 1, "maxLength": 500 }, "emailPreset": { "type": "string", "enum": [ "branded", "minimal" ] } } }, "WebTrackingKey": { "type": "object", "description": "A publishable key for the browser tracking SDK. The key ships in the customer's page source by design, so it is not a secret; it authorizes storefront customer events only and carries an origin allowlist instead of scopes.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "publicKey": { "type": "string", "description": "The publishable key, prefixed seq_pk_." }, "allowedOrigins": { "type": "array", "items": { "type": "string" }, "description": "Normalized origins allowed to use this key. Empty means any origin." }, "isActive": { "type": "boolean", "description": "False when revoked. Revoked keys are rejected at ingest." }, "unrestricted": { "type": "boolean", "description": "True when the allowlist is empty, so any site can send events with this key." }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the key last authorized an event, or null if it never has. Updated at most every five minutes." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "installSnippet": { "type": "string", "description": "The exact script tag to paste into every page. Embeds both the key and the workspace id." }, "endpoint": { "type": "string", "description": "Ingest URL the SDK posts events to." }, "warning": { "type": "string", "description": "Present only when the key is unrestricted." } } }, "IntegrationPixelState": { "type": "object", "description": "Live storefront tracking pixel state for a Shopify integration, read from the store on every call.", "properties": { "success": { "type": "boolean", "example": true }, "integrationId": { "type": "string" }, "provider": { "type": "string", "example": "shopify" }, "shopDomain": { "type": "string", "example": "example.myshopify.com" }, "pixel": { "type": "object", "properties": { "installed": { "type": "boolean", "description": "Whether a pixel for this app exists on the store." }, "id": { "type": [ "string", "null" ], "description": "Shopify's pixel ID." }, "endpoint": { "type": [ "string", "null" ], "description": "Callback URL the installed pixel posts events to." }, "endpointCurrent": { "type": "boolean", "description": "Whether the pixel posts to this account's canonical endpoint or the supported Shopify compatibility endpoint." }, "configurationCurrent": { "type": "boolean", "description": "Whether the endpoint and signed company, shop, and integration settings all match the current connection." }, "healthy": { "type": "boolean", "description": "Installed, current, and confirmed by Shopify. Check this before relying on any on-site event." }, "error": { "type": [ "string", "null" ], "description": "Set when Shopify could not be reached or refused the query. Distinct from \"not installed\" - the state is unknown." } } }, "dependentEvents": { "type": "array", "description": "Event names that depend on this pixel. They are confirmed unable to arrive only when pixel.error is null and pixel.healthy is false.", "items": { "type": "string" } }, "message": { "type": "string" } } }, "IntegrationAttioMapping": { "type": "object", "description": "Attio list mapping for a connected integration: saved Sequenzy-to-Attio listMap, live people-lists from Attio, and this company's Sequenzy lists.", "properties": { "success": { "type": "boolean", "example": true }, "integrationId": { "type": "string" }, "provider": { "type": "string", "example": "attio" }, "listMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Sequenzy list id to Attio list UUID or api slug." }, "mappedListCount": { "type": "integer", "description": "Number of saved mappings whose Sequenzy source and Attio target lists both still exist. Stale saved entries remain in listMap but are not counted." }, "syncCompanyFromDomain": { "type": "boolean", "description": "When true, upsert a company from the person's non-free-mail email domain." }, "sequenzyLists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "attioLists": { "type": "array", "description": "Attio people-lists the stored token can write, read live.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "apiSlug": { "type": "string" }, "name": { "type": "string" } } } }, "changed": { "type": "boolean", "description": "Present on PATCH. False when already in the requested state." }, "changedFields": { "type": "array", "description": "Present on PATCH. Which settings actually moved.", "items": { "type": "string" } }, "message": { "type": "string" } } }, "RenderEmailRequest": { "type": "object", "additionalProperties": false, "description": "Personalization and output options for a render. Omit every field to render for a sample contact with clean links.", "properties": { "subscriberId": { "type": "string", "description": "Personalize as this stored subscriber. Mutually exclusive with subscriber. The rendered HTML then carries that subscriber's details, so this field additionally requires the subscribers:read scope.", "example": "sub_abc123" }, "subscriber": { "type": "object", "description": "Personalize as an ad-hoc contact. Mutually exclusive with subscriberId.", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "customAttributes": { "type": "object", "additionalProperties": true }, "tags": { "type": "array", "description": "Tags this ad-hoc contact carries, used to evaluate tag block conditions. Nothing is stored. Without them a tag condition has no tags to read and renders as false, so only the else branch of a tag split can be previewed. Every other stored-state condition still needs subscriberId.", "items": { "type": "string" } } }, "required": [ "email" ] }, "variables": { "type": "object", "description": "Extra merge variables layered over the contact's attributes.", "additionalProperties": true }, "locale": { "type": "string", "description": "Force a localization locale instead of deriving it from the contact.", "example": "es" }, "variantId": { "type": "string", "description": "Render a specific A/B test variant. Required for sequence steps whose nodeType is action_ab_test; those steps have no email of their own. Sequence variants also need the ab_tests:read scope. Ignored for templates.", "example": "var_abc123" }, "tracking": { "type": "boolean", "default": false, "description": "Apply the company's auto-UTM link decoration as a real send would. Per-send click redirects and the open pixel need a real email send record and are never present in a render." } } }, "RenderEmailResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "html": { "type": "string", "description": "Email-safe HTML document, rendered exactly as it would be sent." }, "subject": { "type": "string", "description": "Subject line with merge tags resolved." }, "previewText": { "type": [ "string", "null" ], "description": "Inbox preview text with merge tags resolved." }, "locale": { "type": "string", "description": "Localization locale the render resolved to.", "example": "en" }, "personalized": { "type": "boolean", "description": "False means no contact was supplied, so a sample contact was used and contact-specific merge tags resolved to empty values." }, "trackingApplied": { "type": "boolean", "description": "Whether auto-UTM link decoration was applied." }, "unresolvedMergeTags": { "type": "array", "description": "Merge tags that rendered as an empty string. An unrecognized tag and a recognized but blank one are identical in the HTML, so this is the only way to tell them apart. Empty when every tag resolved.", "items": { "type": "object", "properties": { "tag": { "type": "string", "description": "Tag name as authored, without braces.", "example": "discountCode" }, "reason": { "type": "string", "enum": [ "unknown", "no_value" ], "description": "unknown - nothing provides this name, so it stays empty for every recipient. no_value - recognized or unverifiable, but blank for this contact. An unknown name is reported even when a default filter supplied text in its place, because that fallback then reaches every recipient while the rendered HTML looks correctly personalized; a recognized name that is merely blank for this contact is not reported when it has a default. A name is only called unknown when the render had a source to check it against. Without the contact's attributes nothing is checkable, since a bare {{plan}} reads the same attribute map as {{subscriber.plan}}, so pass a stored subscriberId or an inline subscriber with customAttributes. Beyond that, event.* needs sample event properties in variables, recommendedProducts.* needs a stored subscriberId the catalog has something to recommend for, and discount.* is only checkable on a sequence step whose incoming paths all run the same discount step. Rendering a transactional email is checkable only when variables is passed, since its tags come from the variables of each send call and carry no prefix marking them. Otherwise those tags land in no_value rather than in unknown. An optional attribute this contact never had set is kept out of unknown by checking the names other contacts in the account carry, which needs the subscribers:read scope; a key without it may report such a name as unknown." } }, "required": [ "tag", "reason" ] } }, "unevaluatedConditions": { "type": "array", "description": "Block conditions this render could not decide. Each was rendered as false, the same fail-closed rule a live send uses, so an else branch in the HTML is not evidence that the condition is false for a real recipient. Empty when every condition was actually evaluated.", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Condition field, such as tag or segment.", "example": "tag" }, "operator": { "type": "string", "example": "contains" }, "value": { "type": "string", "example": "extended" }, "description": { "type": "string", "description": "The condition in the words the dashboard uses.", "example": "Tag contains extended" }, "reason": { "type": "string", "enum": [ "requires_stored_subscriber", "invalid_filter", "evaluation_failed" ], "description": "requires_stored_subscriber - the field reads stored subscriber state, so pass subscriberId, or for a tag condition pass tags on the inline subscriber. invalid_filter - the stored condition is malformed, which fails closed on a real send too; hint carries the validation error. evaluation_failed - the lookup itself failed and the render is worth retrying." }, "hint": { "type": "string", "description": "What to change to get this condition evaluated." } }, "required": [ "field", "operator", "value", "description", "reason", "hint" ] } }, "entity": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "campaign", "sequence_step", "template" ] }, "id": { "type": "string" }, "variantId": { "type": [ "string", "null" ] } }, "required": [ "type", "id", "variantId" ] } }, "required": [ "success", "html", "subject", "previewText", "locale", "personalized", "trackingApplied", "unresolvedMergeTags", "unevaluatedConditions", "entity" ] }, "RequestValidationError": { "type": "object", "description": "Returned with status 422 when the request does not match the endpoint's field types, for example a missing required field, a value outside an allowed set, or a number sent as a string. Fix the field named in `property` and retry.", "properties": { "type": { "type": "string", "example": "validation" }, "on": { "type": "string", "description": "Request part that failed, such as `body` or `query`. A query parameter outside its numeric range reports `property` here, with `property` set to `root` and the parameter value in `found`.", "example": "body" }, "property": { "type": "string", "description": "JSON Pointer to the first failing field.", "example": "/enrollmentMode" }, "message": { "type": "string", "example": "Expected union value" }, "summary": { "type": "string", "description": "Readable description of the first failure.", "example": "Property 'enrollmentMode' must be one of: unlimited, one_time, matching_field" }, "found": { "description": "The request part as received, after unknown fields were removed." }, "errors": { "type": "array", "maxItems": 10, "description": "The first failures found, at most 10.", "items": { "type": "object", "properties": { "path": { "type": "string", "example": "/enrollmentMode" }, "message": { "type": "string" }, "summary": { "type": "string" }, "allowedValues": { "type": "array", "description": "Accepted values when the field takes a fixed set of values.", "items": {} } } } } } }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Error message" }, "code": { "type": "string", "description": "Optional stable machine-readable error discriminator when available.", "example": "COMPANY_CREATE_REQUIRES_PERSONAL_KEY" }, "retryable": { "type": "boolean", "description": "Whether retrying the request can recover from the error." }, "issues": { "type": "array", "description": "Field-level problems with the request, when the endpoint reports them. Up to ten entries; `error` summarizes the first three.", "items": { "$ref": "#/components/schemas/InputIssue" } } }, "required": [ "error" ] }, "InputIssue": { "type": "object", "properties": { "path": { "type": "string", "description": "Dotted field path, such as `audience.subscriberIds[0]`. Empty when the problem is with the request body itself.", "example": "kind" }, "message": { "type": "string", "description": "What is wrong with the field.", "example": "must be \"add_tags\"" }, "allowedValues": { "type": "array", "description": "Accepted values when the field only takes a fixed set of values.", "items": {}, "example": [ "add_tags" ] } }, "required": [ "path", "message" ] }, "SavedPopupTrigger": { "type": "object", "description": "When the popup opens. Merged key by key into the popup's current trigger.", "additionalProperties": true, "properties": { "type": { "type": "string", "enum": [ "delay", "scroll", "exit-intent", "click", "manual" ], "default": "delay" }, "delaySeconds": { "type": "integer", "minimum": 0, "maximum": 3600, "default": 5, "description": "Used when type is delay." }, "scrollPercent": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Used when type is scroll." }, "clickSelector": { "type": "string", "maxLength": 300, "description": "CSS selector of the element that opens the popup. Required when type is click." } } }, "SavedPopupTargeting": { "type": "object", "description": "Where the popup may show. Empty arrays mean no restriction. Merged key by key.", "additionalProperties": true, "properties": { "domains": { "type": "array", "maxItems": 50, "items": { "type": "string" } }, "paths": { "type": "array", "maxItems": 100, "items": { "type": "string" } }, "excludedPaths": { "type": "array", "maxItems": 100, "items": { "type": "string" } }, "device": { "type": "string", "enum": [ "all", "desktop", "mobile" ], "default": "all" } } }, "SavedPopupSchedule": { "type": "object", "description": "Optional run window. Use null on either key to clear it. Merged key by key.", "additionalProperties": true, "properties": { "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Must be later than startsAt." } } }, "SavedPopupFrequency": { "type": "object", "description": "How often one visitor sees the popup. Merged key by key.", "additionalProperties": true, "properties": { "maxDisplays": { "type": "integer", "minimum": 1, "maximum": 100, "default": 3 }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 365, "default": 7 } } }, "SavedPopupVisual": { "type": "object", "description": "Media panel and urgency treatment. Merged key by key.", "additionalProperties": true, "properties": { "style": { "type": "string", "enum": [ "none", "accent", "header", "rail", "image", "countdown" ], "default": "accent" }, "placement": { "type": "string", "enum": [ "top", "left", "center", "right" ], "default": "top" }, "imageUrl": { "type": [ "string", "null" ], "format": "uri" }, "imageAlt": { "type": "string", "maxLength": 160 }, "countdownMinutes": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10080 } } }, "SavedPopup": { "type": "object", "description": "A saved on-site signup popup.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "content": { "type": "object", "description": "Complete popup content - template, presentation, placement, theme, settings, trigger, targeting, schedule, frequency, visual, and blocks. Present on detail reads; omitted when listing unless `includeContent=true`.", "additionalProperties": true }, "viewCount": { "type": "integer", "description": "Times the popup was shown to a visitor." }, "startCount": { "type": "integer", "description": "Times a visitor began filling the popup in. Always between viewCount and conversionCount." }, "conversionCount": { "type": "integer", "description": "Times a visitor submitted the popup and became a subscriber." }, "stats": { "$ref": "#/components/schemas/SavedPopupStats" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri", "description": "Dashboard URL for this popup." } } }, "SavedPopupStats": { "type": "object", "description": "The popup funnel - shown, started, submitted - with rates derived from the raw counters. A rate is null rather than 0 when its denominator is zero, so \"nobody has seen it yet\" never reads as \"nobody converted\".", "properties": { "views": { "type": "integer" }, "starts": { "type": "integer" }, "conversions": { "type": "integer" }, "startRate": { "type": [ "number", "null" ], "description": "starts / views, 0-1. Null when the popup has no views." }, "conversionRate": { "type": [ "number", "null" ], "description": "conversions / views, 0-1. Null when the popup has no views." }, "completionRate": { "type": [ "number", "null" ], "description": "conversions / starts, 0-1. Null when nobody has started it." } } }, "SavedPopupEmbed": { "type": "object", "description": "Deployment snippets for a published popup. Present only when the popup is published; they contain no API key.", "properties": { "scriptUrl": { "type": "string", "format": "uri" }, "javascript": { "type": "string" }, "react": { "type": "string" }, "wordpress": { "type": "string" }, "shopify": { "type": "string" }, "supportedPlatforms": { "type": "array", "items": { "type": "string" } } } }, "ApiKeyMetadata": { "type": "object", "description": "Non-secret metadata for a company-scoped API key. Plain key values and stored hashes are never returned.", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "Non-secret key prefix for identifying the credential." }, "type": { "type": "string", "enum": [ "company" ] }, "scopes": { "type": [ "array", "null" ], "description": "Explicit permission scopes, or null for full access.", "items": { "type": "string" } }, "permissions": { "type": "object", "description": "Effective permission receipt for the key.", "additionalProperties": true }, "deviceName": { "type": [ "string", "null" ] }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "isCurrent": { "type": "boolean", "description": "Whether this is the credential authenticating the request." } }, "required": [ "id", "name", "prefix", "type", "scopes", "permissions", "deviceName", "lastUsedAt", "createdAt", "updatedAt", "isCurrent" ] }, "TransactionalSendIgnoredHeaders": { "type": "array", "description": "Entries in the request `headers` that the send was accepted without. Present only when at least one header was not applied. Idempotent replays report the ignored headers of the retried request. A retry that adds `headers` to a key first used without any replays the original send instead of returning 409.", "items": { "type": "object", "required": [ "name", "reason" ], "properties": { "name": { "type": "string", "description": "Header name as sent, or `*` when `headers` was not an object." }, "reason": { "type": "string", "enum": [ "invalid_headers", "invalid_name", "invalid_value", "duplicate", "reserved", "managed_in_marketing_mode", "requires_list_unsubscribe", "too_many_headers" ], "description": "Why the header was not applied." } } }, "example": [ { "name": "List-Unsubscribe", "reason": "managed_in_marketing_mode" } ] }, "TransactionalSendDiagnostics": { "type": "object", "description": "Non-blocking warnings about template variable issues. The send is still queued when this object is present, and missing values without defaults render as empty strings.", "properties": { "status": { "type": "string", "enum": [ "warning" ], "example": "warning" }, "message": { "type": "string", "example": "Email was queued. A required variable is missing and will render as an empty string." }, "missingRequiredVariables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "RESET_URL" }, "lookupName": { "type": "string", "example": "reset_url" }, "message": { "type": "string", "example": "Email was queued. Required variable \"RESET_URL\" is missing and will render as an empty string." }, "usedIn": { "type": "array", "items": { "type": "object", "properties": { "surface": { "type": "string", "enum": [ "subject", "previewText", "body", "block" ], "example": "block" }, "field": { "type": "string", "example": "url" }, "blockId": { "type": "string", "example": "reset-button" }, "blockType": { "type": "string", "example": "button" } } } }, "suggestions": { "type": "array", "items": { "type": "string" }, "example": [ "resetpasswordlink" ] } } } }, "unusedVariables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "resetpasswordlink" }, "message": { "type": "string", "example": "Variable \"resetpasswordlink\" was provided but is not used by the email template." }, "suggestions": { "type": "array", "items": { "type": "string" }, "example": [ "reset_url" ] } } } } }, "required": [ "status", "message", "missingRequiredVariables", "unusedVariables" ] }, "CommerceCustomer": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "buyer@example.com" }, "externalId": { "type": "string", "description": "Customer-owned app/customer/user ID", "example": "user_123" }, "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "attributes": { "type": "object", "additionalProperties": true, "description": "Custom subscriber attributes to merge into the profile. Synced to ClickHouse for segment filtering.", "example": { "acquisitionChannel": "tiktok", "country": "US" } } } }, "CommerceOrderItem": { "type": "object", "required": [ "productId", "title", "quantity" ], "properties": { "productId": { "type": "string", "description": "Your product identifier (same value used when upserting products)", "example": "SKU-PROTEIN-1KG" }, "variantId": { "type": [ "string", "null" ], "description": "Your variant identifier within the product", "example": "SKU-PROTEIN-1KG-VANILLA" }, "sku": { "type": [ "string", "null" ], "example": "VANILLA-1KG" }, "title": { "type": "string", "example": "Protein Powder" }, "variantTitle": { "type": [ "string", "null" ], "example": "Vanilla" }, "quantity": { "type": "integer", "minimum": 0, "example": 1 }, "priceCents": { "type": [ "integer", "null" ], "description": "Unit price in cents", "example": 8850 } } }, "CommerceProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal Sequenzy product ID" }, "productId": { "type": [ "string", "null" ], "description": "Your product identifier (providerProductId)", "example": "SKU-PROTEIN-1KG" }, "providerProductId": { "type": [ "string", "null" ], "description": "Provider product identifier", "example": "prod_ABC123" }, "provider": { "type": "string", "enum": [ "api", "stripe", "shopify", "woocommerce", "manual" ], "example": "api" }, "title": { "type": "string", "example": "Protein Powder" }, "description": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "price": { "type": [ "integer", "null" ], "description": "Unit price in cents", "example": 8850 }, "priceCents": { "type": [ "integer", "null" ], "example": 8850 }, "compareAtPrice": { "type": [ "integer", "null" ] }, "compareAtPriceCents": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ], "example": "USD" }, "inStock": { "type": "boolean" }, "providerCreatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Product creation time reported by the source catalog. Used for newest-product ranking." }, "digitalDelivery": { "$ref": "#/components/schemas/ProductDigitalDelivery" }, "variants": { "type": "array", "description": "For Stripe products, every active Stripe price of the product (variantId is the Stripe price ID).", "items": { "type": "object", "properties": { "variantId": { "type": "string" }, "title": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "priceCents": { "type": [ "integer", "null" ] }, "compareAtPriceCents": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ], "description": "The variant's own currency. Stripe products can have active prices in several currencies, so this can differ from the product-level currency.", "example": "USD" }, "imageUrl": { "type": [ "string", "null" ] }, "inStock": { "type": "boolean" }, "inventoryQuantity": { "type": [ "integer", "null" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AgentFriendlyError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "string", "description": "Stable machine-readable error code.", "example": "SEGMENT_NAME_ALREADY_EXISTS" }, "error": { "type": "string", "description": "Short error label.", "example": "Segment name already exists" }, "title": { "type": "string", "description": "UI-friendly title.", "example": "Segment name already exists" }, "description": { "type": "string", "description": "Agent-friendly explanation of why the request failed.", "example": "A saved segment with this name already exists in this company." }, "resolution": { "type": "string", "description": "Concrete next step for humans or AI agents.", "example": "Call list_segments before creating, reuse the existing segment id, or retry with a different name." }, "docsUrl": { "type": "string", "format": "uri", "description": "Documentation URL for the failed operation.", "example": "https://docs.sequenzy.com/api-reference/segments/create" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "success", "code", "error", "title", "description", "resolution", "docsUrl" ] }, "EngagementStats": { "type": "object", "description": "Unified engagement metrics returned by analytics endpoints. When a period or start/end filter is applied these are a funnel over the sends made inside that window, not a log of events inside it: every delivery, engagement, and reply count is attributed to one of those sends, including activity that arrives after the window closes, so opened <= delivered <= sent always holds and no rate can exceed 100%. conversions and revenueCents are the exception and use the goal's own last-touch attribution window. Open and click metrics exclude detected scanner, preview, and tracked asset events unless includeMachineEngagement is true.", "properties": { "sent": { "type": "integer" }, "delivered": { "type": "integer", "description": "Capped at sent count" }, "bounced": { "type": "integer", "description": "Unique bounces (deduplicated by email send)" }, "opened": { "type": "integer", "description": "Unique opens (deduplicated by email send)" }, "clicked": { "type": "integer", "description": "Unique clicks (deduplicated by email send)" }, "replies": { "type": "integer", "description": "Inbound replies captured for delivered emails" }, "unsubscribed": { "type": "integer" }, "deliveryRate": { "type": "number", "description": "Percentage (0-100)" }, "bounceRate": { "type": "number", "description": "Percentage (0-100), calculated from sent emails" }, "rateDenominator": { "type": "integer", "description": "The number every engagement rate divides by: delivered, falling back to sent when no delivery events were recorded, and 0 when nothing was sent" }, "rateDenominatorBasis": { "type": "string", "enum": [ "delivered", "sent", "none" ], "description": "Which field rateDenominator was taken from" }, "openRate": { "type": "number", "description": "Percentage (0-100), opened / rateDenominator" }, "clickRate": { "type": "number", "description": "Percentage (0-100), clicked / rateDenominator" }, "replyRate": { "type": "number", "description": "Percentage (0-100), replies / rateDenominator" }, "unsubscribeRate": { "type": "number", "description": "Percentage (0-100), unsubscribed / rateDenominator" }, "conversions": { "type": "integer", "description": "Attributed goal conversions (last-touch, 24h window). Only returned by campaign and sequence metrics endpoints." }, "revenueCents": { "type": "integer", "description": "Attributed revenue in cents from purchase events (saas.purchase and ecommerce.order_placed). Only returned by campaign and sequence metrics endpoints." } } }, "SequenceEnrollmentCounts": { "type": "object", "description": "Point-in-time counts of active and waiting enrollment tokens for a sequence. This live snapshot is not limited by historical period, start, or end filters. Counts represent enrollment runs, not necessarily distinct subscribers.", "required": [ "active", "waiting", "total", "byCurrentNode" ], "properties": { "active": { "type": "integer", "description": "Active enrollment-token count." }, "waiting": { "type": "integer", "description": "Waiting enrollment-token count." }, "total": { "type": "integer", "description": "Total active plus waiting enrollment-token count." }, "byCurrentNode": { "type": "array", "description": "Active and waiting enrollment counts grouped by current sequence node.", "items": { "type": "object", "required": [ "currentNodeId", "currentNodeMissing", "active", "waiting", "total" ], "properties": { "currentNodeId": { "type": "string", "description": "Current sequence node ID." }, "currentNodeType": { "type": "string", "description": "Current sequence node type. Omitted when the node no longer exists in the graph." }, "currentNodeLabel": { "type": "string", "description": "Current sequence node label or email subject when available." }, "currentNodeMissing": { "type": "boolean", "description": "Whether the current node no longer exists in the sequence graph." }, "active": { "type": "integer", "description": "Active enrollment-token count at this node." }, "waiting": { "type": "integer", "description": "Waiting enrollment-token count at this node." }, "total": { "type": "integer", "description": "Total active plus waiting enrollment-token count at this node." } } } } } }, "TransactionalMetricsResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "period": { "type": "string" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "transactional": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "stats": { "allOf": [ { "$ref": "#/components/schemas/EngagementStats" }, { "type": "object", "properties": { "complaints": { "type": "integer" }, "complaintRate": { "type": "number", "format": "float" } } } ] }, "complaints": { "type": "object", "properties": { "count": { "type": "integer" }, "rate": { "type": "number", "format": "float" } } }, "clickedLinks": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "clicks": { "type": "integer" }, "percentage": { "type": "number", "format": "float" } } } }, "bounceBreakdown": { "type": "object", "properties": { "permanent": { "type": "integer" }, "transient": { "type": "integer" }, "undetermined": { "type": "integer" }, "subtypes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Permanent", "Transient", "Undetermined" ] }, "subType": { "type": [ "string", "null" ] }, "count": { "type": "integer" } } } } } }, "engagementBreakdown": { "type": "object", "properties": { "human": { "type": "object", "properties": { "opens": { "type": "integer" }, "clicks": { "type": "integer" } } }, "machine": { "type": "object", "properties": { "opens": { "type": "integer" }, "clicks": { "type": "integer" } } } } } } }, "CommerceValueForecast": { "type": "object", "description": "Explainable commerce forecast derived from up to two years of provider-neutral placed-order events.", "properties": { "status": { "type": "string", "enum": [ "ready", "insufficient_data" ] }, "generatedAt": { "type": "string", "format": "date-time" }, "modelVersion": { "type": "string", "example": "cohort-rfm-v1" }, "currency": { "type": [ "string", "null" ] }, "confidence": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", null ] }, "isSampled": { "type": "boolean" }, "eligibility": { "type": "object", "properties": { "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "current": { "type": "number" }, "required": { "type": "number" } } } } } }, "history": { "type": "object", "properties": { "orderCount": { "type": "integer" }, "customerCount": { "type": "integer" }, "repeatCustomerCount": { "type": "integer" }, "historyDays": { "type": "integer" }, "daysSinceLastOrder": { "type": "integer" }, "excludedCurrencyOrderCount": { "type": "integer" } } }, "actual": { "type": "object", "properties": { "averageOrderValueCents": { "type": [ "integer", "null" ] }, "averageCustomerValueCents": { "type": [ "integer", "null" ] }, "repeatPurchaseRate": { "type": [ "number", "null" ] } } }, "forecast": { "type": [ "object", "null" ], "properties": { "predictedAverageOrderValueCents": { "type": "integer" }, "predictedAverageOrderValueRange": { "$ref": "#/components/schemas/CommerceForecastRange" }, "predictedCustomerValue365DaysCents": { "type": "integer" }, "predictedCustomerValue365DaysRange": { "$ref": "#/components/schemas/CommerceForecastRange" }, "expectedOrders90Days": { "type": "number" }, "expectedRevenue90DaysCents": { "type": "integer" }, "expectedRevenue90DaysRange": { "$ref": "#/components/schemas/CommerceForecastRange" } } } } }, "CommerceForecastRange": { "type": "object", "properties": { "lowCents": { "type": "integer" }, "highCents": { "type": "integer" } } }, "ClickedLink": { "type": "object", "description": "One destination URL from the campaign's per-link click breakdown. Returned as a top-level `clickedLinks` array by the campaign metrics endpoint when the campaign has tracked link clicks.", "properties": { "url": { "type": "string", "description": "The clicked destination URL as sent in the email." }, "clicks": { "type": "integer", "description": "Number of recorded clicks on this URL." }, "percentage": { "type": "number", "description": "This link's share of every recorded link click (0-100), including links beyond the returned top 20." } } }, "RecommendationMetrics": { "type": "object", "description": "Product recommendation funnel for a campaign or sequence. Returned as a top-level `recommendations` object when recommendation blocks were rendered. The requested period or custom time range scopes impressions and clicks. Orders and revenue are attributed when a subscriber buys a recommended product within 7 days of a scoped click.", "properties": { "impressions": { "type": "integer", "description": "Total recommended products rendered across all sends." }, "recipients": { "type": "integer", "description": "Unique subscribers shown at least one recommendation." }, "clicks": { "type": "integer", "description": "Recorded clicks on recommended products." }, "clickers": { "type": "integer", "description": "Unique subscribers who clicked a recommendation." }, "orders": { "type": "integer", "description": "Orders containing a clicked recommended product." }, "revenueCents": { "type": "integer", "description": "Legacy sum of attributed order minor units across currencies. Use revenueByCurrency for display or financial analysis." }, "revenueByCurrency": { "type": "array", "description": "Currency-safe attributed revenue totals. UNKNOWN identifies orders whose source event omitted currency.", "items": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 code or UNKNOWN." }, "revenueCents": { "type": "integer", "description": "Attributed revenue in this currency's minor units." } } } }, "topProducts": { "type": "array", "description": "Per-product impressions and clicks, most clicked first.", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "Commerce provider (shopify, woocommerce, ...)." }, "providerProductId": { "type": "string", "description": "Product ID in the provider's catalog." }, "impressions": { "type": "integer" }, "clicks": { "type": "integer" } } } } } }, "PollResultsSummary": { "type": "object", "description": "Aggregated poll / NPS answers for one poll block. Each subscriber counts once per block using their latest answer; multi-select polls (allowMultiple) count each subscriber once per selected option, so answer percentages can sum past 100. Returned as a top-level `polls` array by the campaign metrics endpoint when the campaign collected poll responses.", "properties": { "blockId": { "type": "string", "description": "Poll block id inside the email content." }, "variant": { "type": "string", "enum": [ "options", "nps" ] }, "allowMultiple": { "type": "boolean", "description": "Present and true for multi-select polls, where recipients save a set of options from the hosted selection page and the attribute stores the list of selected values." }, "question": { "type": "string" }, "attributeKey": { "type": "string", "description": "Subscriber attribute key where the current/latest response is stored. A later poll that reuses this key can overwrite it, so use a campaign-and-block-scoped pollResponse subscriber filter for an exact historical respondent drill-down. Omitted when the recorded responses carry no valid key." }, "totalResponses": { "type": "integer", "description": "Number of respondents (subscribers whose latest answer selects at least one option; a cleared multi-select submit counts as no answer). Also the percentage denominator." }, "answers": { "type": "array", "description": "Ordered by responses (options) or by score 0-10 (NPS, zero-filled).", "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "Human-readable answer label captured when the response was recorded." }, "value": { "type": "string", "description": "Stable stored answer value. Use this field as the answer identifier when labels can change." }, "responses": { "type": "integer" }, "percentage": { "type": "number", "description": "Share of the poll's respondents (0-100, one decimal). Sums can exceed 100 for multi-select polls." } } } }, "nps": { "type": "object", "description": "Present for NPS polls only.", "properties": { "score": { "type": "integer", "description": "Net Promoter Score (-100 to 100)" }, "average": { "type": "number" }, "promoters": { "type": "integer" }, "passives": { "type": "integer" }, "detractors": { "type": "integer" } } } } }, "EmailEvent": { "type": "object", "properties": { "id": { "type": "string" }, "emailSendId": { "type": "string" }, "companyId": { "type": "string" }, "campaignId": { "type": [ "string", "null" ], "description": "Campaign ID for campaigns, or automation email node ID for sequence events." }, "transactionalEmailId": { "type": [ "string", "null" ] }, "subscriberId": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "emailName": { "type": [ "string", "null" ] }, "emailType": { "type": [ "string", "null" ], "enum": [ "campaign", "sequence", "transactional", null ] }, "abTestId": { "type": [ "string", "null" ] }, "abTestVariantId": { "type": [ "string", "null" ] }, "eventType": { "type": "string", "enum": [ "send", "delivery", "bounce", "complaint", "open", "click", "unsubscribe", "delivery_delay", "transport_failure" ] }, "bounceType": { "type": [ "string", "null" ] }, "bounceSubType": { "type": [ "string", "null" ] }, "complaintType": { "type": [ "string", "null" ] }, "clickedUrl": { "type": [ "string", "null" ] }, "ipAddress": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] }, "countryCode": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "eventTime": { "type": "string", "format": "date-time" } } }, "PollResponse": { "type": "object", "description": "One respondent's latest answer to one Poll or NPS block.", "properties": { "subscriberId": { "type": "string" }, "email": { "type": [ "string", "null" ], "description": "Null when the subscriber has since been deleted." }, "externalId": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "blockId": { "type": "string", "description": "Poll block ID inside the email content." }, "variant": { "type": "string", "enum": [ "options", "nps" ] }, "question": { "type": "string" }, "attributeKey": { "type": [ "string", "null" ], "description": "Subscriber attribute the answer was stored under." }, "allowMultiple": { "type": "boolean", "description": "Whether the poll accepted several selections." }, "answers": { "type": "array", "description": "Selected option labels. One entry, or several for a multi-select poll.", "items": { "type": "string" } }, "values": { "type": "array", "description": "Stored values parallel to `answers`.", "items": { "type": "string" } }, "respondedAt": { "type": "string", "format": "date-time" } } }, "ShopifyBrowseAbandonmentSettings": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Whether browse-abandonment events fire for this store (default true)." }, "delayHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 168, "description": "Hours to wait after a product view before the abandonment check (default 2, max 168)." }, "cooldownHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 720, "description": "Minimum hours between browse-abandoned events per subscriber (default 24, max 720)." } } }, "ShopifyCartAbandonmentSettings": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Whether cart-abandonment events fire for this store (default true)." }, "delayHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 168, "description": "Hours of cart inactivity before the cart counts as abandoned (default 1, max 168)." }, "cooldownHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 720, "description": "Minimum hours between cart-abandoned events per subscriber (default 24, max 720)." }, "expireAfterHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 720, "description": "Hours after which an untouched tracked cart is dropped instead of being emailed about or merged into by a later add (default 72, max 720). A store can empty a cart without sending a removal - a session or reservation timing out, an inventory hold releasing, checkout finishing on another device - and past this window the snapshot is no longer treated as evidence the shopper still has those items. Set it below delayHours on stores whose carts expire faster than the abandonment delay: those carts are then intentionally never emailed about." } } }, "ShopifyPriceDropSettings": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Whether price-drop events fire for this store (default true)." }, "minPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 95, "description": "Minimum price decrease percent to alert on (default 5, max 95)." }, "lookbackDays": { "type": "number", "exclusiveMinimum": 0, "maximum": 90, "description": "How many days back product viewers qualify as the audience (default 30, max 90)." }, "cooldownDays": { "type": "number", "exclusiveMinimum": 0, "maximum": 90, "description": "Minimum days between price-drop events per subscriber and product (default 7, max 90)." } } }, "EmailDesignSystem": { "type": "object", "description": "The visual identity every AI-generated email renders inside, parsed from the company's design direction text.", "required": [ "version", "designCode", "compositionSpine", "source" ], "properties": { "version": { "type": "integer", "example": 1 }, "designCode": { "type": "object", "description": "The locked visual grammar applied to every generated email.", "required": [ "version", "kickerStyle", "titleAlignment", "buttonShape", "dividerStyle", "density", "openerTreatments" ], "properties": { "version": { "type": "integer", "example": 1 }, "kickerStyle": { "type": "string", "enum": [ "chip", "letterspaced", "none" ] }, "titleAlignment": { "type": "string", "enum": [ "left", "center" ] }, "buttonShape": { "type": "string", "enum": [ "rounded", "pill" ] }, "dividerStyle": { "type": "string", "enum": [ "line", "space" ] }, "density": { "type": "string", "enum": [ "airy", "compact" ] }, "openerTreatments": { "type": "array", "items": { "type": "string", "enum": [ "hero-image", "hero-color", "header-hero", "editorial-masthead", "title-led" ] } } } }, "compositionSpine": { "type": "string", "enum": [ "hero-led", "editorial", "product-spec" ], "description": "Which worked-example skeleton anchors email composition." }, "source": { "type": "string", "enum": [ "derived", "custom" ], "description": "derived when every token comes from brand derivation; custom when the direction text carries the identity." } } }, "SyncRule": { "type": "object", "required": [ "triggerEvent", "actions" ], "properties": { "triggerEvent": { "type": "string", "description": "Event name that triggers the rule.", "example": "ecommerce.order_placed" }, "actions": { "type": "object", "required": [ "addTags", "removeTags" ], "properties": { "addTags": { "type": "array", "items": { "type": "string" }, "example": [ "vinyl-collector" ] }, "removeTags": { "type": "array", "items": { "type": "string" }, "example": [] } } }, "conditions": { "type": "object", "description": "Optional conditions that must all hold for the rule to apply.", "properties": { "requiresTags": { "type": "array", "description": "Rule only applies if the subscriber has ALL of these tags.", "items": { "type": "string" } }, "requiresNotTags": { "type": "array", "description": "Rule only applies if the subscriber has NONE of these tags.", "items": { "type": "string" } }, "purchasedProduct": { "type": "object", "description": "For commerce events with product context - rule only applies when a product on the event matches every specified selector (values within a selector are OR'd).", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "collectionIds": { "type": "array", "items": { "type": "string" } }, "productTypes": { "type": "array", "items": { "type": "string" } }, "vendors": { "type": "array", "items": { "type": "string" } } } } } } } }, "Company": { "type": "object", "properties": { "id": { "type": "string", "example": "company_abc123" }, "name": { "type": "string", "example": "Acme Inc" }, "description": { "type": [ "string", "null" ], "example": "Lifecycle email automation for SaaS teams." }, "status": { "type": "string", "example": "ready" }, "websiteUrl": { "type": [ "string", "null" ], "example": "acme.com" }, "logoUrl": { "type": [ "string", "null" ], "example": "https://example.com/logo.png" }, "founderName": { "type": [ "string", "null" ], "example": "Sarah" }, "primaryColor": { "type": [ "string", "null" ], "example": "#0ea5e9" }, "brandColors": { "type": [ "object", "null" ], "additionalProperties": true, "example": { "primary": "#0ea5e9" } }, "valueProps": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true }, "example": [ { "title": "Fast setup", "description": "Launch lifecycle emails in minutes." } ] }, "testimonials": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "toneVoice": { "type": [ "string", "null" ], "example": "clear, direct, warm" }, "companyContext": { "type": [ "string", "null" ], "example": "Acme helps SaaS teams send lifecycle emails from product events." }, "emailDesignPrompt": { "type": [ "string", "null" ], "description": "Art direction for AI-designed emails: layout, density, which sections belong in an email, imagery, and CTA prominence. `toneVoice` steers copy; this steers design. When empty, the next email generation prefills it with the direction derived from the brand.", "example": "Editorial and calm. One idea per email, no feature grids." }, "emailLengthPreference": { "type": "string", "enum": [ "concise", "balanced", "detailed" ], "description": "How long AI-written email copy should be. New workspaces default to `concise`.", "example": "concise" }, "socialLinks": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "privacyPolicyUrl": { "type": [ "string", "null" ] }, "termsUrl": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri", "description": "Dashboard edit URL for this campaign.", "example": "https://sequenzy.com/dashboard/company/comp_abc123/campaign/camp_abc123" }, "previewUrl": { "type": "string", "format": "uri", "description": "Dashboard review/preview URL for this campaign.", "example": "https://sequenzy.com/dashboard/company/comp_abc123/campaign/camp_abc123?step=review" }, "language": { "type": "string", "example": "en" }, "pricing": { "type": [ "object", "null" ], "additionalProperties": true }, "fontFamily": { "type": [ "string", "null" ] }, "emailTheme": { "type": [ "object", "null" ], "additionalProperties": true }, "emailDirection": { "type": "string", "example": "ltr" }, "emailLocalizationConfig": { "type": "object", "additionalProperties": true }, "defaultSubscriberListIds": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Workspace default lists new contacts join when nothing targets them explicitly. null means every current and future list, [] means no list at all, and an array means exactly those lists.", "example": [ "list_abc123" ] }, "emailBranding": { "type": "object", "readOnly": true, "required": [ "visible", "removalEntitled", "reason", "managedBy", "removalAction", "subscriptionTier", "subscriptionStatus", "subscriptionUrl" ], "description": "Effective \"Sent with Sequenzy\" entitlement for future renders and sends. This is derived from the company owner's subscription and is not an editable footer field. Existing live sequences pick up an entitlement change without their stored email blocks changing.", "properties": { "visible": { "type": "boolean", "description": "Whether Sequenzy branding is added to outgoing email." }, "removalEntitled": { "type": "boolean", "description": "Whether the current owner subscription removes branding." }, "reason": { "type": "string", "enum": [ "free_plan", "paid_plan", "email_partner", "inactive_subscription", "company_not_found" ] }, "managedBy": { "type": "string", "enum": [ "owner_subscription" ] }, "removalAction": { "type": "string", "enum": [ "none", "upgrade", "renew_subscription" ] }, "subscriptionTier": { "type": [ "string", "null" ], "enum": [ "free", "pro_1k", "pro_5k", "pro_10k", "pro_25k", "pro_30k", "pro_50k", "pro_100k", "pro_150k", "pro_2m", "pro_3m", "pro_4m", "pro_5m", "enterprise", null ] }, "subscriptionStatus": { "type": [ "string", "null" ], "enum": [ "active", "past_due", "canceled", "trialing", "incomplete", null ] }, "subscriptionUrl": { "type": "string", "format": "uri", "description": "Owner-facing subscription, upgrade, and billing-management page." } } }, "defaultSenderProfileId": { "type": [ "string", "null" ] }, "defaultFromName": { "type": [ "string", "null" ] }, "defaultFromEmail": { "type": [ "string", "null" ], "format": "email" }, "defaultReplyProfileId": { "type": [ "string", "null" ] }, "defaultReplyToName": { "type": [ "string", "null" ] }, "defaultReplyToEmail": { "type": [ "string", "null" ], "format": "email" }, "replyTrackingEnabled": { "type": "boolean", "description": "Whether inbound reply capture is enabled for this company." }, "replyTrackingDomainMode": { "type": "string", "enum": [ "sequenzy", "custom" ], "description": "Whether reply capture uses Sequenzy's managed inbound domain or a configured custom domain." }, "forwardReplies": { "type": "boolean", "description": "Whether captured replies are forwarded to the configured mailbox." }, "replyRetentionDays": { "type": "integer", "readOnly": true, "description": "Current reply retention period in days." } } }, "Website": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string", "example": "mail.example.com" }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "failed", "misconfigured" ], "example": "pending", "description": "Stored DNS verification status. This does not imply that a sending transport is ready." }, "dnsVerified": { "type": "boolean", "description": "Whether the customer DNS records are verified." }, "readyToSend": { "type": "boolean", "description": "Whether the domain is fully ready to send (DNS verified and activation finished)." }, "readiness": { "type": "object", "description": "Customer-facing sending readiness. When readyToSend is false, reason says why; dns_* reasons describe your DNS records, while activation reasons resolve on Sequenzy's side.", "properties": { "status": { "type": "string", "enum": [ "setup_required", "verifying_dns", "activating", "ready", "blocked" ] }, "reason": { "type": [ "string", "null" ], "enum": [ "dns_not_started", "dns_pending", "dns_failed", "activation_pending", "activation_failed", "sending_unavailable", null ] } } }, "message": { "type": "string", "description": "Creation or setup summary when returned by a mutating operation." }, "dnsRecords": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The DNS records to publish and their per-record verification status. Custom reply routing is independent of sending readiness. GET returns stored results; POST verify performs a fresh check.", "properties": { "inboundVerificationRecord": { "type": "object", "readOnly": true, "description": "Optional public TXT record for an existing reply hostname outside its verified sending domain. Verification prepares this after the inbound MX verifies. Publish the exact value at the fully qualified name, then verify again. Absence can mean verification is already covered, preparation has not run, or preparation failed; inspect inboundRoutingStatus/error. This generated field cannot be set or cleared through the website API.", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "example": "_amazonses.inbound.example.com" }, "value": { "type": "string", "description": "Public domain-ownership token, not an API credential." } } }, "inboundVerificationStatus": { "type": "string", "enum": [ "pending", "verified", "misconfigured" ], "readOnly": true, "description": "Stored receiving-domain ownership status, absent before it has been checked. Pending is not active routing. Existing sending-domain verification can satisfy ownership without an additional TXT record." }, "inboundRoutingStatus": { "type": "string", "enum": [ "pending", "active", "failed" ], "readOnly": true, "description": "Customer-facing reply readiness from stored checks, returned when an inbound MX record exists. SES routes require verified MX, receiving ownership, and an active receiving rule. Unchecked legacy SES routes display pending; retained MTA reply routes keep their existing status. Inconclusive ownership checks preserve the underlying route and previously confirmed ownership, with an error for retry." }, "inboundRoutingError": { "type": [ "string", "null" ], "readOnly": true, "description": "Last reply-routing error and recovery instruction. Null when there is no stored error; omitted when no inbound MX record exists. Retry verification after correcting DNS or a temporary provider failure." }, "trackingRecord": { "type": "object", "readOnly": true, "description": "CNAME record for the company tracking domain, present when the company has one. It is optional and never gates verification or sending; publish it with the other records to brand tracked links. Proxying must be off.", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "example": "links.example.com" }, "value": { "type": "string", "example": "links1.sequenzydns.com" } } }, "trackingStatus": { "type": [ "string", "null" ], "enum": [ "not_started", "pending", "verified", "failed", null ], "readOnly": true, "description": "Verification status of trackingRecord, including its HTTPS certificate. Informational; it never affects the domain's status." } } }, "tracking": { "type": "object", "readOnly": true, "description": "Link tracking for this domain. Every sending domain uses the company tracking domain, which never gates verification or sending; until it verifies, links use the shared Sequenzy tracking domain. Manage it with the Tracking Domain endpoints.", "properties": { "policy": { "type": "string", "enum": [ "required", "legacy" ], "deprecated": true, "description": "Always legacy. Kept for compatibility." }, "required": { "type": "boolean", "deprecated": true, "description": "Always false; tracking never gates sending. Kept for compatibility." }, "hostname": { "type": [ "string", "null" ], "description": "The company tracking hostname, or null when links use the shared Sequenzy tracking domain.", "example": "links.example.com" }, "status": { "type": [ "string", "null" ], "enum": [ "not_started", "pending", "verified", "failed", null ], "description": "Verification status of hostname, including HTTPS. not_started until you confirm DNS setup with Verify Sending Domain or check it with Verify Tracking Domain." }, "ready": { "type": "boolean", "description": "Whether hostname is verified and serving HTTPS." }, "error": { "type": [ "string", "null" ], "description": "Last tracking verification error, if any." }, "cnameRecord": { "type": [ "object", "null" ], "description": "The CNAME to publish for hostname.", "properties": { "type": { "type": "string", "enum": [ "CNAME" ] }, "name": { "type": "string", "example": "links.example.com" }, "value": { "type": "string", "example": "links1.sequenzydns.com" } } } } }, "dkim": { "type": "object", "additionalProperties": true, "description": "Normalized DKIM type, status, and diagnostics." }, "spf": { "type": "object", "additionalProperties": true, "description": "Normalized SPF status, expected record, and diagnostics." }, "mailFrom": { "type": "object", "additionalProperties": true, "description": "Normalized custom MAIL FROM MX status and diagnostics." }, "lastVerifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "nextVerificationAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "SubscriberList": { "type": "object", "properties": { "id": { "type": "string", "example": "list_abc123" }, "name": { "type": "string", "example": "Newsletter Subscribers" }, "description": { "type": [ "string", "null" ], "description": "Internal workspace metadata returned only through authenticated list-management surfaces. Never shown in hosted or embedded subscriber preferences." }, "isPrivate": { "type": "boolean", "description": "Whether the list is private. Private lists are hidden unless allowMemberUnsubscribe is enabled, in which case current members can see the name and opt out. Private lists cannot be joined through preferences. Descriptions remain internal; global unsubscribe still applies.", "example": false }, "allowMemberUnsubscribe": { "type": "boolean", "default": false, "description": "Whether current members of a private list can see its name and unsubscribe in preferences. Does not allow joining or rejoining. No effect on public lists." }, "createdAt": { "type": "string", "format": "date-time" }, "subscriberCount": { "type": "integer", "description": "Current list members of any status. Memberships with unsubscribedAt set are excluded." }, "activeSubscriberCount": { "type": "integer", "description": "Current list members with status=active. May include phone-only contacts without an email address." } } }, "TagDefinition": { "type": "object", "properties": { "id": { "type": "string", "example": "tag_abc123" }, "name": { "type": "string", "example": "premium" }, "color": { "type": [ "string", "null" ], "example": "#f97316" }, "isSystem": { "type": "boolean", "example": false } } }, "EmailPreset": { "type": [ "string", "null" ], "enum": [ "branded", "minimal", null ], "description": "Per-email Style > Format, derived from the stored blocks. `branded` renders the company logo and the full footer; `minimal` renders no logo and the simple footer. Null when the entire email is a single raw HTML block, which has no Sequenzy format. Sequence steps, campaigns, transactional templates, and saved templates all report this field, so chrome can be compared across emails without rendering them.", "example": "branded" }, "CampaignChannel": { "type": "string", "enum": [ "email", "sms" ], "description": "Delivery channel. SMS campaigns are created and managed from the dashboard: they carry no email, so `subject` and `blocks` come back empty, and the email-only endpoints (update, schedule, pause, resume, duplicate, resend to non-openers) reject them. Campaign stats and campaign events reject them too, since both read email engagement.", "example": "email" }, "CampaignStatus": { "type": "string", "enum": [ "draft", "scheduled", "waiting_approval", "rejected", "sending", "paused", "sent", "cancelled" ], "description": "Campaign status. `waiting_approval` means the campaign is held for safety review and is not sending; this is most common on new accounts and recently registered sending domains. See https://docs.sequenzy.com/concepts/campaigns#safety-review", "example": "draft" }, "CampaignSummary": { "type": "object", "properties": { "id": { "type": "string", "example": "camp_abc123" }, "name": { "type": "string", "example": "April Launch" }, "type": { "$ref": "#/components/schemas/CampaignChannel" }, "subject": { "type": "string", "example": "A quick update" }, "emailId": { "type": [ "string", "null" ], "description": "The linked email body. The same record is returned by the templates endpoints and can be passed as `templateId` when creating campaigns to reuse the design. Null for SMS campaigns.", "example": "email_abc123" }, "emailPreset": { "allOf": [ { "$ref": "#/components/schemas/EmailPreset" } ], "description": "Style > Format of the linked email. Null for SMS campaigns and for an email stored as a single raw HTML block." }, "hasAudience": { "type": "boolean", "description": "Whether an explicit audience is configured. False for unset or empty selections. This does not validate resource existence or count eligible recipients. Draft rows can use this for an Audience set indicator." }, "status": { "$ref": "#/components/schemas/CampaignStatus" }, "rejectionComment": { "type": [ "string", "null" ], "description": "Reviewer feedback when the campaign status is rejected. Stays null while a campaign is still in waiting_approval." }, "trackingCode": { "type": [ "string", "null" ], "description": "Campaign tracking code available to UTM templates as `{{campaign.trackingCode}}`." }, "labels": { "type": "array", "description": "Label names assigned to this campaign.", "items": { "type": "string" }, "example": [ "edm", "api" ] }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "For native sends, when the send finished. It is stamped after the last recipient is handed off, so for a spread or optimal-time send this is the end of the delivery window rather than when sending started. Imported campaigns retain the source provider's timestamp." }, "createdAt": { "type": "string", "format": "date-time" }, "spreadOverHours": { "type": [ "integer", "null" ], "description": "Hours the send was (or will be) spread over. Null means there is no fixed spread; inspect sendTimeOptimization to distinguish an optimal-time send from a campaign with no recorded pacing. Imported campaigns may not include source-provider pacing data.", "example": 6 }, "sendTimeOptimization": { "type": "boolean", "description": "Whether each recipient is sent at their best predicted open time. Campaign-only: there is no company or sequence STO setting. Sequences use sendingWindow instead. Always false when spreadOverHours is set: setting a spread clears send time optimization." }, "sendTimeWindowHours": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 24, "description": "Window send time optimization may deliver within, in hours from scheduledAt. Defaults to 12 and only applies when sendTimeOptimization is true.", "example": 12 }, "sendInRecipientTimezone": { "type": "boolean", "description": "Whether the campaign is delivered at the scheduled wall-clock time in each recipient's timezone." }, "scheduledTimezone": { "type": [ "string", "null" ], "maxLength": 64, "description": "Stored IANA timezone that anchors the campaign's scheduled wall-clock time. Use sendInRecipientTimezone to determine whether recipient-timezone delivery is enabled; this value may remain set when that mode is disabled.", "example": "America/New_York" }, "maxRecipients": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000000, "description": "Recipient cap applied when the audience is resolved at send time. The first N matching subscribers (by subscriber id) receive the campaign after every audience and suppression rule; recipients already reached count against the cap when a paused send resumes. Null means the whole audience is targeted.", "example": null } } }, "ResolvedAudienceEntity": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ], "description": "Null when the referenced list or segment no longer exists." }, "missing": { "type": "boolean", "description": "True when the ID points at a deleted or cross-company record." } } }, "ResolvedAudienceRule": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "all", "lists", "segments", "filtered" ] }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedAudienceEntity" } }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedAudienceEntity" } }, "filters": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "ResolvedCampaignAudience": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "unset", "all", "lists", "segment", "filtered", "rules" ] }, "summary": { "type": "string", "description": "Plain-language description of who the campaign reaches." }, "isUnset": { "type": "boolean", "description": "True when targeting has never been set, so scheduling sends to every active subscriber." }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedAudienceEntity" } }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedAudienceEntity" } }, "filters": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "filterJoinOperator": { "type": [ "string", "null" ], "enum": [ "and", "or", null ] }, "include": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedAudienceRule" } }, "exclude": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedAudienceRule" } }, "excludedSubscriberIds": { "type": "array", "items": { "type": "string" } }, "includedSubscriberIds": { "type": "array", "items": { "type": "string" } }, "excludedCampaignOpenerIds": { "type": "array", "items": { "type": "string" } } } }, "IntegrationSummary": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string", "example": "shopify" }, "name": { "type": "string", "description": "Display name for the provider, falling back to the raw provider id.", "example": "Shopify" }, "category": { "type": [ "string", "null" ], "description": "Provider category, or null for a provider with no catalog entry.", "enum": [ "payments", "ecommerce", "auth", "analytics", "ads", "affiliate", "cms", "crm", "developer", null ] }, "providerAccountId": { "type": "string", "description": "Provider-side account identifier, such as a Shopify shop domain or Stripe acct_ ID." }, "isActive": { "type": "boolean" }, "syncEnabled": { "type": "boolean" }, "syncStatus": { "type": [ "string", "null" ] }, "lastSyncAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastSyncError": { "type": [ "string", "null" ] }, "totalCustomersSynced": { "type": "integer" }, "totalEventsSynced": { "type": "integer" }, "connectedAt": { "type": "string", "format": "date-time" }, "disconnectedAt": { "type": [ "string", "null" ], "format": "date-time" }, "details": { "type": "object", "additionalProperties": true, "description": "Allowlisted non-secret metadata. Never contains credentials. Attio includes listMap, mappedListCount, and syncCompanyFromDomain for configuration diagnostics." }, "lastSyncSkipped": { "description": "Records the last sync could not import normally. Null when the sync was clean or the provider does not report skips.", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/IntegrationSyncSkipSummary" } ] }, { "type": "null" } ] } } }, "EventSchema": { "type": "object", "description": "The published payload of one event. Listing mode returns the summary fields only; asking for a single eventName adds providers, mergeTagPrefix, and notes.", "properties": { "eventName": { "type": "string", "description": "Normalized event name - the name to trigger and to configure triggers on.", "example": "ecommerce.order_placed" }, "requestedEventName": { "type": "string", "description": "The name as asked for, before alias normalization." }, "documented": { "type": "boolean", "description": "Whether a reference payload is published. False never means the event name is invalid - custom events carry exactly the properties you send and are never rejected." }, "label": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "documentedProviders": { "type": "array", "description": "Providers with a reference payload for this event.", "items": { "type": "string", "enum": [ "shopify", "woocommerce", "manual", "api", "stripe" ] } }, "providers": { "type": "array", "description": "Single-event mode only. One entry per provider.", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "shopify", "woocommerce", "manual", "api", "stripe" ] }, "examplePayload": { "type": "object", "description": "A representative sample payload, not a contract.", "additionalProperties": true }, "properties": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Dot path into the payload. Object array elements use [], e.g. lineItems[].priceCents." }, "type": { "type": "string", "description": "Human-readable type, e.g. string, string | null, object[]." }, "description": { "type": "string", "description": "Present only where the sample value alone is ambiguous." }, "mergeTag": { "type": "string", "description": "Merge tag that resolves this path. Scalar paths only." } } } } } } }, "mergeTagPrefix": { "type": "string", "example": "event." }, "notes": { "type": "array", "items": { "type": "string" } } } }, "IntegrationProviderCapability": { "type": "object", "description": "What an integration provider does, independent of whether it is connected.", "properties": { "provider": { "type": "string", "example": "stripe" }, "name": { "type": "string", "example": "Stripe" }, "category": { "type": "string", "enum": [ "payments", "ecommerce", "auth", "analytics", "ads", "affiliate", "cms", "crm", "developer" ] }, "availability": { "type": "string", "enum": [ "available", "beta", "coming_soon" ], "description": "A coming_soon provider appears in the dashboard picker but has no webhook handler yet, so it emits nothing." }, "summary": { "type": "string" }, "connectMethod": { "type": "string", "enum": [ "oauth", "api_key", "app_install", "plugin", "webhook" ] }, "syncs": { "type": "array", "description": "What the integration keeps in sync. Empty when it only pushes events as they happen.", "items": { "type": "string" } }, "emits": { "type": "array", "description": "Every event the provider can produce. Empty when it never triggers automations.", "items": { "type": "object", "properties": { "event": { "type": "string", "description": "Event name a sequence triggers on." }, "when": { "type": "string", "description": "The real-world moment that produces this event." } } } }, "writesAttributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "description": { "type": "string" } } } }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "connect", "disconnect", "enable_sync", "disable_sync", "sync_now", "sync_products", "set_list_targeting", "activate_pixel", "update_attio_settings" ] } }, "connectFields": { "type": "array", "description": "Fields POST /integrations/connect accepts for this provider. Present exactly when actions includes connect.", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "apiKey", "webhookSecret", "providerAccountId", "settings", "historyImport" ] }, "required": { "type": "boolean" }, "secret": { "type": "boolean", "description": "True when the value is a credential and must be handled as a secret." }, "description": { "type": "string" } } } }, "notes": { "type": "array", "description": "Caveats worth knowing before building on the provider.", "items": { "type": "string" } } } }, "IntegrationEventWiring": { "type": "object", "description": "One emitted event crossed with the company's sync rules and sequences.", "properties": { "event": { "type": "string" }, "when": { "type": "string" }, "addsTags": { "type": "array", "items": { "type": "string" } }, "removesTags": { "type": "array", "items": { "type": "string" } }, "rules": { "type": "array", "description": "Every matching sync rule, kept separate so conditional effects remain accurate.", "items": { "type": "object", "properties": { "addsTags": { "type": "array", "items": { "type": "string" } }, "removesTags": { "type": "array", "items": { "type": "string" } }, "conditions": { "type": [ "object", "null" ], "additionalProperties": true } } } }, "observedByAccount": { "type": "boolean", "description": "Whether the account has received this event name from any source. Not integration-specific." }, "accountLastSeenAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the account last received the event name from any source." }, "ruleSource": { "type": "string", "enum": [ "custom", "default", "none" ], "description": "Where the matching sync rule came from. \"none\" means no rule touches this event, so it changes no tags." }, "listeners": { "type": "array", "description": "Sequences that trigger on this event.", "items": { "type": "object", "properties": { "sequenceId": { "type": "string" }, "name": { "type": "string" }, "effectiveStatus": { "type": "string" }, "acceptsNewEnrollments": { "type": "boolean" }, "effectiveStatusSummary": { "type": "string" } } } } } }, "IntegrationActivityEntry": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "integrationId": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "received", "queued", "processed", "skipped", "failed" ] }, "eventType": { "type": [ "string", "null" ] }, "providerEventId": { "type": [ "string", "null" ] }, "jobId": { "type": [ "string", "null" ] }, "subscriberId": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "The contact the event was matched to, or null when none could be resolved." }, "externalId": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "requestPayload": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Sanitized provider request metadata captured for diagnosis." }, "responsePayload": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Sanitized processing result metadata captured for diagnosis." }, "receivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "processedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "IntegrationDetail": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "integration": { "allOf": [ { "$ref": "#/components/schemas/IntegrationSummary" }, { "type": "object", "properties": { "name": { "type": "string", "description": "Provider display name." }, "category": { "type": [ "string", "null" ] } } } ] }, "capabilities": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/IntegrationProviderCapability" } ] }, { "type": "null" } ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationEventWiring" } }, "unusedEvents": { "type": "array", "description": "Events the provider emits that no sequence triggers on.", "items": { "type": "string" } }, "accountNeverReceivedEvents": { "type": "array", "description": "Provider event names the account has never received from any source. Not integration-specific.", "items": { "type": "string" } }, "activity": { "type": "object", "properties": { "windowHours": { "type": "integer", "example": 24 }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "failed": { "type": "integer" }, "skipped": { "type": "integer" }, "stalled": { "type": "integer", "description": "Events queued more than 15 minutes without completing." }, "lastActivityAt": { "type": [ "string", "null" ], "format": "date-time" }, "recentFailures": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "eventType": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "ingestion": { "type": "object", "description": "What this integration does to the contact list: whether bulk backfills run, and which lists the contacts created by the provider's live webhook join. Neither setting stops that webhook creating contacts.", "properties": { "bulkSyncEnabled": { "type": "boolean", "description": "Bulk imports and backfills. Same value as integration.syncEnabled." }, "supportsListTargeting": { "type": "boolean" }, "listTargeting": { "type": [ "string", "null" ], "enum": [ "company_default", "none", "specific", null ], "description": "Where contacts created by this integration land. Null for providers that ignore per-integration list targeting." }, "listIds": { "type": [ "array", "null" ], "description": "Configured target lists. Null means new contacts follow the workspace default lists.", "items": { "type": "string" } }, "lists": { "type": "array", "description": "Names for the configured lists.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "missingListIds": { "type": "array", "description": "Configured IDs whose list no longer exists. Deleting a list does not scrub it from integration settings and ingestion silently skips it, so these are targets nothing actually joins.", "items": { "type": "string" } }, "summary": { "type": "string", "description": "One sentence naming where this integration's new contacts land." } } }, "pixel": { "type": [ "object", "null" ], "description": "Shopify only: live storefront tracking pixel state, read from the store on every call. Null for providers without a pixel. Same shape as the pixel endpoint, plus healthy and dependentEvents.", "properties": { "installed": { "type": "boolean" }, "id": { "type": [ "string", "null" ] }, "endpoint": { "type": [ "string", "null" ] }, "endpointCurrent": { "type": "boolean" }, "configurationCurrent": { "type": "boolean" }, "healthy": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "dependentEvents": { "type": "array", "items": { "type": "string" } } } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string" }, "action": { "type": "string" } } } }, "availableActions": { "type": "array", "description": "Actions callable right now given the integration's current state.", "items": { "type": "string" } } } }, "IntegrationSyncSkipSummary": { "type": "object", "description": "Summary of records a store import could not bring in normally. A store with real order history often carries a few addresses on domains that have since been shut down; those are reported here instead of failing the whole import.", "properties": { "total": { "type": "integer", "description": "Every affected record, including any beyond the stored sample." }, "suppressed": { "type": "integer", "description": "Imported, but the address cannot receive email, so the profile is stored as bounced and sends stay suppressed. Order history still attaches to it." }, "skipped": { "type": "integer", "description": "Not imported at all." }, "truncated": { "type": "boolean", "description": "True when more records were affected than `records` holds." }, "records": { "type": "array", "description": "Sample of the affected records, up to 50.", "items": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "outcome": { "type": "string", "enum": [ "suppressed", "skipped" ] }, "reasonCode": { "type": "string", "example": "invalid_email_domain" }, "reason": { "type": "string", "example": "Invalid domain for \"buyer@example.com\": Domain cannot receive email (no MX records)" } } } } } }, "SenderProfileSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "domainId": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "domainStatus": { "type": [ "string", "null" ], "description": "Aggregate verification status of the sending domain." }, "canSend": { "type": "boolean", "description": "True when the domain is fully ready to send (DNS verified and activation finished)." }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ReplyProfileSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "SendingStatus": { "type": "object", "description": "Company-level sending state, the sender-health measurements behind it, and the remediation path. Enforcement is not time-windowed, so metricsWindow.expiresAt is always null.", "properties": { "success": { "type": "boolean", "example": true }, "status": { "type": "string", "enum": [ "active", "paused", "suspended" ], "description": "Anything other than active blocks every send for this workspace, including test sends." }, "pauseReason": { "type": [ "string", "null" ], "description": "Enforcement message including the measured rate, the threshold it crossed, and the volume it was measured over.", "example": "Bounce rate (9.910%) exceeded threshold (5%) for 111 total emails" }, "pauseReasonKind": { "type": [ "string", "null" ], "enum": [ "high_hard_bounce_rate", "high_soft_bounce_rate", "high_complaint_rate", "phishing_guard", "over_email_limit", "manual", "other", null ], "description": "Only high_hard_bounce_rate can be cleared through the resume endpoint. over_email_limit lifts automatically once the account has email allowance again." }, "pausedAt": { "type": [ "string", "null" ], "format": "date-time" }, "selfResume": { "type": "object", "properties": { "canSelfResume": { "type": "boolean", "description": "Whether POST /sending-status/resume will succeed right now." }, "supported": { "type": "boolean", "description": "Whether this pause reason is self-resumable at all." }, "allowedByAdmin": { "type": "boolean" }, "ownerIsTrusted": { "type": "boolean" }, "aiReviewStatus": { "type": "string", "enum": [ "not_required", "pending", "approved", "flagged", "failed" ], "description": "State of the automated sender-health review opened when the pause was created." }, "aiReviewReason": { "type": [ "string", "null" ] }, "aiReviewStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "aiReviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "unavailableReason": { "type": [ "string", "null" ], "enum": [ "unsupported_reason", "waiting_for_review", "blocked_by_ai", "review_failed", "blocked_by_admin", null ], "description": "The gate blocking resume. Null when resume is available." } } }, "senderHealth": { "type": [ "object", "null" ], "description": "Null when the workspace has no metrics record yet or sender-health analytics are temporarily unavailable. Pause state and remediation remain available during an analytics outage.", "properties": { "enforcementMode": { "type": "string", "enum": [ "enforce", "monitor_only" ] }, "scopedSent": { "type": "integer", "description": "Backward-compatible alias for bounceScopedSent." }, "bounceScopedSent": { "type": "integer", "description": "Non-test sends counted from the bounce reset watermark - the denominator for hard- and soft-bounce rates." }, "complaintScopedSent": { "type": "integer", "description": "Non-test sends counted from the complaint reset watermark - the denominator for complaint rates." }, "hardBounce": { "$ref": "#/components/schemas/SenderHealthMetric" }, "softBounce": { "$ref": "#/components/schemas/SenderHealthMetric" }, "complaint": { "$ref": "#/components/schemas/SenderHealthMetric" } } }, "metricsWindow": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "all_time_since_reset" ] }, "expiresAt": { "type": [ "string", "null" ], "description": "Always null. Enforcement totals are all-time from the watermark, so a paused rate never expires on its own." }, "bounceResetAt": { "type": [ "string", "null" ], "format": "date-time" }, "complaintResetAt": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": "string" } } }, "remediation": { "type": "object", "properties": { "steps": { "type": "array", "description": "Ordered next steps for the current state.", "items": { "type": "string" } }, "supportEmail": { "type": "string" }, "docsUrl": { "type": "string" }, "dashboardPath": { "type": [ "string", "null" ] }, "dashboardUrl": { "type": [ "string", "null" ] } } } } }, "SenderHealthMetric": { "type": "object", "properties": { "count": { "type": "integer" }, "rate": { "type": "number", "description": "Percentage of the applicable bounceScopedSent or complaintScopedSent denominator." }, "warnThreshold": { "$ref": "#/components/schemas/SenderHealthThresholdBound" }, "pauseThreshold": { "$ref": "#/components/schemas/SenderHealthThresholdBound" } } }, "SenderHealthThresholdBound": { "type": "object", "description": "Threshold that applies at this send volume. Either bound may be null when the tier does not use it.", "properties": { "rate": { "type": [ "number", "null" ] }, "count": { "type": [ "integer", "null" ] } } }, "TrackingDomain": { "type": "object", "description": "The company tracking domain. Every sending domain uses it for tracked links and opens. It never gates sending; until it verifies, or when it is broken or removed, links use the shared Sequenzy tracking domain.", "required": [ "domain", "status", "active", "everVerified", "cnameRecord" ], "properties": { "domain": { "type": "string", "description": "Tracking hostname, for example links.example.com.", "example": "links.example.com" }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "failed" ], "description": "Verification status of the CNAME and HTTPS certificate. not_started until the DNS setup is confirmed or checked." }, "active": { "type": "boolean", "description": "True while verified. New emails use this domain only while active." }, "everVerified": { "type": "boolean", "description": "True once this hostname has verified. A failed domain that was verified before is broken rather than unfinished." }, "sslStatus": { "type": [ "string", "null" ] }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ], "description": "Latest verification problem, if any." }, "cnameRecord": { "type": "object", "description": "The DNS record to publish.", "properties": { "type": { "type": "string", "enum": [ "CNAME" ] }, "name": { "type": "string", "example": "links.example.com" }, "value": { "type": "string", "example": "links1.sequenzydns.com" } } } } }, "TrackingSettings": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "tracking": { "type": "object", "properties": { "openTrackingEnabled": { "type": "boolean" }, "clickTrackingEnabled": { "type": "boolean" }, "strictBotFilteringEnabled": { "type": "boolean", "description": "Opt-in aggressive bot detection (strict user-agent patterns, datacenter and Microsoft Azure IPs, fast campaign and sequence clicks from IPs clicking other recipients' emails, cross-send IP sweeps). Off by default; enabling it can lower reported open and click rates." }, "unsubscribeTrackingEnabled": { "type": "boolean", "description": "Whether to track unsubscribe link clicks. When false, Sequenzy unsubscribe links go directly to https://sequenzy.com, even with a custom tracking domain. Actual unsubscribes and their email attribution are still recorded." }, "defaultAttributionWindowHours": { "type": "integer" }, "transactionalOpenTrackingEnabled": { "type": "boolean", "description": "Open tracking default for sends through the Send Email API. Account-wide open tracking must also be enabled; per-send trackingSettings can only opt out." }, "transactionalClickTrackingEnabled": { "type": "boolean", "description": "Click tracking default for sends through the Send Email API. Account-wide click tracking must also be enabled; per-send trackingSettings can only opt out." } } }, "consent": { "type": "object", "description": "Signup consent settings, as opposed to engagement measurement.", "properties": { "doubleOptInEnabled": { "type": "boolean", "description": "Whether new contacts must confirm by email before they become subscribed. When on, contacts added by forms, the API, and integrations start pending and are never sent marketing email until they confirm." }, "doubleOptInEmailId": { "type": [ "string", "null" ], "description": "Confirmation email sent to pending contacts. Null when double opt-in has never been enabled; enabling it provisions one automatically." }, "doubleOptInRedirectUrl": { "type": [ "string", "null" ], "description": "Where the hosted confirmation page sends subscribers after they confirm. Null keeps them on the branded confirmation page." } } }, "autoUtm": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "settings": { "type": "object", "additionalProperties": true } } }, "trackingDomain": { "type": [ "object", "null" ], "description": "Company tracking domain, used by every sending domain for tracked links and opens. Null when links use the shared Sequenzy tracking domain; links also use it while the tracking domain is not verified. Manage it with the Tracking Domain endpoints.", "properties": { "domain": { "type": "string" }, "status": { "type": "string" }, "sslStatus": { "type": [ "string", "null" ] }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } } }, "replyTracking": { "type": "object", "properties": { "inboundEmailEnabled": { "type": "boolean" }, "inboundReplyDomainMode": { "type": "string" }, "forwardReplies": { "type": "boolean" } } } } }, "CampaignDetail": { "allOf": [ { "$ref": "#/components/schemas/CampaignSummary" }, { "type": "object", "properties": { "preheader": { "type": "string", "example": "Latest product news" }, "preheaderText": { "type": "string", "description": "Compatibility alias for preheader.", "example": "Latest product news" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "campaignData": { "type": [ "object", "null" ], "additionalProperties": true }, "computedLists": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "targetLists": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Saved campaign audience, or null when targeting is still unset and scheduling will fall back to all active subscribers." }, "senderProfileId": { "type": "string" }, "fromName": { "type": [ "string", "null" ] }, "fromEmail": { "type": [ "string", "null" ], "format": "email" }, "replyProfileId": { "type": [ "string", "null" ], "example": "reply_abc123" }, "replyToName": { "type": [ "string", "null" ], "example": "Support" }, "replyToEmail": { "type": [ "string", "null" ], "format": "email", "example": "support@example.com" }, "ccEmails": { "type": [ "array", "null" ], "description": "Addresses CC'd on every recipient's email for this campaign.", "items": { "type": "string", "format": "email" } }, "bccEmails": { "type": [ "array", "null" ], "description": "Addresses BCC'd on every recipient's email for this campaign.", "items": { "type": "string", "format": "email" } }, "shareUrl": { "type": [ "string", "null" ], "description": "Public anonymized view-in-browser link, or null until one is minted via POST /campaigns/{campaignId}/share-link.", "example": "https://sequenzy.com/view/campaign/8f2kL9qWm3ZxYv71TnB4c5RdVaEuGh0s" } } } ] }, "LandingPageContent": { "type": "object", "properties": { "version": { "type": "integer", "enum": [ 2 ] }, "template": { "default": "waitlist", "type": "string", "enum": [ "from-scratch", "waitlist", "lead-magnet", "launch", "demo-request", "webinar", "newsletter", "product-hunt", "pricing-offer", "agency-lead-gen", "feature-announcement" ] }, "seo": { "default": { "faviconUrl": "", "hideFromSearchEngines": false }, "allOf": [ { "$ref": "#/components/schemas/LandingPageSeo" } ] }, "header": { "default": { "enabled": true, "showLogo": true, "logoUrl": "", "logoSize": 36, "showName": true, "name": "" }, "allOf": [ { "$ref": "#/components/schemas/LandingPageHeader" } ] }, "theme": { "default": { "accentColor": "#f97316", "backgroundColor": "#ffffff", "textColor": "#111827", "mutedTextColor": "#6b7280", "cardColor": "#ffffff", "borderRadius": 8, "fontPair": "modern-sans", "headingFontFamily": "", "bodyFontFamily": "", "density": "balanced", "accentStyle": "pill", "surfaceStyle": "soft", "sectionAnimation": "none", "sectionAnimationSpeed": "normal" }, "allOf": [ { "$ref": "#/components/schemas/LandingPageTheme" } ] }, "blocks": { "minItems": 0, "type": "array", "items": { "$ref": "#/components/schemas/LandingPageBlock" }, "description": "Blocks render in slot order: top, hero, form, body, footer, preserving order within each slot. Includes nested group children. An empty array is accepted: a default footer is appended whenever no footer is present. The stored document has exactly one footer." } }, "required": [ "version", "blocks" ], "description": "Version 2 landing page builder document. Providing content on update replaces the whole document. Block IDs must be unique throughout the tree. A missing footer is appended automatically; after normalization exactly one footer and at most one form are allowed. Groups may nest at most eight levels, and every child must share its parent slot. See /api-reference/landing-pages/content for block examples and semantic validation. Form and footer blocks must stay at the root, outside groups." }, "LandingPageBlock": { "oneOf": [ { "$ref": "#/components/schemas/LandingPageGroupBlock" }, { "$ref": "#/components/schemas/LandingPageHeadingBlock" }, { "$ref": "#/components/schemas/LandingPageTextBlock" }, { "$ref": "#/components/schemas/LandingPageImageBlock" }, { "$ref": "#/components/schemas/LandingPageVideoBlock" }, { "$ref": "#/components/schemas/LandingPageButtonBlock" }, { "$ref": "#/components/schemas/LandingPageCustomHtmlBlock" }, { "$ref": "#/components/schemas/LandingPageFeatureGridBlock" }, { "$ref": "#/components/schemas/LandingPageStatsBlock" }, { "$ref": "#/components/schemas/LandingPageTestimonialBlock" }, { "$ref": "#/components/schemas/LandingPageLogoCloudBlock" }, { "$ref": "#/components/schemas/LandingPageFaqBlock" }, { "$ref": "#/components/schemas/LandingPagePricingBlock" }, { "$ref": "#/components/schemas/LandingPageFormBlock" }, { "$ref": "#/components/schemas/LandingPageFooterBlock" }, { "$ref": "#/components/schemas/LandingPageSpacerBlock" }, { "$ref": "#/components/schemas/LandingPageDividerBlock" } ], "discriminator": { "propertyName": "kind", "mapping": { "group": "#/components/schemas/LandingPageGroupBlock", "heading": "#/components/schemas/LandingPageHeadingBlock", "text": "#/components/schemas/LandingPageTextBlock", "image": "#/components/schemas/LandingPageImageBlock", "video": "#/components/schemas/LandingPageVideoBlock", "button": "#/components/schemas/LandingPageButtonBlock", "custom-html": "#/components/schemas/LandingPageCustomHtmlBlock", "feature-grid": "#/components/schemas/LandingPageFeatureGridBlock", "stats": "#/components/schemas/LandingPageStatsBlock", "testimonial": "#/components/schemas/LandingPageTestimonialBlock", "logo-cloud": "#/components/schemas/LandingPageLogoCloudBlock", "faq": "#/components/schemas/LandingPageFaqBlock", "pricing": "#/components/schemas/LandingPagePricingBlock", "form": "#/components/schemas/LandingPageFormBlock", "footer": "#/components/schemas/LandingPageFooterBlock", "spacer": "#/components/schemas/LandingPageSpacerBlock", "divider": "#/components/schemas/LandingPageDividerBlock" } } }, "LandingPageButtonBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "button" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Plain text or inline HTML (bold, italic, links, colors). At most 80 visible characters; formatting markup does not count toward that limit." }, "url": { "default": "", "type": "string", "maxLength": 500 }, "variant": { "default": "primary", "type": "string", "enum": [ "primary", "secondary" ] }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "slot", "kind", "text" ] } ], "description": "CTA url accepts an HTTPS URL or an in-page anchor such as #form, #section-, #block-, or #top. Anchor links open in the same tab." }, "LandingPageCustomHtmlBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "custom-html" ] }, "html": { "default": "", "type": "string", "maxLength": 20000 }, "height": { "default": 320, "type": "integer", "minimum": 40, "maximum": 1200 } }, "required": [ "slot", "kind" ] } ] }, "LandingPageDividerBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "divider" ] } }, "required": [ "slot", "kind" ] } ] }, "LandingPageFaqBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "faq" ] }, "heading": { "default": "Common questions", "type": "string", "maxLength": 120 }, "items": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "$ref": "#/components/schemas/LandingPageFaqItem" } }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "slot", "kind", "items" ] } ] }, "LandingPageFaqItem": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 160 }, "answer": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "question", "answer" ] }, "LandingPageFeatureGridBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "feature-grid" ] }, "features": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/LandingPageFeature" } }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "columns": { "type": "integer", "minimum": 1, "maximum": 6 }, "layout": { "type": "string", "enum": [ "row", "column" ] } }, "required": [ "slot", "kind", "features" ] } ] }, "LandingPageFeature": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 300 } }, "required": [ "title", "description" ] }, "LandingPageFooterBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "footer" ] }, "kind": { "type": "string", "enum": [ "footer" ] }, "brandText": { "default": "Built by Sequenzy", "type": "string", "maxLength": 120 }, "showBrandText": { "default": true, "type": "boolean" }, "showPrivacyLink": { "default": true, "type": "boolean" }, "privacyLabel": { "default": "Privacy", "type": "string", "maxLength": 80 }, "privacyUrl": { "default": "", "type": "string", "maxLength": 500 }, "showTermsLink": { "default": true, "type": "boolean" }, "termsLabel": { "default": "Terms", "type": "string", "maxLength": 80 }, "termsUrl": { "default": "", "type": "string", "maxLength": 500 } }, "required": [ "slot", "kind" ] } ] }, "LandingPageFormBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "form" ] }, "kind": { "type": "string", "enum": [ "form" ] }, "heading": { "default": "Get early access", "type": "string", "maxLength": 120 }, "description": { "default": "", "type": "string", "maxLength": 240 }, "form": { "default": { "enabled": true, "duplicateStrategy": "skip", "listMode": "default", "listIds": [], "tagIds": [], "showFirstName": true, "showLastName": false, "showPhone": false, "firstNameRequired": false, "lastNameRequired": false, "phoneRequired": false, "emailPlaceholder": "you@example.com", "firstNamePlaceholder": "First name", "lastNamePlaceholder": "Last name", "phonePlaceholder": "Phone number", "customFields": [], "buttonText": "Join the list", "successMessage": "You're on the list." }, "allOf": [ { "$ref": "#/components/schemas/LandingPageFormConfig" } ] }, "cardTilt": { "type": "integer", "minimum": -3, "maximum": 3 }, "cardWidth": { "type": "string", "enum": [ "narrow", "medium", "wide" ] } }, "required": [ "slot", "kind" ] } ] }, "LandingPageFormConfig": { "type": "object", "properties": { "enabled": { "default": true, "type": "boolean" }, "duplicateStrategy": { "default": "skip", "type": "string", "enum": [ "skip", "merge", "overwrite" ] }, "listMode": { "default": "default", "type": "string", "enum": [ "default", "none", "specific" ] }, "listIds": { "default": [], "type": "array", "items": { "type": "string" } }, "tagIds": { "default": [], "type": "array", "items": { "type": "string" } }, "showFirstName": { "default": true, "type": "boolean" }, "showLastName": { "default": false, "type": "boolean" }, "showPhone": { "default": false, "type": "boolean" }, "firstNameRequired": { "default": false, "type": "boolean" }, "lastNameRequired": { "default": false, "type": "boolean" }, "phoneRequired": { "default": false, "type": "boolean" }, "emailPlaceholder": { "default": "you@example.com", "type": "string", "maxLength": 120 }, "firstNamePlaceholder": { "default": "First name", "type": "string", "maxLength": 120 }, "lastNamePlaceholder": { "default": "Last name", "type": "string", "maxLength": 120 }, "phonePlaceholder": { "default": "Phone number", "type": "string", "maxLength": 120 }, "customFields": { "default": [], "maxItems": 8, "type": "array", "items": { "$ref": "#/components/schemas/LandingPageFormCustomField" }, "description": "Up to eight custom subscriber attributes. Names use letters, numbers, underscores, dots or dashes and must start with a letter. Use unique names; email, firstName, lastName and website are reserved." }, "buttonText": { "default": "Join the list", "type": "string", "minLength": 1, "maxLength": 80 }, "successMessage": { "default": "You're on the list.", "type": "string", "minLength": 1, "maxLength": 240 }, "redirectUrl": { "type": "string", "maxLength": 500 } }, "description": "Form audience and submission settings. listMode default uses the workspace default lists; none joins no lists; specific uses listIds. All listIds and tagIds must belong to your company. Custom field names must be unique and cannot be email, firstName, lastName or website. Redirect URLs must pass HTTP/HTTPS validation." }, "LandingPageFormCustomField": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }, "label": { "default": "", "type": "string", "maxLength": 120 }, "placeholder": { "default": "", "type": "string", "maxLength": 120 }, "required": { "default": false, "type": "boolean" }, "inputType": { "default": "text", "type": "string", "enum": [ "text", "phone", "number", "textarea", "select", "radio", "checkbox", "consent", "hidden" ] }, "options": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "value": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "label", "value" ] } }, "consentText": { "default": "", "type": "string", "maxLength": 300 }, "defaultValue": { "default": "", "type": "string", "maxLength": 500 } }, "required": [ "name" ] }, "LandingPageGroupBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "group" ] }, "label": { "default": "Group", "type": "string", "minLength": 1, "maxLength": 120 }, "layout": { "default": "stack", "type": "string", "enum": [ "stack", "row", "grid", "overlay" ] }, "columns": { "default": 2, "type": "integer", "minimum": 1, "maximum": 4 }, "gap": { "default": 16, "type": "integer", "minimum": 0, "maximum": 64 }, "padding": { "default": 0, "type": "integer", "minimum": 0, "maximum": 64 }, "overlayColor": { "default": "#000000", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "overlayPosition": { "default": "center", "type": "string", "enum": [ "top", "center", "bottom" ] }, "overlayShade": { "default": 35, "type": "integer", "minimum": 0, "maximum": 100 }, "children": { "default": [], "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/LandingPageBlock" } } }, "required": [ "slot", "kind" ] } ], "description": "Children share the parent slot. Overlay needs exactly one direct image block with at most one gallery image; other overlay groups normalize to stack. Maximum group depth is eight." }, "LandingPageHeader": { "type": "object", "properties": { "enabled": { "default": true, "type": "boolean" }, "showLogo": { "default": true, "type": "boolean" }, "logoUrl": { "default": "", "type": "string", "maxLength": 1000 }, "logoSize": { "default": 36, "type": "integer", "minimum": 24, "maximum": 96 }, "showName": { "default": true, "type": "boolean" }, "name": { "default": "", "type": "string", "maxLength": 120 } } }, "LandingPageHeadingBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "heading" ] }, "level": { "default": 2, "type": "integer", "enum": [ 1, 2, 3 ] }, "content": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Plain text or inline HTML (bold, italic, links, colors). At most 180 visible characters; formatting markup does not count toward that limit." }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "slot", "kind", "content" ] } ] }, "LandingPageImageBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "image" ] }, "src": { "default": "", "type": "string", "maxLength": 1000 }, "alt": { "default": "", "type": "string", "maxLength": 160 }, "images": { "default": [], "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/LandingPageImageItem" } }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "width": { "type": "integer", "minimum": 25, "maximum": 100 }, "height": { "type": "integer", "minimum": 80, "maximum": 640 }, "fit": { "type": "string", "enum": [ "cover", "contain" ] } }, "required": [ "slot", "kind" ] } ] }, "LandingPageImageItem": { "type": "object", "properties": { "src": { "default": "", "type": "string", "maxLength": 1000 }, "alt": { "default": "", "type": "string", "maxLength": 160 }, "linkUrl": { "type": "string", "maxLength": 500 } } }, "LandingPageLogoCloudBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "logo-cloud" ] }, "heading": { "default": "Trusted by teams building faster", "type": "string", "maxLength": 120 }, "logos": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "$ref": "#/components/schemas/LandingPageLogo" } }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "columns": { "type": "integer", "minimum": 1, "maximum": 6 } }, "required": [ "slot", "kind", "logos" ] } ] }, "LandingPageLogo": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ] }, "LandingPagePricingBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "pricing" ] }, "eyebrow": { "default": "Simple pricing", "type": "string", "maxLength": 80 }, "heading": { "type": "string", "minLength": 1, "maxLength": 140 }, "description": { "default": "", "type": "string", "maxLength": 300 }, "price": { "type": "string", "minLength": 1, "maxLength": 80 }, "period": { "default": "", "type": "string", "maxLength": 80 }, "buttonText": { "type": "string", "minLength": 1, "maxLength": 80 }, "buttonUrl": { "default": "", "type": "string", "maxLength": 500 }, "features": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 } }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "slot", "kind", "heading", "price", "buttonText", "features" ] } ], "description": "Pricing buttonUrl accepts an HTTPS URL or an in-page anchor such as #form." }, "LandingPageSeo": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 70 }, "description": { "type": "string", "maxLength": 160 }, "faviconUrl": { "default": "", "type": "string", "maxLength": 1000, "description": "Empty falls back to the company logo." }, "hideFromSearchEngines": { "default": false, "type": "boolean", "description": "Adds noindex, nofollow. The page stays reachable by direct link." } } }, "LandingPageSpacerBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "spacer" ] }, "height": { "default": 32, "type": "integer", "minimum": 8, "maximum": 160 } }, "required": [ "slot", "kind" ] } ] }, "LandingPageStatistic": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "value", "label" ] }, "LandingPageStatsBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "stats" ] }, "stats": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/LandingPageStatistic" } }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "columns": { "type": "integer", "minimum": 1, "maximum": 6 } }, "required": [ "slot", "kind", "stats" ] } ] }, "LandingPageTestimonialBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "testimonial" ] }, "testimonials": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/LandingPageTestimonial" } }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "columns": { "type": "integer", "minimum": 1, "maximum": 6 }, "layout": { "type": "string", "enum": [ "row", "column" ] } }, "required": [ "slot", "kind", "testimonials" ] } ] }, "LandingPageTestimonial": { "type": "object", "properties": { "quote": { "type": "string", "minLength": 1, "maxLength": 500 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "role": { "default": "", "type": "string", "maxLength": 160 }, "avatarUrl": { "default": "", "type": "string", "maxLength": 1000 } }, "required": [ "quote", "name" ] }, "LandingPageTextBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "text" ] }, "variant": { "default": "paragraph", "type": "string", "enum": [ "paragraph", "eyebrow", "caption" ] }, "content": { "type": "string", "maxLength": 5000, "description": "Plain text or inline HTML (bold, italic, links, colors). At most 700 visible characters; formatting markup does not count toward that limit." }, "align": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "slot", "kind", "content" ] } ] }, "LandingPageTheme": { "type": "object", "properties": { "accentColor": { "default": "#f97316", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundColor": { "default": "#ffffff", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textColor": { "default": "#111827", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "mutedTextColor": { "default": "#6b7280", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "cardColor": { "default": "#ffffff", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "borderRadius": { "default": 8, "type": "integer", "minimum": 0, "maximum": 24 }, "fontPair": { "default": "modern-sans", "type": "string", "enum": [ "modern-sans", "editorial-serif", "classic-serif", "friendly-rounded", "commerce-sans", "technical-mono" ] }, "headingFontFamily": { "default": "", "type": "string", "maxLength": 160 }, "bodyFontFamily": { "default": "", "type": "string", "maxLength": 160 }, "density": { "default": "balanced", "type": "string", "enum": [ "compact", "balanced", "spacious" ] }, "accentStyle": { "default": "pill", "type": "string", "enum": [ "pill", "underline", "bar", "badge" ] }, "surfaceStyle": { "default": "soft", "type": "string", "enum": [ "soft", "outlined", "solid", "minimal" ] }, "sectionAnimation": { "default": "none", "type": "string", "enum": [ "none", "fade", "slide-up", "zoom-in" ], "description": "Scroll reveal animation; skipped for visitors who prefer reduced motion." }, "sectionAnimationSpeed": { "default": "normal", "type": "string", "enum": [ "slow", "normal", "fast" ] } } }, "LandingPageVideoBlock": { "allOf": [ { "$ref": "#/components/schemas/LandingPageBlockBase" }, { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "top", "hero", "form", "body", "footer" ] }, "kind": { "type": "string", "enum": [ "video" ] }, "url": { "default": "", "type": "string", "maxLength": 1000 }, "title": { "default": "", "type": "string", "maxLength": 160 }, "align": { "type": "string", "enum": [ "left", "center", "right" ] }, "width": { "type": "integer", "minimum": 25, "maximum": 100 }, "aspectRatio": { "default": "16:9", "type": "string", "enum": [ "16:9", "4:3", "1:1", "9:16" ] } }, "required": [ "slot", "kind" ] } ], "description": "Embeds a YouTube share URL. Other video providers and direct video files are not supported." }, "LandingPageBlockBase": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionKind": { "type": "string", "minLength": 1, "maxLength": 80 }, "sectionLabel": { "type": "string", "minLength": 1, "maxLength": 120 }, "sectionVariant": { "type": "string", "maxLength": 80 }, "sectionLayout": { "type": "string", "enum": [ "stack", "split", "center" ] }, "sectionAlign": { "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "id" ] }, "CaptureButtonBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "button" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "default": "", "type": "string", "maxLength": 500 }, "variant": { "default": "primary", "type": "string", "enum": [ "primary", "secondary" ] }, "align": { "default": "left", "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "id", "kind", "text", "url", "variant", "align" ] }, "CaptureCountdownBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "countdown" ] }, "label": { "default": "Limited time", "type": "string", "maxLength": 80 }, "endsAt": { "type": "string", "maxLength": 80 } }, "required": [ "id", "kind", "label", "endsAt" ] }, "CaptureCustomHtmlBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "custom-html" ] }, "html": { "default": "", "type": "string", "maxLength": 20000 }, "height": { "default": 320, "type": "integer", "minimum": 40, "maximum": 1200 } }, "required": [ "id", "kind", "html", "height" ] }, "CaptureDividerBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "divider" ] } }, "required": [ "id", "kind" ] }, "CaptureFeatureGridBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "feature-grid" ] }, "features": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/CaptureFeature" } }, "columns": { "default": 3, "type": "integer", "minimum": 1, "maximum": 4 } }, "required": [ "id", "kind", "features", "columns" ] }, "CaptureFeature": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 1100, "description": "Inline HTML is sanitized. Visible text after stripping markup and trimming must contain at most 120 characters. maxLength limits the raw markup separately." }, "description": { "type": "string", "maxLength": 2000, "description": "Inline HTML is sanitized. Visible text after stripping markup and trimming must contain at most 300 characters. maxLength limits the raw markup separately." } }, "required": [ "title", "description" ], "description": "At least one of title or description must contain visible text." }, "CaptureGroupBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "group" ] }, "label": { "default": "Group", "type": "string", "minLength": 1, "maxLength": 120 }, "layout": { "default": "stack", "type": "string", "enum": [ "stack", "row", "grid", "overlay" ] }, "columns": { "default": 2, "type": "integer", "minimum": 1, "maximum": 4 }, "gap": { "default": 12, "type": "integer", "minimum": 0, "maximum": 64 }, "padding": { "default": 0, "type": "integer", "minimum": 0, "maximum": 64 }, "overlayColor": { "default": "#000000", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "overlayPosition": { "default": "center", "type": "string", "enum": [ "top", "center", "bottom" ] }, "overlayShade": { "default": 35, "type": "integer", "minimum": 0, "maximum": 100 }, "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/FormCaptureBlock" } } }, "required": [ "id", "kind", "label", "layout", "columns", "gap", "padding", "overlayColor", "overlayPosition", "overlayShade", "children" ] }, "CaptureHeadingBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "heading" ] }, "level": { "default": 2, "type": "integer", "enum": [ 1, 2, 3 ] }, "content": { "type": "string", "maxLength": 1400, "description": "Inline HTML is sanitized. Visible text after stripping markup and trimming must contain 1 to 180 characters. maxLength limits the raw markup separately." }, "align": { "default": "left", "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "id", "kind", "level", "content", "align" ] }, "CaptureImageBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "image" ] }, "src": { "default": "", "type": "string", "maxLength": 1000 }, "alt": { "default": "", "type": "string", "maxLength": 160 }, "fit": { "default": "cover", "type": "string", "enum": [ "cover", "contain" ] } }, "required": [ "id", "kind", "src", "alt", "fit" ] }, "CaptureSpacerBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "spacer" ] }, "height": { "default": 32, "type": "integer", "minimum": 8, "maximum": 160 } }, "required": [ "id", "kind", "height" ] }, "CaptureTestimonialBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "testimonial" ] }, "testimonials": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/CaptureTestimonial" } } }, "required": [ "id", "kind", "testimonials" ] }, "CaptureTestimonial": { "type": "object", "properties": { "quote": { "type": "string", "maxLength": 3000, "description": "Inline HTML is sanitized. Visible text after stripping markup and trimming must contain 1 to 500 characters. maxLength limits the raw markup separately." }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "role": { "default": "", "type": "string", "maxLength": 160 } }, "required": [ "quote", "name", "role" ] }, "CaptureTextBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "text" ] }, "variant": { "default": "paragraph", "type": "string", "enum": [ "paragraph", "eyebrow", "caption" ] }, "content": { "type": "string", "maxLength": 4000, "description": "Inline HTML is sanitized. Visible text after stripping markup and trimming must contain at most 700 characters. maxLength limits the raw markup separately." }, "align": { "default": "left", "type": "string", "enum": [ "left", "center", "right" ] } }, "required": [ "id", "kind", "variant", "content", "align" ] }, "CaptureTheme": { "type": "object", "properties": { "accentColor": { "default": "#f97316", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundColor": { "default": "#ffffff", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textColor": { "default": "#111827", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "mutedTextColor": { "default": "#6b7280", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "cardColor": { "default": "#ffffff", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "borderColor": { "default": "#e5e7eb", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "borderRadius": { "default": 8, "type": "integer", "minimum": 0, "maximum": 32 }, "headingFontFamily": { "default": "", "type": "string", "maxLength": 160 }, "bodyFontFamily": { "default": "", "type": "string", "maxLength": 160 }, "density": { "default": "balanced", "type": "string", "enum": [ "compact", "balanced", "spacious" ] } }, "required": [ "accentColor", "backgroundColor", "textColor", "mutedTextColor", "cardColor", "borderColor", "borderRadius", "headingFontFamily", "bodyFontFamily", "density" ] }, "FormCaptureBlock": { "oneOf": [ { "$ref": "#/components/schemas/CaptureGroupBlock" }, { "$ref": "#/components/schemas/CaptureHeadingBlock" }, { "$ref": "#/components/schemas/CaptureTextBlock" }, { "$ref": "#/components/schemas/CaptureImageBlock" }, { "$ref": "#/components/schemas/CaptureButtonBlock" }, { "$ref": "#/components/schemas/CaptureDividerBlock" }, { "$ref": "#/components/schemas/CaptureSpacerBlock" }, { "$ref": "#/components/schemas/CaptureCustomHtmlBlock" }, { "$ref": "#/components/schemas/CaptureFeatureGridBlock" }, { "$ref": "#/components/schemas/CaptureTestimonialBlock" }, { "$ref": "#/components/schemas/CaptureCountdownBlock" }, { "$ref": "#/components/schemas/FormCaptureFieldBlock" }, { "$ref": "#/components/schemas/FormCaptureStepBlock" }, { "$ref": "#/components/schemas/FormCaptureSubmitButtonBlock" }, { "$ref": "#/components/schemas/FormCaptureSuccessScreenBlock" }, { "$ref": "#/components/schemas/FormCaptureErrorStateBlock" } ], "description": "Form content block, selected by kind. Returned content includes normalized defaults." }, "FormCaptureErrorStateBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "error-state" ] }, "message": { "default": "Something went wrong. Please try again.", "type": "string", "minLength": 1, "maxLength": 240 } }, "required": [ "id", "kind", "message" ] }, "FormCaptureFieldBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "form-field" ] }, "fieldType": { "default": "text", "type": "string", "enum": [ "text", "email", "phone", "number", "textarea", "select", "radio", "checkbox", "consent", "hidden" ] }, "label": { "default": "", "type": "string", "maxLength": 120 }, "showLabel": { "default": true, "type": "boolean" }, "width": { "type": "string", "enum": [ "full", "half" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }, "placeholder": { "default": "", "type": "string", "maxLength": 120 }, "required": { "default": false, "type": "boolean" }, "defaultValue": { "default": "", "type": "string", "maxLength": 500 }, "options": { "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/FormCaptureFieldOption" } }, "mapsTo": { "default": "customAttribute", "type": "string", "enum": [ "email", "firstName", "lastName", "phone", "customAttribute" ] }, "consentText": { "default": "", "type": "string", "maxLength": 500 } }, "required": [ "id", "kind", "fieldType", "label", "showLabel", "name", "placeholder", "required", "defaultValue", "options", "mapsTo", "consentText" ] }, "FormCaptureFieldOption": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "value": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "id", "label", "value" ], "description": "Choice option. Supply value; id and label are derived from it when omitted. Read responses include the normalized id and label." }, "FormCaptureSettings": { "type": "object", "properties": { "duplicateStrategy": { "default": "skip", "type": "string", "enum": [ "skip", "merge", "overwrite" ] }, "resubscribeBehavior": { "default": "reactivate", "type": "string", "enum": [ "reactivate", "double_opt_in" ], "description": "What happens when a contact who unsubscribed from all email submits the form or popup again. `reactivate` resubscribes them and restores the target lists. `double_opt_in` sends the workspace confirmation email first. Workspace double opt-in always requires confirmation." }, "listMode": { "default": "all", "type": "string", "enum": [ "all", "none", "specific" ] }, "listIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string" } }, "tagIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string" } }, "afterSubmission": { "default": "message", "type": "string", "enum": [ "message", "redirect" ] }, "redirectUrl": { "default": "", "type": "string", "maxLength": 500 } }, "required": [ "duplicateStrategy", "resubscribeBehavior", "listMode", "listIds", "tagIds", "afterSubmission", "redirectUrl" ] }, "FormCaptureStepBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "form-step" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "default": "", "type": "string", "maxLength": 240 }, "blockIds": { "default": [], "maxItems": 40, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "required": [ "id", "kind", "title", "description", "blockIds" ] }, "FormCaptureSubmitButtonBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "submit-button" ] }, "text": { "default": "Submit", "type": "string", "minLength": 1, "maxLength": 80 }, "width": { "type": "string", "enum": [ "full", "half" ] } }, "required": [ "id", "kind", "text" ] }, "FormCaptureSuccessScreenBlock": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "kind": { "type": "string", "enum": [ "success-screen" ] }, "heading": { "type": "string", "maxLength": 1100, "description": "Inline HTML is sanitized. Visible text after stripping markup and trimming must contain at most 120 characters. maxLength limits the raw markup separately." }, "message": { "type": "string", "maxLength": 1700, "description": "Inline HTML is sanitized. Visible text after stripping markup and trimming must contain 1 to 240 characters. maxLength limits the raw markup separately." } }, "required": [ "id", "kind", "heading", "message" ] }, "SavedFormContent": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "surface": { "type": "string", "enum": [ "form" ] }, "template": { "default": "editorial-split", "type": "string", "minLength": 1, "maxLength": 80 }, "theme": { "default": { "accentColor": "#f97316", "backgroundColor": "#ffffff", "textColor": "#111827", "mutedTextColor": "#6b7280", "cardColor": "#ffffff", "borderColor": "#e5e7eb", "borderRadius": 8, "headingFontFamily": "", "bodyFontFamily": "", "density": "balanced" }, "allOf": [ { "$ref": "#/components/schemas/CaptureTheme" } ] }, "settings": { "default": { "duplicateStrategy": "skip", "resubscribeBehavior": "reactivate", "listMode": "all", "listIds": [], "tagIds": [], "afterSubmission": "message", "redirectUrl": "" }, "allOf": [ { "$ref": "#/components/schemas/FormCaptureSettings" } ] }, "blocks": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/FormCaptureBlock" } } }, "required": [ "version", "surface", "template", "theme", "settings", "blocks" ], "description": "Complete version 1 form builder document. Read content.blocks before replacing the array. Exactly one required email field and one submit button are required. Block IDs and field names must be unique. At most 200 total blocks and three levels of groups. See /api-reference/widgets/update-saved-form#content-blocks for writable fields and placement rules. Read responses include template, theme, settings and all defaulted properties after normalization." }, "SavedFormSettings": { "type": "object", "properties": { "duplicateStrategy": { "default": "skip", "type": "string", "enum": [ "skip", "merge", "overwrite" ] }, "resubscribeBehavior": { "default": "reactivate", "type": "string", "enum": [ "reactivate", "double_opt_in" ], "description": "What happens when a contact who unsubscribed from all email submits the form or popup again. `reactivate` resubscribes them and restores the target lists. `double_opt_in` sends the workspace confirmation email first. Workspace double opt-in always requires confirmation." }, "listMode": { "default": "all", "type": "string", "enum": [ "all", "none", "specific" ] }, "listIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string" } }, "tagIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string" } }, "templateId": { "default": "editorial-split", "type": "string", "enum": [ "minimal", "inline", "card", "compact", "editorial-split", "full-page-welcome", "inline-banner", "floating-bar" ] }, "themeMode": { "default": "design-system", "type": "string", "enum": [ "design-system", "custom" ] }, "formStyle": { "default": "button-below", "type": "string", "enum": [ "button-below", "button-inline" ] }, "buttonText": { "default": "Subscribe", "type": "string", "minLength": 1, "maxLength": 80 }, "buttonColor": { "default": null, "type": [ "string", "null" ], "maxLength": 300 }, "placeholderEmail": { "default": "you@example.com", "type": "string", "maxLength": 120 }, "eyebrowText": { "default": "", "type": "string", "maxLength": 900 }, "headline": { "default": "", "type": "string", "maxLength": 1400 }, "description": { "default": "", "type": "string", "maxLength": 4000 }, "imageUrl": { "default": null, "type": [ "string", "null" ], "maxLength": 1000 }, "imageAlt": { "default": "", "type": "string", "maxLength": 160 }, "visualPlacement": { "default": "none", "type": "string", "enum": [ "none", "background", "left", "right", "top" ] }, "overlayColor": { "default": null, "type": [ "string", "null" ], "maxLength": 300 }, "overlayOpacity": { "default": 0.35, "type": "number", "minimum": 0, "maximum": 0.85 }, "fontFamily": { "default": null, "type": [ "string", "null" ], "maxLength": 300 }, "fontSize": { "default": null, "type": [ "string", "null" ], "maxLength": 300 }, "fontColor": { "default": null, "type": [ "string", "null" ], "maxLength": 300 }, "borderRadius": { "default": null, "type": [ "string", "null" ], "maxLength": 300 }, "afterSubmission": { "default": "message", "type": "string", "enum": [ "message", "redirect" ] }, "redirectUrl": { "default": "", "type": "string", "maxLength": 500 }, "successMessage": { "default": "Thanks for subscribing!", "type": "string", "minLength": 1, "maxLength": 1700 }, "successFontColor": { "default": null, "type": [ "string", "null" ], "maxLength": 300 }, "successFontSize": { "default": "14", "type": "string", "maxLength": 16 }, "errorMessage": { "default": "Something went wrong. Please try again.", "type": "string", "minLength": 1, "maxLength": 240 }, "showFirstName": { "default": false, "type": "boolean" }, "showLastName": { "default": false, "type": "boolean" }, "placeholderFirstName": { "default": "First name", "type": "string", "maxLength": 120 }, "placeholderLastName": { "default": "Last name", "type": "string", "maxLength": 120 }, "firstNameRequired": { "default": false, "type": "boolean" }, "lastNameRequired": { "default": false, "type": "boolean" }, "fieldOrder": { "maxItems": 50, "type": "array", "items": { "type": "string", "description": "Built-in field name (firstName, lastName, email) or custom:." } }, "customFields": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }, "placeholder": { "default": "", "type": "string", "maxLength": 120 }, "required": { "default": false, "type": "boolean" } }, "required": [ "id", "label", "name" ] } } }, "required": [ "duplicateStrategy", "resubscribeBehavior", "listMode", "listIds", "tagIds", "templateId", "themeMode", "formStyle", "buttonText", "buttonColor", "placeholderEmail", "eyebrowText", "headline", "description", "imageUrl", "imageAlt", "visualPlacement", "overlayColor", "overlayOpacity", "fontFamily", "fontSize", "fontColor", "borderRadius", "afterSubmission", "redirectUrl", "successMessage", "successFontColor", "successFontSize", "errorMessage", "showFirstName", "showLastName", "placeholderFirstName", "placeholderLastName", "firstNameRequired", "lastNameRequired", "fieldOrder", "customFields" ] }, "SavedForm": { "type": "object", "required": [ "id", "name", "status", "settings", "content", "submissionCount", "publishedAt", "createdAt", "updatedAt", "actionUrl", "url" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "settings": { "$ref": "#/components/schemas/SavedFormSettings" }, "content": { "$ref": "#/components/schemas/SavedFormContent" }, "submissionCount": { "type": "integer" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Publication timestamp; unpublishing may preserve it. Use status to determine whether the form is currently published." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "actionUrl": { "type": "string", "format": "uri" }, "url": { "type": "string", "format": "uri", "description": "Dashboard URL for this form." } } }, "SavedFormEmbed": { "type": "object", "required": [ "actionUrl", "scriptUrl", "javascript", "nativeForm", "fetch", "supportedPlatforms" ], "properties": { "actionUrl": { "type": "string", "format": "uri" }, "scriptUrl": { "type": "string", "format": "uri" }, "javascript": { "type": "string", "description": "Hosted JavaScript embed markup." }, "nativeForm": { "type": "string", "description": "Native HTML form embed markup." }, "fetch": { "type": "string", "description": "Fetch-enhanced embed markup." }, "supportedPlatforms": { "type": "array", "items": { "type": "string" } } } }, "LandingPageSummary": { "type": "object", "properties": { "id": { "type": "string", "example": "lp_abc123" }, "companyId": { "type": "string", "example": "comp_abc123" }, "name": { "type": "string", "example": "Product Waitlist" }, "slug": { "type": "string", "example": "product-waitlist" }, "status": { "type": "string", "enum": [ "draft", "published" ], "example": "published" }, "content": { "$ref": "#/components/schemas/LandingPageContent" }, "viewCount": { "type": "integer", "example": 1240 }, "conversionCount": { "type": "integer", "example": 186 }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri", "description": "Dashboard edit URL.", "example": "https://sequenzy.com/dashboard/company/comp_abc123/landing-pages/lp_abc123" }, "appPublicUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Sequenzy-hosted public URL when published.", "example": "https://sequenzy.com/lp/comp_abc123/product-waitlist" }, "customDomain": { "type": [ "string", "null" ], "description": "Preferred verified custom hostname for this page.", "example": "offer.example.com" }, "customDomainScope": { "type": [ "string", "null" ], "enum": [ "page", "workspace", null ], "description": "Whether the preferred hostname is dedicated to this page or inherited from the workspace." }, "publicUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Custom-domain public URL when a verified custom domain is connected, otherwise the Sequenzy-hosted public URL.", "example": "https://pages.example.com/product-waitlist" }, "previewUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Signed, unlisted visitor-facing preview of the current content. Works for drafts. Not indexed.", "example": "https://sequenzy.com/lp/preview/lp_abc123?token=..." } } }, "LandingPageDomain": { "type": "object", "properties": { "domain": { "type": [ "string", "null" ], "example": "pages.example.com" }, "domainScope": { "type": [ "string", "null" ], "enum": [ "page", "workspace", null ], "description": "Domain assignment scope." }, "landingPageId": { "type": [ "string", "null" ], "description": "Assigned landing page ID for a dedicated page domain." }, "domainStatus": { "type": "string", "example": "pending" }, "fallbackDomain": { "type": [ "string", "null" ], "description": "Verified or pending workspace domain retained as a fallback for a page-scoped domain." }, "fallbackDomainStatus": { "type": "string", "default": "not_started", "description": "Workspace fallback-domain status; `not_started` when no fallback domain is configured." }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "dnsRecordAddedAt": { "type": [ "string", "null" ], "format": "date-time" }, "sslStatus": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "verificationRecords": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cnameTarget": { "type": "string", "example": "pages.sequenzydns.com" }, "dnsRecordType": { "type": "string", "enum": [ "A", "CNAME" ], "description": "DNS record type to add - CNAME for subdomains, A for root domains." }, "dnsRecordName": { "type": [ "string", "null" ], "description": "DNS record name (the connected hostname); null when no domain is connected.", "example": "pages.example.com" }, "dnsRecordValue": { "type": "string", "description": "DNS record value - the CNAME target for subdomains or the A record IP (76.76.21.21) for root domains.", "example": "pages.sequenzydns.com" } } }, "TemplateSummary": { "type": "object", "properties": { "id": { "type": "string", "example": "email_abc123" }, "name": { "type": "string", "example": "[Template] Welcome" }, "subject": { "type": "string", "example": "Welcome!" }, "previewText": { "type": [ "string", "null" ] }, "emailPreset": { "$ref": "#/components/schemas/EmailPreset" }, "labels": { "type": "array", "description": "Label names assigned to this template.", "items": { "type": "string" }, "example": [ "edm", "template" ] }, "isTemplate": { "type": "boolean", "description": "True when this email is marked as a reusable master design.\nMaster designs are offered first when a sequence step or campaign\nstarts from an existing email, and starting from one always creates\nan independent copy (never a shared link).\n", "example": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "localizations": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "TemplateDetail": { "allOf": [ { "$ref": "#/components/schemas/TemplateSummary" }, { "type": "object", "properties": { "companyId": { "type": "string", "example": "company_abc123" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "fontFamily": { "type": [ "string", "null" ] }, "shareUrl": { "type": [ "string", "null" ], "description": "Public anonymized view-in-browser URL. Null until a link is\nminted via POST /templates/{templateId}/share-link.\n" }, "emailLocalizationConfig": { "type": "object", "additionalProperties": true }, "abTests": { "type": "array", "description": "Present when this email belongs to one or more A/B test\nvariants and the key has ab_tests:read. Content edits must use\nthe A/B variant update endpoint / `update_ab_test_variant`\ntool, not PUT /templates/{templateId}. Campaign variants can\nshare one email, so each test lists every matching variant.\n", "items": { "$ref": "#/components/schemas/TemplateAbTestReference" } } } } ] }, "TemplateAbTestVariantReference": { "type": "object", "properties": { "variantId": { "type": "string" }, "variantLabel": { "type": "string" } }, "required": [ "variantId", "variantLabel" ] }, "TemplateAbTestReference": { "type": "object", "properties": { "abTestId": { "type": "string" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateAbTestVariantReference" } }, "contentEditing": { "$ref": "#/components/schemas/AbTestContentEditing" } }, "required": [ "abTestId", "variants", "contentEditing" ] }, "TemplateUpdateError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "description": "Validation error. When code is AB_TEST_VARIANT_CONTENT_EDIT, the\nrecovery fields below are present. abTests is included only when\nthe key also has ab_tests:read.\n", "properties": { "title": { "type": "string" }, "howToFix": { "type": "string" }, "docsUrl": { "type": "string", "format": "uri" }, "abTests": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateAbTestReference" } } } } ] }, "TemplateLocalization": { "type": "object", "properties": { "locale": { "type": "string", "example": "es" }, "status": { "type": "string", "enum": [ "synced", "stale", "syncing", "failed" ] }, "subject": { "type": "string", "example": "Bienvenido" }, "previewText": { "type": [ "string", "null" ] }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "sourceHash": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "syncedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ABTestVariant": { "type": "object", "properties": { "id": { "type": "string", "example": "var_a" }, "variantId": { "type": "string", "example": "var_a" }, "abTestId": { "type": "string", "example": "ab_abc123" }, "label": { "type": "string", "example": "A" }, "variantLabel": { "type": "string", "example": "A" }, "emailId": { "type": "string", "example": "email_abc123" }, "subject": { "type": "string", "example": "Welcome" }, "previewText": { "type": [ "string", "null" ] }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "testSends": { "type": "integer" }, "testOpens": { "type": "integer" }, "testClicks": { "type": "integer" }, "isWinner": { "type": "boolean" }, "localizations": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "createdAt": { "type": "string", "format": "date-time" } } }, "ABTest": { "type": "object", "properties": { "id": { "type": "string", "example": "ab_abc123" }, "companyId": { "type": "string", "example": "company_abc123" }, "kind": { "type": "string", "enum": [ "campaign", "sequence" ], "description": "Identifies which settings model applies to this test." }, "campaignId": { "type": [ "string", "null" ], "example": "camp_abc123" }, "automationNodeId": { "type": [ "string", "null" ], "example": "node_abc123" }, "name": { "type": [ "string", "null" ], "example": "Subject test" }, "status": { "type": "string", "example": "draft" }, "testPercentage": { "type": "integer", "description": "Campaign test audience percentage. Sequence tests retain the legacy internal sentinel value 100; use settings instead." }, "testDurationMinutes": { "type": "integer", "description": "Campaign test duration. Sequence tests retain the legacy internal sentinel value 0; use settings instead." }, "winnerCriteria": { "type": "string", "example": "open_rate" }, "testType": { "type": "string", "enum": [ "subject", "content" ], "description": "Effective sequence variant strategy. Present for sequence tests." }, "winnerThreshold": { "type": "integer", "description": "Effective sequence recipient threshold. Present for sequence tests." }, "autoSelectWinner": { "type": "boolean", "description": "Whether a winner is picked automatically once winnerThreshold is reached and one variant leads. False after testing is resumed; contacts are then split until a winner is selected. Present for sequence tests." }, "settings": { "type": "object", "additionalProperties": true, "description": "Effective settings for this test kind. Campaign tests return testPercentage, testDurationMinutes, and winnerCriteria; sequence tests return testType, winnerThreshold, and winnerCriteria." }, "winningVariantId": { "type": [ "string", "null" ] }, "winnerSelectedAt": { "type": [ "string", "null" ], "format": "date-time" }, "testStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "testEndsAt": { "type": [ "string", "null" ], "format": "date-time" }, "pendingSampleUpdate": { "type": [ "object", "null" ], "description": "Durable campaign sample request, null when absent or applied. Retry the same testPercentage after an interrupted request; error enables explicit discard.", "properties": { "id": { "type": "string" }, "testPercentage": { "type": "integer" }, "requestedAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time", "description": "Optional publication claim timestamp." }, "error": { "type": "string" } } }, "progress": { "type": [ "object", "null" ], "description": "Present on campaign detail and settings responses. Null if the campaign is missing. Counts unique recipient deliveries across retry attempts, excluding separate test emails.", "properties": { "campaignStatus": { "type": "string" }, "pauseReason": { "type": [ "string", "null" ] }, "audienceSize": { "type": [ "integer", "null" ], "description": "Original send-time audience size; null for legacy campaigns without an estimate." }, "committed": { "type": "integer", "description": "Recipients with a durable send attempt, including pending or failed sends." }, "sent": { "type": "integer", "description": "Recipients with a sentAt timestamp on an attempt." }, "remaining": { "type": [ "integer", "null" ], "description": "Audience size minus committed recipients, floored at zero; null when size is unavailable." }, "minimumTestPercentage": { "type": [ "integer", "null" ], "description": "Minimum whole percentage that contains committed recipients, at least 5; null without audience size. Workers revalidate against later sends." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": [ "string", "null" ] }, "committed": { "type": "integer" }, "sent": { "type": "integer" }, "pending": { "type": "integer" }, "failed": { "type": "integer", "description": "Recipients with failed attempts and no successful or pending attempt." } } } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ABTestVariant" } } } }, "Account": { "type": "object", "description": "A B2B account (organization, workspace or team) that contacts belong to.", "properties": { "id": { "type": "string", "example": "acc_abc123" }, "externalId": { "type": "string", "description": "Customer-owned organization ID, unique per workspace.", "example": "org_123" }, "name": { "type": [ "string", "null" ], "example": "Acme" }, "domain": { "type": [ "string", "null" ], "example": "acme.com" }, "attributes": { "type": "object", "additionalProperties": true, "description": "Account attributes, fanned out to members as `account.`.", "example": { "plan": "pro", "seats": 5 } }, "memberCount": { "type": "integer" }, "lastEventAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AccountReference": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" } } }, "AccountMember": { "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "subscriberId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "email": { "type": [ "string", "null" ] }, "externalId": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "AccountUpsertInput": { "type": "object", "required": [ "externalId" ], "properties": { "externalId": { "type": "string", "maxLength": 255, "example": "org_123" }, "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ], "description": "Normalized to a hostname such as acme.com." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Up to 100 attributes. Null values delete keys when merging." }, "replaceAttributes": { "type": "boolean", "default": false }, "members": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "externalId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } } } } }, "AccountPatchInput": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "additionalProperties": true }, "replaceAttributes": { "type": "boolean" } } }, "AccountUpsertResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "created": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" }, "members": { "type": "array", "items": { "type": "object", "properties": { "subscriberId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "externalId": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "created": { "type": "boolean" } } } } } }, "AccountMemberChangeResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" }, "member": { "type": "object", "properties": { "subscriberId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "externalId": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "created": { "type": "boolean" }, "subscriberCreated": { "type": "boolean" } } } } }, "AccountOrganizationIdKey": { "type": "object", "required": [ "propertyKey" ], "properties": { "propertyKey": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Event property or contact attribute holding your organization ID, such as `workspaceId`. Trimmed." }, "source": { "type": "string", "enum": [ "event", "attribute" ], "default": "event", "description": "Where the ID lives." }, "nameKey": { "type": [ "string", "null" ], "maxLength": 255, "description": "Property or attribute holding the organization name. Without it, accounts are named after the work email domain their contacts share." } } }, "AccountOrganizationIdCandidate": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "event", "attribute" ] }, "propertyKey": { "type": "string" }, "nameKey": { "type": [ "string", "null" ], "description": "Sibling property with the organization name, when found." }, "eventCount": { "type": "integer", "description": "Events carrying the key (`event`) or contacts with the attribute (`attribute`)." }, "accountCount": { "type": "integer", "description": "Distinct organizations, the accounts creating would make." }, "eventNames": { "type": "array", "items": { "type": "string" }, "description": "Up to 8 event names carrying the key. Empty for attributes." } } }, "AccountOrganizationIdPreview": { "type": "object", "properties": { "externalId": { "type": "string", "description": "The organization ID, which becomes the account's external ID." }, "name": { "type": [ "string", "null" ], "description": "The name the account gets. From `nameKey` when set, otherwise from the work email domain most of its contacts share. Null when neither exists." }, "domain": { "type": [ "string", "null" ], "description": "Work email domain most of its contacts share. Personal and disposable providers and your own sending domains are ignored." }, "contactCount": { "type": "integer", "description": "Contacts that would become members." }, "sampleEmails": { "type": "array", "items": { "type": "string" }, "description": "Up to 3 of those contacts, those at `domain` first." } } }, "AccountOrganizationIdJob": { "type": "object", "properties": { "jobId": { "type": "string" }, "settings": { "type": [ "object", "null" ], "description": "What the run reads. A run already in progress for the same `propertyKey` keeps its own `source` and `nameKey`, which may differ from a later request.", "properties": { "source": { "type": "string", "enum": [ "event", "attribute", "domains" ] }, "propertyKey": { "type": "string" }, "nameKey": { "type": [ "string", "null" ] } } }, "state": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "result": { "type": [ "object", "null" ], "description": "Present when `completed`.", "properties": { "accountsCreated": { "type": "integer" }, "accountsUpdated": { "type": "integer", "description": "Existing accounts that got a name or domain." }, "membershipsCreated": { "type": "integer" }, "membershipsUpdated": { "type": "integer" }, "skipped": { "type": "integer", "description": "Contacts that no longer exist, or invalid IDs." }, "truncated": { "type": "boolean", "description": "History was larger than one run covers. Start the job again to continue." } } }, "error": { "type": [ "string", "null" ], "description": "Present when `failed`." } } }, "AccountSuggestion": { "type": "object", "properties": { "domain": { "type": "string", "example": "acme.com" }, "name": { "type": "string", "description": "Name the account gets when the suggestion is accepted.", "example": "Acme" }, "contactCount": { "type": "integer", "description": "Contacts at the domain. Domains with any contact in an account are not suggested.", "example": 7 }, "sampleEmails": { "type": "array", "maxItems": 10, "description": "Up to 10 of those contacts' emails, alphabetical, so you can check who is behind the suggestion.", "items": { "type": "string" }, "example": [ "ana@acme.com", "ben@acme.com" ] } } }, "AccountSuggestionsAcceptResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "accountsCreated": { "type": "integer" }, "membershipsCreated": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "updated", "skipped" ] }, "reason": { "type": [ "string", "null" ], "enum": [ "no_contacts", "multiple_accounts", "already_in_account", null ] }, "account": { "oneOf": [ { "$ref": "#/components/schemas/Account" }, { "type": "null" } ] }, "contactCount": { "type": "integer", "description": "Eligible contacts at the domain (in no account, or already in this one), before the 5,000 member cap." }, "membersAdded": { "type": "integer" }, "truncated": { "type": "boolean", "description": "True when contacts were left out because accounts hold at most 5,000 members (the attribute fan-out limit)." } } } } } }, "AccountEvent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "eventTime": { "type": "string", "format": "date-time" }, "properties": { "type": [ "object", "null" ], "additionalProperties": true }, "recipientCount": { "type": "integer" } } }, "Subscriber": { "type": "object", "properties": { "id": { "type": "string", "example": "sub_abc123" }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Null for phone-only (SMS) contacts, which are identified by their phone number instead.", "example": "user@example.com" }, "externalId": { "type": [ "string", "null" ], "description": "Customer-owned app/customer/user ID for this subscriber", "example": "user_123" }, "firstName": { "type": [ "string", "null" ], "example": "John" }, "lastName": { "type": [ "string", "null" ], "example": "Doe" }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone identifier used for recipient-local campaign delivery. Null when unknown.", "example": "America/New_York" }, "phone": { "type": [ "string", "null" ], "description": "Phone number in E.164 format", "example": "+15551234567" }, "smsStatus": { "type": "string", "enum": [ "not_subscribed", "pending", "subscribed", "unsubscribed" ], "description": "SMS marketing consent status, independent of the email status", "example": "subscribed" }, "status": { "type": "string", "enum": [ "active", "unsubscribed", "bounced" ], "example": "active" }, "unsubscribedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the contact opted out, derived from the list memberships the opt-out deactivated. Use this rather than `updatedAt` to date an opt-out - any later tag or attribute write moves `updatedAt`. Null unless the contact is currently unsubscribed, so leaving a single list does not set it, and null for contacts imported as already unsubscribed, where no date exists.", "example": "2026-07-15T10:00:00.000Z" }, "emailProvider": { "type": [ "string", "null" ], "example": "gmail" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "premium", "newsletter" ] }, "customAttributes": { "type": "object", "additionalProperties": true, "example": { "plan": "pro", "signupSource": "website" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "phoneCountry": { "type": [ "string", "null" ], "description": "Two-letter ISO country code associated with the normalized phone number, or null when unavailable.", "example": "US" } } }, "SubscriberImportRecord": { "type": "object", "description": "Every record must include an email or a phone. Records with only a phone import as phone-only (SMS) contacts.", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "description": "Optional when the record has a phone." }, "externalId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "timezone": { "type": "string", "maxLength": 64, "description": "IANA timezone identifier (e.g. America/New_York) used for recipient-local campaign delivery. Records with an invalid value import without it." }, "phone": { "type": "string", "maxLength": 64, "description": "Phone number. National-format values use the batch defaultPhoneCountry. Required when the record has no email." }, "status": { "type": "string", "enum": [ "active", "unsubscribed", "bounced" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "customAttributes": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, { "type": "null" } ] } }, "createdAt": { "type": "string", "format": "date-time", "description": "Original signup date on the source platform. Preserves the contact's real history so date-relative segments are correct right after the import. An existing contact's date only ever moves earlier. An unusable value rejects the whole request with a 400 naming the row.", "example": "2019-03-14T09:30:00Z" } } }, "SubscriberImport": { "type": "object", "properties": { "id": { "type": "string" }, "batchId": { "type": "string" }, "fileName": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed" ] }, "totalRows": { "type": "integer" }, "emailCount": { "type": "integer" }, "duplicateRows": { "type": "integer" }, "addedCount": { "type": "integer" }, "updatedCount": { "type": "integer" }, "skippedCount": { "type": "integer" }, "failedCount": { "type": "integer" }, "processedCount": { "type": "integer" }, "totalChunks": { "type": "integer" }, "completedChunks": { "type": "integer" }, "failedChunks": { "type": "integer" }, "skippedReasons": { "type": "object", "description": "Count per reason a row was skipped. The values sum to skippedCount.", "additionalProperties": { "type": "integer" } }, "failedReasons": { "type": "object", "additionalProperties": { "type": "integer" } }, "failedChunkReasons": { "type": "object", "additionalProperties": { "type": "integer" } }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SubscriberNote": { "type": "object", "properties": { "id": { "type": "string", "example": "note_123" }, "companyId": { "type": "string", "example": "comp_abc123" }, "subscriberId": { "type": "string", "example": "sub_abc123" }, "authorId": { "type": "string", "example": "user_123" }, "body": { "type": "string", "example": "Asked about enterprise pricing" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "author": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "example": "user_123" }, "name": { "type": [ "string", "null" ], "example": "Ana" }, "email": { "type": [ "string", "null" ], "example": "ana@example.com" } } } } }, "SubscriberListMembership": { "type": "object", "properties": { "id": { "type": "string", "example": "list_vip" }, "name": { "type": "string", "example": "VIP Customers" }, "description": { "type": [ "string", "null" ] }, "isPrivate": { "type": [ "boolean", "null" ], "description": "Whether the list is private. Private lists are omitted from the hosted subscriber email preferences/unsubscribe page and cannot be subscribed to or unsubscribed from individually there. List privacy does not override a subscriber's global unsubscribe." }, "subscribedAt": { "type": "string", "format": "date-time" }, "unsubscribedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "SubscriberSequenceEnrollment": { "type": "object", "properties": { "tokenId": { "type": "string", "example": "token_123" }, "sequenceId": { "type": "string", "example": "seq_welcome" }, "sequenceName": { "type": "string", "example": "Welcome Flow" }, "sequenceStatus": { "type": "string", "example": "active" }, "enrollmentStatus": { "type": "string", "example": "active" }, "currentNodeId": { "type": "string", "example": "node_abc" }, "currentNodeType": { "type": [ "string", "null" ], "example": "action_email" }, "currentNodeLabel": { "type": [ "string", "null" ], "example": "Send welcome email" }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time" }, "enteredAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SubscriberEmailStats": { "type": "object", "properties": { "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "bounced": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "complained": { "type": "integer" } } }, "SubscriberActivityEvent": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string", "example": "custom", "description": "Email event type (send, delivery, open, click, bounce, complaint, unsubscribe, delivery_delay), \"custom\" for subscriber events, or an SMS event type (sms_sent, sms_delivered, sms_failed, sms_clicked, sms_opted_out). New types may be added over time.\n" }, "eventTime": { "type": "string", "format": "date-time" }, "emailSendId": { "type": [ "string", "null" ] }, "campaignId": { "type": [ "string", "null" ] }, "clickedUrl": { "type": [ "string", "null" ] }, "machine": { "type": "boolean", "description": "Whether this open/click event is classified as bot/scanner activity." }, "engagementQuality": { "type": [ "string", "null" ], "enum": [ "human", "machine", "asset", null ], "description": "Engagement classification for open/click events." }, "classificationReasons": { "type": "array", "items": { "type": "string" }, "description": "Classification reason codes for open/click events." }, "bounceType": { "type": [ "string", "null" ] }, "smsSendId": { "type": [ "string", "null" ], "description": "SMS send this event belongs to. Present only on sms_* events." }, "smsErrorCode": { "type": [ "string", "null" ], "description": "Carrier or provider error code. Present only on sms_failed events." }, "smsSegments": { "type": [ "integer", "null" ], "description": "Number of SMS segments the message was split into. Present only on sms_* events." }, "eventName": { "type": [ "string", "null" ], "example": "saas.purchase" }, "properties": { "type": [ "object", "null" ], "additionalProperties": true } } }, "FilterLeaf": { "type": "object", "description": "A single subscriber filter rule.", "properties": { "kind": { "type": "string", "enum": [ "filter" ], "description": "Required when the filter is inside a v2 root group." }, "id": { "type": "string", "example": "filter-1" }, "field": { "type": "string", "enum": [ "status", "phone", "smsStatus", "tag", "email", "emailProvider", "added", "firstName", "lastName", "list", "attribute", "event", "segment", "stripeProduct", "stripeCurrentProduct", "stripeTrialProduct", "commerceProduct", "commerceCollection", "emailSent", "emailDelivered", "emailOpened", "emailClicked", "emailBounced", "emailComplained" ] }, "operator": { "type": "string", "description": "Valid operators depend on the field. status/segment: is, is_not. smsStatus: is, is_not (values: subscribed, unsubscribed, not_subscribed). phone: is_not_empty, is_empty (empty value). tag: contains, not_contains, is_empty, is_not_empty. email: contains, not_contains for domain or substring matching, is, is_not for an exact case-insensitive address. emailProvider/list: is, is_not, is_empty, is_not_empty. firstName/lastName: contains, not_contains, is_empty, is_not_empty. added: less_than, more_than. attribute: is, is_not, is_empty, is_not_empty, gte, lte, gt, lt, contains, not_contains. event and email engagement fields: is, is_not, at_least, less_than_count. emailBounced also supports is_temporary_bounce and is_permanent_bounce. stripeProduct: is, is_not, at_least, less_than_count. stripeCurrentProduct/stripeTrialProduct: is, is_not, gte, lte, gt, lt. commerceProduct/commerceCollection: is, is_not, at_least, less_than_count.", "enum": [ "is", "is_not", "is_empty", "is_not_empty", "contains", "not_contains", "less_than", "more_than", "is_temporary_bounce", "is_permanent_bounce", "at_least", "less_than_count", "gte", "lte", "gt", "lt" ] }, "value": { "type": "string", "description": "Event filters use `eventName:30d` or `eventName:5:30d`. Segment filters use a segment ID. Email engagement fields use a rolling time window (`7d`, `30d`, `90d`, `180d`, `all`), a specific campaign via `campaign:`, an email-type scope via `marketing:` (marketing-policy campaign, automation, and Send API traffic) or `transactional:` (transactional-policy sends; with is/is_not or the emailBounced subtype operators; scopes require a send-time policy snapshot, so ambiguous older events remain unscoped), or `count:timeRange` (such as `10:30d` or `10:all`) with at_least/less_than_count. Stripe product filters use `prod_123` for bought/current/trialing checks, `prod_123:3` for payment thresholds, and product-scoped values such as `prod_123:is_canceled`, `prod_123:cancels_at:2026-05-26`, `prod_123:end_at:2026-05-26`, or `prod_123:start_at:7 days ago`. Commerce product filters use `provider:productId` (provider one of `shopify`, `woocommerce`, `api`), optionally with an order-count threshold (`shopify:42:2`); a bare product ID matches the ID on any provider. Commerce collection filters use a collection ID or handle (`skincare`), optionally provider-prefixed and/or with an order-count threshold (`shopify:skincare:2`), and match anyone whose orders contain any product currently in that collection." } }, "required": [ "id", "field", "operator", "value" ] }, "FilterGroup": { "type": "object", "description": "A nested AND/OR filter group.", "properties": { "kind": { "type": "string", "enum": [ "group" ] }, "id": { "type": "string", "example": "root" }, "joinOperator": { "type": "string", "enum": [ "and", "or" ] }, "children": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/FilterLeaf" }, { "$ref": "#/components/schemas/FilterGroup" } ], "discriminator": { "propertyName": "kind", "mapping": { "filter": "#/components/schemas/FilterLeaf", "group": "#/components/schemas/FilterGroup" } } } } }, "required": [ "kind", "id", "joinOperator", "children" ] }, "Segment": { "type": "object", "properties": { "id": { "type": "string", "example": "seg_active_buyers" }, "name": { "type": "string", "example": "Active buyers" }, "filters": { "type": "array", "description": "Legacy v1 flat filters, or flattened leaves for v2 responses.", "items": { "$ref": "#/components/schemas/FilterLeaf" } }, "filterJoinOperator": { "type": "string", "enum": [ "and", "or" ] }, "format": { "type": "string", "enum": [ "v1", "v2" ] }, "root": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/FilterGroup" } ] }, { "type": "null" } ] }, "subscriberCount": { "type": "integer" }, "activeSubscriberCount": { "type": "integer" } } }, "AudienceSync": { "type": "object", "description": "A segment-to-Meta-custom-audience sync mapping.", "properties": { "id": { "type": "string", "example": "sync_abc123" }, "segmentId": { "type": "string", "example": "seg_recent_buyers" }, "segmentName": { "type": [ "string", "null" ], "example": "Recent buyers" }, "adAccountId": { "type": "string", "example": "act_1234567890" }, "audienceName": { "type": "string", "example": "Sequenzy - Recent buyers" }, "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] }, "isActive": { "type": "boolean" }, "syncStatus": { "type": "string", "description": "idle, syncing, error, or disconnected (the Meta connection was revoked; the sync is paused until you reconnect)", "example": "idle" }, "lastSyncAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastSyncError": { "type": [ "string", "null" ] }, "lastSyncedCount": { "type": "integer", "description": "Subscribers uploaded in the most recent run." }, "createdAt": { "type": "string", "format": "date-time" } } }, "AdAccount": { "type": "object", "properties": { "id": { "type": "string", "example": "act_1234567890" }, "name": { "type": "string", "example": "Acme Main Account" } } }, "ProductDigitalDelivery": { "type": [ "object", "null" ], "description": "Distributable file delivered after a purchase of this product.", "properties": { "url": { "type": "string", "example": "https://images.sequenzy.com/product-files/comp_123/9f2.../guide.pdf" }, "source": { "type": "string", "enum": [ "upload", "url" ] }, "fileName": { "type": [ "string", "null" ], "example": "guide.pdf" }, "fileSizeBytes": { "type": [ "integer", "null" ] }, "mimeType": { "type": [ "string", "null" ], "example": "application/pdf" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "example": "prod_internal_1" }, "provider": { "type": "string", "enum": [ "api", "stripe", "shopify", "woocommerce", "manual" ] }, "providerProductId": { "type": [ "string", "null" ], "example": "prod_ABC123" }, "title": { "type": "string", "example": "The Indie Hacker Guide" }, "description": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "price": { "type": [ "integer", "null" ], "description": "Price in cents", "example": 4900 }, "currency": { "type": [ "string", "null" ], "example": "USD" }, "url": { "type": [ "string", "null" ] }, "inStock": { "type": [ "boolean", "null" ], "description": "For Stripe products, false means archived in Stripe." }, "digitalDelivery": { "$ref": "#/components/schemas/ProductDigitalDelivery" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "DetailedSubscriber": { "allOf": [ { "$ref": "#/components/schemas/Subscriber" }, { "type": "object", "properties": { "lists": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberListMembership" } }, "sequenceEnrollments": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberSequenceEnrollment" } }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberNote" } }, "emailStats": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SubscriberEmailStats" } ] }, { "type": "null" } ] }, "activity": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberActivityEvent" } } } } ] }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 100 }, "totalPages": { "type": "integer", "example": 5 } } }, "SubscriberListPagination": { "type": "object", "description": "Pagination for the subscriber list endpoint. `total` and `totalPages` are null on cursor requests because the count query is skipped.", "properties": { "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 1000 }, "total": { "type": [ "integer", "null" ], "example": 8718 }, "totalPages": { "type": [ "integer", "null" ], "example": 9 }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass back as `cursor` to fetch the next page. Null when there are no further results.", "example": "eyJ2ZXJzaW9uIjoxLCJzb3J0IjoiY3JlYXRlZF9hdF9kZXNjX2lkX2Rlc2MifQ" }, "hasMore": { "type": "boolean", "example": true }, "orderBy": { "type": "string", "description": "Sort key the cursor walks.", "example": "created_at_desc_id_desc" } } }, "TransactionalEmail": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" }, "description": "Assigned company label names. Empty when unlabelled.", "example": [ "Billing", "Receipts" ] }, "id": { "type": "string", "example": "tx_abc123" }, "name": { "type": "string", "example": "Welcome Email" }, "slug": { "type": "string", "example": "welcome-email" }, "emailId": { "type": "string", "example": "email_123" }, "enabled": { "type": "boolean", "example": true }, "managedBy": { "type": "string", "enum": [ "dashboard", "code" ], "description": "`code` when the email was created by a direct-content send with `trackAs`. Its content is a snapshot of a recent send, it cannot be sent by slug, and only `name`, `enabled` and `labels` can be updated. `dashboard` for every other transactional email.", "example": "dashboard" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TransactionalEmailListItem": { "allOf": [ { "$ref": "#/components/schemas/TransactionalEmail" }, { "type": "object", "properties": { "subject": { "type": [ "string", "null" ] }, "emailPreset": { "$ref": "#/components/schemas/EmailPreset" }, "stats": { "type": "object", "properties": { "sends": { "type": "integer" }, "deliveries": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "bounces": { "type": "integer" }, "openRate": { "type": "number", "format": "float" }, "clickRate": { "type": "number", "format": "float" } } } } } ] }, "TransactionalEmailDetails": { "allOf": [ { "$ref": "#/components/schemas/TransactionalEmail" }, { "type": "object", "properties": { "variables": { "type": "array", "items": { "type": "string" }, "example": [ "NAME", "COMPANY", "PRODUCT" ] }, "subject": { "type": [ "string", "null" ], "example": "Welcome, {{NAME}}" }, "previewText": { "type": [ "string", "null" ], "example": "Your account is ready." }, "emailPreset": { "$ref": "#/components/schemas/EmailPreset" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "email": { "oneOf": [ { "$ref": "#/components/schemas/Email" }, { "type": "null" } ] } } } ] }, "Attachment": { "type": "object", "required": [ "filename" ], "properties": { "filename": { "type": "string", "description": "The filename for the attachment (including extension)", "example": "invoice.pdf" }, "content": { "type": "string", "description": "Base64-encoded file content (mutually exclusive with path)", "example": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC..." }, "path": { "type": "string", "format": "uri", "description": "URL to fetch the file from (mutually exclusive with content)", "example": "https://example.com/files/invoice.pdf" }, "contentType": { "type": "string", "description": "MIME type of the attachment (optional, auto-detected from the filename if not provided)", "example": "application/pdf" }, "contentId": { "type": "string", "description": "Content-ID that embeds the file as an inline image instead of attaching it. Reference it from the HTML body as ``; the message is then sent as multipart/related, which is the only embedded-image form Gmail renders. If nothing in the HTML references the value, the file is sent as a normal attachment.", "example": "ticket-qr" } } }, "UrlAttachment": { "type": "object", "description": "URL-backed email attachment. The file is fetched from the URL at send time (max 10 attachments and 15MB total per email). For event-triggered sequences, path may be an event merge tag such as {{event.file_url}} that resolves to a public URL for each enrollment. Base64 content is not supported here.", "required": [ "filename", "path" ], "properties": { "filename": { "type": "string", "description": "Filename shown in the recipient's email client (including extension). Event merge tags are supported.", "example": "guide.pdf" }, "path": { "type": "string", "description": "Public HTTP(S) URL or an event-backed URL template such as {{event.file_url}}. The resolved URL is validated and fetched at send time.", "example": "https://example.com/files/guide.pdf" } } }, "EmailBlockTypeReference": { "type": "object", "description": "Field reference for one email block type. Lists are their own block type rather than a text variant: a `text` block accepts only variant paragraph, lead, or html and never accepts `items`.", "properties": { "type": { "type": "string", "example": "steps" }, "creatable": { "type": "boolean", "description": "False for structural types the editor manages, which should not be hand-authored." }, "reason": { "type": "string", "description": "Why a non-creatable type is excluded." }, "required": { "type": "array", "items": { "type": "string" }, "example": [ "items", "variant" ] }, "optional": { "type": "array", "items": { "type": "string" }, "example": [ "id", "accentColor", "styles", "conditions" ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlockFieldReference" } }, "example": { "type": "object", "description": "A minimal valid block of this type.", "additionalProperties": true }, "notes": { "type": "array", "items": { "type": "string" } } } }, "EmailBlockConditionFieldReference": { "type": "object", "description": "One field a block condition may filter on. A block's own `field` and `operator` entries are two flat enums that pool every field's operators together, and the schema narrows them against each other when it validates - so `{\"field\": \"tag\", \"operator\": \"is\"}` parses and is then rejected. This is that narrowing, spelled out.", "properties": { "field": { "type": "string", "example": "tag" }, "label": { "type": "string", "example": "Tag" }, "operators": { "type": "array", "description": "The only operators this field accepts.", "items": { "type": "string" }, "example": [ "contains", "not_contains", "is_empty", "is_not_empty" ] }, "values": { "type": "array", "description": "Closed value set, for the fields that have one.", "items": { "type": "string" } }, "valueFormat": { "type": "string", "description": "How the `value` string is shaped for this field." }, "serverEvaluated": { "type": "boolean", "description": "Whether the field reads stored subscriber state rather than the merge data of the send." }, "previewSupport": { "type": "string", "enum": [ "any_contact", "inline_tags_or_stored_subscriber", "stored_subscriber" ], "description": "What a render needs before it can evaluate this field. any_contact - resolved from merge data. inline_tags_or_stored_subscriber - tag, which an inline contact can state for itself. stored_subscriber - needs subscriberId. A condition a render cannot evaluate renders as false and is listed in that render's unevaluatedConditions." }, "example": { "type": "object", "description": "A valid condition using this field.", "additionalProperties": true } }, "required": [ "field", "label", "operators", "valueFormat", "serverEvaluated", "previewSupport", "example" ] }, "EmailBlockFieldReference": { "type": "object", "properties": { "name": { "type": "string", "example": "variant" }, "required": { "type": "boolean" }, "type": { "type": "string", "description": "Value shape, for example string, number, boolean, enum, array, or object.", "example": "enum" }, "values": { "type": "array", "description": "Allowed values, for enum and literal-union fields.", "items": {}, "example": [ "numbered", "timeline" ] }, "itemFields": { "type": "array", "description": "Shape of one entry in an array field. This is where `list` and `steps` differ: list items carry `content`, steps items carry `title` and an optional `description`.", "items": { "$ref": "#/components/schemas/EmailBlockFieldReference" } }, "fields": { "type": "array", "description": "Shape of an object field, for example the `mode`, `strategy`, `lookbackDays`, `sort`, and `filters` of a repeat block's `productSource`.", "items": { "$ref": "#/components/schemas/EmailBlockFieldReference" } } } }, "EmailBlock": { "type": "object", "description": "Email content block. The shape depends on the block type. Any block may carry a `conditions` array so it renders only for matching recipients, the structural `group` type wraps children in Stack, Row, Grid, or Overlay layout, and `conditional-group` adds if/else branching via `ifBranch` and `elseBranch` (each an object with a `children` array).", "required": [ "type" ], "properties": { "id": { "type": "string", "example": "block_123" }, "type": { "type": "string", "enum": [ "text", "html", "heading", "list", "button", "spacer", "divider", "image", "columns", "group", "conditional-group", "repeat", "card", "cta", "social", "logo", "header", "footer", "video", "product", "discount-code", "code", "countdown", "hero", "testimonial", "gallery", "badge", "table", "features", "image-card", "pricing", "author", "article", "rating", "stats", "steps", "product-grid", "poll" ], "example": "html" }, "content": { "type": "string", "description": "Content for text, html, and heading-like blocks.", "example": "

Hello

" }, "label": { "type": "string", "maxLength": 120, "default": "Group", "description": "Editor label for a structural group block." }, "layout": { "type": "string", "enum": [ "stack", "row", "grid", "overlay" ], "default": "stack", "description": "Direct-child layout for a structural group block." }, "columns": { "type": "integer", "minimum": 1, "maximum": 4, "default": 2, "description": "Number of columns used by a group with grid layout." }, "gap": { "type": "integer", "minimum": 0, "maximum": 64, "default": 16, "description": "Gap in pixels between direct group children." }, "padding": { "type": "integer", "minimum": 0, "maximum": 64, "default": 0, "description": "Uniform group padding in pixels; per-side styles.padding* fields override it." }, "overlayColor": { "type": "string", "default": "#000000", "description": "Opaque fallback and shade color for an overlay group." }, "overlayShade": { "type": "integer", "minimum": 0, "maximum": 100, "default": 35, "description": "Overlay shade intensity as a percentage." }, "overlayPosition": { "type": "string", "enum": [ "top", "center", "bottom" ], "default": "center", "description": "Vertical position of overlay foreground content." }, "children": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Recursive child blocks for group and repeat containers.", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "styles": { "type": "object", "description": "Per-block visual styles. For compatibility, style fields such as backgroundColor, backgroundOpacity, borderColor, borderWidth, and borderRadius can also be supplied at the block top level and are normalized into this object.", "additionalProperties": false, "properties": { "paddingTop": { "type": "number" }, "paddingBottom": { "type": "number" }, "paddingLeft": { "type": "number" }, "paddingRight": { "type": "number" }, "backgroundColor": { "type": "string", "example": "#f8fafc" }, "backgroundOpacity": { "type": "number", "minimum": 0, "maximum": 100, "description": "Background opacity percentage from 0 to 100.", "example": 80 }, "textColor": { "type": "string", "example": "#111827" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "borderRadius": { "type": "number", "example": 12 }, "borderColor": { "type": "string", "example": "#cbd5e1" }, "borderWidth": { "type": "number", "example": 1 }, "bleed": { "type": "boolean", "description": "Stretch the block edge-to-edge across the email container. Top-level blocks only." } } }, "conditions": { "type": "array", "description": "Optional per-block display rules. The block renders only when every rule matches. The same shape is used for a conditional-group block's top-level `conditions`.", "items": { "type": "object", "required": [ "id", "field", "operator", "value" ], "properties": { "id": { "type": "string", "example": "c1" }, "field": { "type": "string", "enum": [ "variable", "attribute", "email", "firstName", "lastName" ], "description": "`variable` resolves a merge-tag path from the transactional send `variables` or an automation `event` payload (nested paths like `order.total` or `event.plan` work). `attribute` reads a stored subscriber attribute. `email`, `firstName`, and `lastName` read core subscriber fields." }, "operator": { "type": "string", "enum": [ "is", "is_not", "contains", "not_contains", "gt", "gte", "lt", "lte", "is_empty", "is_not_empty" ] }, "value": { "type": "string", "description": "For `variable` and `attribute`, use `name:value` - the part before the colon is the variable path or attribute name, and the part after it is the comparison value. For `email`, `firstName`, and `lastName`, provide the plain comparison string.", "example": "plan:pro" } } } } }, "additionalProperties": true }, "Email": { "type": "object", "properties": { "id": { "type": "string", "example": "email_123" }, "companyId": { "type": "string", "example": "company_123" }, "name": { "type": "string", "example": "Welcome email" }, "subject": { "type": "string", "example": "Welcome" }, "previewText": { "type": [ "string", "null" ], "example": "Here's what to do next" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "FooterApplicationOptions": { "type": "object", "required": [ "scopes" ], "properties": { "scopes": { "type": "array", "items": { "type": "string", "enum": [ "sequences", "campaigns", "transactional", "templates" ] } }, "includeCustomized": { "type": "boolean", "default": false } } }, "FooterApplicationItem": { "type": "object", "required": [ "id", "name", "kind", "scope" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "email", "ab_variant", "localization" ] }, "scope": { "type": "string", "enum": [ "sequences", "campaigns", "transactional", "templates" ] }, "reason": { "type": "string", "enum": [ "customized", "no_footer", "ambiguous_footer", "raw_html", "protected", "shared" ] } } }, "FooterApplicationPreview": { "type": "object", "required": [ "token", "counts", "affected", "skipped" ], "properties": { "token": { "type": "string", "description": "Pass as previewToken with identical input when applying. Relevant content changes invalidate it." }, "counts": { "type": "object", "properties": { "sequences": { "type": "integer" }, "campaigns": { "type": "integer" }, "transactional": { "type": "integer" }, "templates": { "type": "integer" } } }, "affected": { "type": "array", "items": { "$ref": "#/components/schemas/FooterApplicationItem" } }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/FooterApplicationItem" } } } }, "FooterRenderedPreview": { "type": "object", "properties": { "footerHtml": { "type": "string" }, "note": { "type": "string" }, "samples": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/FooterApplicationItem" }, { "type": "object", "properties": { "beforeHtml": { "type": "string" }, "afterHtml": { "type": "string" } } } ] } } } }, "EmailComponent": { "type": "object", "properties": { "id": { "type": "string", "example": "cmp_123" }, "companyId": { "type": "string", "example": "company_123" }, "name": { "type": "string", "example": "Default Footer" }, "description": { "type": [ "string", "null" ], "example": null }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "componentType": { "type": "string", "enum": [ "section", "footer" ], "example": "footer" }, "defaultSlot": { "type": [ "string", "null" ], "enum": [ "footer", null ], "description": "Slot this component is pinned as the company default for, or null when it is an ordinary saved component.", "example": "footer" }, "version": { "type": "integer", "description": "Incremented every time the component's blocks are replaced. Emails cloned from an earlier version keep those blocks.", "example": 3 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EmailSendEvent": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_123" }, "emailSendId": { "type": "string", "example": "send_123" }, "companyId": { "type": "string", "example": "company_123" }, "campaignId": { "type": [ "string", "null" ] }, "transactionalEmailId": { "type": [ "string", "null" ] }, "subscriberId": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "emailName": { "type": [ "string", "null" ], "example": "Welcome" }, "emailType": { "type": [ "string", "null" ], "enum": [ "campaign", "transactional", "sequence", null ], "description": "Send-source category retained for analytics compatibility. Use deliveryPolicy for the actual marketing or transactional policy." }, "deliveryPolicy": { "type": [ "string", "null" ], "enum": [ "marketing", "transactional", null ], "description": "Delivery policy used for suppression and compliance behavior, or null when retained legacy events cannot prove it." }, "abTestId": { "type": [ "string", "null" ] }, "abTestVariantId": { "type": [ "string", "null" ] }, "eventType": { "type": "string", "example": "delivery" }, "bounceType": { "type": [ "string", "null" ] }, "bounceSubType": { "type": [ "string", "null" ] }, "complaintType": { "type": [ "string", "null" ] }, "clickedUrl": { "type": [ "string", "null" ] }, "ipAddress": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] }, "countryCode": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "eventTime": { "type": "string", "format": "date-time" } } }, "EmailSend": { "type": "object", "properties": { "id": { "type": "string", "example": "send_123" }, "companyId": { "type": "string", "example": "company_123" }, "type": { "type": [ "string", "null" ], "enum": [ "campaign", "transactional", "sequence", null ], "description": "Send-source category. API/MCP sends use transactional here even when their delivery policy is marketing." }, "emailType": { "type": [ "string", "null" ], "enum": [ "marketing", "transactional", null ], "description": "Delivery policy used for suppression and compliance behavior, or null when retained legacy data cannot prove it." }, "isTransactional": { "type": [ "boolean", "null" ], "description": "Stored delivery-policy snapshot. Prefer emailType for a normalized value." }, "isTestEmail": { "type": "boolean", "description": "Whether this delivery was a test send hidden from normal sent-email history." }, "campaignId": { "type": [ "string", "null" ] }, "transactionalEmailId": { "type": [ "string", "null" ] }, "automationNodeId": { "type": [ "string", "null" ] }, "automationTokenId": { "type": [ "string", "null" ] }, "abTestVariantId": { "type": [ "string", "null" ] }, "subscriberId": { "type": [ "string", "null" ] }, "subscriberExternalId": { "type": [ "string", "null" ], "description": "Customer-owned subscriber ID captured from a single-recipient transactional send." }, "recipientEmail": { "type": [ "string", "null" ], "format": "email" }, "additionalRecipients": { "type": [ "object", "null" ], "description": "Full recipient envelope for multi-recipient transactional sends, as actually sent. Null for single-recipient sends.", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email" } }, "cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" } } } }, "subject": { "type": [ "string", "null" ], "example": "Welcome" }, "senderEmail": { "type": [ "string", "null" ], "format": "email" }, "senderName": { "type": [ "string", "null" ] }, "authenticatedDomainId": { "type": [ "string", "null" ] }, "originalReplyTo": { "type": [ "string", "null" ], "description": "Resolved reply destination, optionally including a display name. When reply tracking is disabled, this is the sent Reply-To header. When reply tracking is enabled, the sent header is a unique trackable address and this value is the forwarding destination." }, "sendingIpAddress": { "type": [ "string", "null" ] }, "observedSendingIpAddress": { "type": [ "string", "null" ] }, "sesMessageId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "sent", "delivered", "opened", "clicked", "bounced", "complained", "failed", "suppressed" ] }, "bounceType": { "type": [ "string", "null" ] }, "bounceSubType": { "type": [ "string", "null" ] }, "complaintType": { "type": [ "string", "null" ] }, "suppressionReason": { "type": [ "string", "null" ], "enum": [ "bounced", "complaint", "unsubscribed", null ] }, "errorMessage": { "type": [ "string", "null" ] }, "internalFailureCode": { "type": [ "string", "null" ], "enum": [ "transport_exhausted", "admin_bounce", "crash_orphaned_claim", null ], "description": "Why a send reached status \"failed\". Present only for terminal delivery failures. \"transport_exhausted\" means every available delivery route was refused by the recipient provider; \"admin_bounce\" means an operator removed the message from the delivery queue; \"crash_orphaned_claim\" means the sending worker stopped between claiming the send and recording a transport outcome, so the message was never confirmed as reaching the provider. None of them is a bounce: the address is still valid, stays subscribed, and is not suppressed. New codes can be added over time, so treat an unrecognized value as a generic failure rather than rejecting the response." }, "emailBody": { "type": [ "string", "null" ], "description": "Stored HTML body. Null when the email send row has been cleaned up." }, "isCopiedRecipient": { "type": "boolean", "description": "Whether this is an auxiliary CC/BCC delivery record whose content and engagement belong to a primary email send." }, "primaryEmailSendId": { "type": [ "string", "null" ], "description": "Primary email send ID for a copied-recipient delivery, or null for ordinary sends and when the primary record is unavailable." }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "bouncedAt": { "type": [ "string", "null" ], "format": "date-time" }, "complainedAt": { "type": [ "string", "null" ], "format": "date-time" }, "openedAt": { "type": [ "string", "null" ], "format": "date-time" }, "clickedAt": { "type": [ "string", "null" ], "format": "date-time" }, "unsubscribedAt": { "type": [ "string", "null" ], "format": "date-time" }, "suppressedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "subscriber": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "campaign": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, { "type": "null" } ] }, "automation": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, { "type": "null" } ] } } }, "EmailBodyInput": { "type": "object", "properties": { "html": { "type": "string", "description": "Raw HTML body. Provide either html or blocks, not both.", "example": "

Hello

" }, "blocks": { "type": "array", "description": "Structured email blocks. Provide either blocks or html, not both. Put visual styling under styles; top-level style keys such as backgroundColor, backgroundOpacity, borderColor, borderWidth, and borderRadius are normalized into styles.", "items": { "$ref": "#/components/schemas/EmailBlock" } } } }, "BlockFieldWarnings": { "type": "array", "description": "Non-blocking advisories about a successful write. Present when an input was discarded or did not take effect as requested. This includes block fields that do not render as their names suggest, sequence email-step formatting restored on top of submitted blocks, and sender-identity conflicts such as a replyToName that differs from the saved profile. Each message identifies the affected input and gives recovery guidance. Absent when there is nothing to report.", "items": { "type": "string" }, "example": [ "blocks[0].styles.color is not a supported field and was ignored. Button label color comes from the block-level `buttonTextColor` field. Supported styles fields: backgroundColor, backgroundOpacity, bleed, borderColor, borderRadius, borderWidth, paddingBottom, paddingLeft, paddingRight, paddingTop, textAlign, textColor." ] }, "SequenceStatus": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "description": "Stored lifecycle status. Do not read literally: a sequence can be active while enrollmentPaused blocks new subscribers. Branch on effectiveStatus instead." }, "SequenceEffectiveStatus": { "type": "string", "enum": [ "draft", "live", "enrollment_paused", "paused", "archived" ], "description": "Resolved run state, and the single field to branch on. live accepts new subscribers and advances existing recipients; enrollment_paused advances existing recipients only; draft, paused, and archived do neither." }, "SequenceTriggerType": { "type": "string", "description": "How contacts enter the sequence. `manual` never enrolls anyone automatically; use it with key dates for one-time countdown campaigns and enroll the audience with the enroll-audience endpoint.", "enum": [ "contact_added", "tag_added", "segment_entered", "event_received", "inbound_webhook", "inactivity", "frequency", "manual" ] }, "SequenceDelayOffsetInput": { "type": "object", "description": "Relative offset for a delay.", "properties": { "days": { "type": "number", "minimum": 0, "example": 1 }, "hours": { "type": "number", "minimum": 0, "example": 2 }, "minutes": { "type": "number", "minimum": 0, "example": 30 } } }, "SequenceDelayInput": { "type": "object", "description": "Delay before this step runs. Use duration fields for fixed waits, mode until_date with untilDateField for a date from the trigger event or a contact attribute (untilDateSource), mode until_weekday with the weekday window fields, or mode until_key_date with untilKeyDate (prefer the waitUntilKeyDate shorthand).", "properties": { "mode": { "type": "string", "enum": [ "duration", "until_date", "until_weekday", "until_key_date" ], "description": "Delay mode. Defaults to duration.", "example": "until_date" }, "untilKeyDate": { "type": "string", "description": "Key of a sequence key date to wait relative to when mode is until_key_date.", "example": "black_friday_starts" }, "keyDate": { "type": "string", "description": "Alias for untilKeyDate.", "example": "black_friday_starts" }, "untilPastAction": { "type": "string", "enum": [ "continue", "skip", "exit" ], "description": "For until_key_date and until_date, what a late enrollee does when the moment already passed. continue moves on immediately, skip skips the following email and action steps until the next wait, condition or branch, exit ends the enrollment. Defaults to skip for until_key_date and continue for until_date.", "example": "skip" }, "pastAction": { "type": "string", "enum": [ "continue", "skip", "exit" ], "description": "Alias for untilPastAction.", "example": "skip" }, "days": { "type": "number", "minimum": 0, "example": 1 }, "hours": { "type": "number", "minimum": 0, "example": 2 }, "minutes": { "type": "number", "minimum": 0, "example": 30 }, "untilDateField": { "type": "string", "description": "Date field path to wait until when mode is until_date, read from the source chosen by untilDateSource.", "example": "renews_at" }, "field": { "type": "string", "description": "Alias for untilDateField.", "example": "subscription.renews_at" }, "untilDateSource": { "type": "string", "enum": [ "event", "attribute" ], "description": "Where untilDateField is read from when mode is until_date. event reads the trigger event properties; attribute reads the contact's custom attributes when the step is reached. Defaults to event.", "example": "attribute" }, "source": { "type": "string", "enum": [ "event", "attribute" ], "description": "Alias for untilDateSource.", "example": "attribute" }, "untilOffsetDirection": { "type": "string", "enum": [ "before", "after" ], "description": "Whether the offset runs before or after the date field. Defaults to after.", "example": "before" }, "direction": { "type": "string", "enum": [ "before", "after" ], "description": "Alias for untilOffsetDirection.", "example": "before" }, "untilMissingAction": { "type": "string", "enum": [ "continue", "exit" ], "description": "What to do when the date field is missing or invalid. Defaults to continue.", "example": "exit" }, "missingAction": { "type": "string", "enum": [ "continue", "exit" ], "description": "Alias for untilMissingAction.", "example": "exit" }, "untilDays": { "type": "array", "items": { "type": "string" }, "description": "Weekdays the wait may release on when mode is until_weekday.", "example": [ "sunday" ] }, "untilStartTime": { "type": "string", "description": "Window start in 24-hour HH:mm local time when mode is until_weekday.", "example": "09:00" }, "untilEndTime": { "type": "string", "description": "Window end in 24-hour HH:mm local time when mode is until_weekday. Defaults to the end-of-day boundary 24:00.", "example": "12:00" }, "untilTimezone": { "type": "string", "description": "IANA timezone used to evaluate the window when mode is until_weekday.", "example": "America/Los_Angeles" } } }, "SequenceWaitUntilInput": { "type": "object", "description": "Wait until a date from the trigger event or a contact attribute, optionally offset before or after that date. The value must be an ISO 8601 date or a Unix timestamp in seconds or milliseconds.", "properties": { "field": { "type": "string", "description": "Date field path to wait until, read from the source.", "example": "renews_at" }, "untilDateField": { "type": "string", "description": "Alias for field.", "example": "subscription.renews_at" }, "source": { "type": "string", "enum": [ "event", "attribute" ], "description": "Where field is read from. event reads the trigger event properties and needs an event trigger. attribute reads the contact's custom attributes when the step is reached, so it works with any trigger. If the date moves later while a contact is waiting, the contact waits for the new date; moving it earlier does not release them sooner, and a date removed while waiting follows missingAction. Defaults to event.", "example": "attribute" }, "untilDateSource": { "type": "string", "enum": [ "event", "attribute" ], "description": "Alias for source.", "example": "attribute" }, "offset": { "$ref": "#/components/schemas/SequenceDelayOffsetInput" }, "days": { "type": "number", "minimum": 0, "description": "Shorthand offset days when offset is omitted.", "example": 1 }, "hours": { "type": "number", "minimum": 0, "description": "Shorthand offset hours when offset is omitted.", "example": 2 }, "minutes": { "type": "number", "minimum": 0, "description": "Shorthand offset minutes when offset is omitted.", "example": 30 }, "direction": { "type": "string", "enum": [ "before", "after" ], "description": "Whether the offset runs before or after the field date. Defaults to after.", "example": "before" }, "untilOffsetDirection": { "type": "string", "enum": [ "before", "after" ], "description": "Alias for direction.", "example": "before" }, "missingAction": { "type": "string", "enum": [ "continue", "exit" ], "description": "What to do when the date field is missing or invalid. Defaults to continue.", "example": "exit" }, "untilMissingAction": { "type": "string", "enum": [ "continue", "exit" ], "description": "Alias for missingAction.", "example": "exit" }, "pastAction": { "type": "string", "enum": [ "continue", "skip", "exit" ], "description": "What to do when the date, after the offset, already passed when the contact reaches this wait. continue moves on immediately, skip skips the following email and action steps until the next wait, condition or branch so late joiners only get what is still ahead, exit ends the enrollment. Defaults to continue.", "example": "skip" }, "untilPastAction": { "type": "string", "enum": [ "continue", "skip", "exit" ], "description": "Alias for pastAction.", "example": "skip" } } }, "SequenceKeyDate": { "type": "object", "required": [ "label", "at" ], "properties": { "key": { "type": "string", "description": "Stable identifier referenced by waitUntilKeyDate.key (lowercase letters, digits, underscores). Defaults to a slug of the label.", "example": "black_friday_starts" }, "label": { "type": "string", "description": "Human label shown in the builder.", "example": "Black Friday starts" }, "at": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time. A value without a zone designator (\"2026-11-27T00:00\") is read as wall-clock time in the key dates timezone. Stored and returned normalized to UTC.", "example": "2026-11-27T05:00:00.000Z" } } }, "SequenceKeyDates": { "type": "object", "description": "Named absolute moments the sequence counts down to. Delay steps with waitUntilKeyDate wait relative to one of them, so the whole countdown is re-timed by editing these dates. Changing a key date on a live sequence re-schedules contacts already waiting on it. Send null to clear.", "required": [ "dates" ], "properties": { "timezone": { "type": "string", "description": "IANA timezone the dates are shown and edited in. Required when dates is non-empty.", "example": "America/New_York" }, "dates": { "type": "array", "maxItems": 20, "description": "Sorted by time when returned.", "items": { "$ref": "#/components/schemas/SequenceKeyDate" } } } }, "SequenceWaitUntilKeyDateInput": { "type": "object", "description": "Wait relative to one of the sequence's key dates before this step, e.g. 7 days before black_friday_starts or 1 hour before black_friday_ends. The key must exist in the sequence's keyDates.", "properties": { "key": { "type": "string", "description": "Key date identifier from keyDates.", "example": "black_friday_starts" }, "untilKeyDate": { "type": "string", "description": "Alias for key.", "example": "black_friday_starts" }, "offset": { "$ref": "#/components/schemas/SequenceDelayOffsetInput" }, "days": { "type": "number", "minimum": 0, "description": "Offset days shorthand. Ignored when offset is provided.", "example": 7 }, "hours": { "type": "number", "minimum": 0, "description": "Offset hours shorthand.", "example": 0 }, "minutes": { "type": "number", "minimum": 0, "description": "Offset minutes shorthand.", "example": 0 }, "direction": { "type": "string", "enum": [ "before", "after" ], "description": "Whether the offset applies before or after the key date. Defaults to before.", "example": "before" }, "untilOffsetDirection": { "type": "string", "enum": [ "before", "after" ], "description": "Alias for direction.", "example": "before" }, "pastAction": { "type": "string", "enum": [ "continue", "skip", "exit" ], "description": "What a late enrollee does when the moment already passed. skip (default) skips the following steps until the next wait, continue sends immediately, exit ends the enrollment.", "example": "skip" }, "untilPastAction": { "type": "string", "enum": [ "continue", "skip", "exit" ], "description": "Alias for pastAction.", "example": "skip" }, "missingAction": { "type": "string", "enum": [ "continue", "exit" ], "description": "What to do when the key date no longer exists. Defaults to exit.", "example": "exit" }, "untilMissingAction": { "type": "string", "enum": [ "continue", "exit" ], "description": "Alias for missingAction.", "example": "exit" } } }, "SequenceAudience": { "type": "object", "description": "Who to enroll. Same shape as campaign targetLists.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "all", "lists", "segment", "filtered", "rules" ], "example": "lists" }, "listIds": { "type": "array", "items": { "type": "string" }, "description": "For type lists.", "example": [ "list_abc123" ] }, "segmentId": { "type": "string", "description": "For type segment.", "example": "seg_abc123" }, "filters": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "For type filtered; subscriber filters." }, "filterJoinOperator": { "type": "string", "enum": [ "and", "or" ] }, "include": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "For type rules; include rules of type all, lists, segments, or filtered." }, "exclude": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "For type rules; exclude rules." }, "excludedSubscriberIds": { "type": "array", "items": { "type": "string" } } } }, "SequenceAudienceEnrollment": { "type": "object", "description": "One background audience enrollment run.", "properties": { "id": { "type": "string", "example": "aer_abc123" }, "sequenceId": { "type": "string", "example": "seq_abc123" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "cancelled", "failed" ], "example": "running" }, "audience": { "$ref": "#/components/schemas/SequenceAudience" }, "data": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Run-level data passed when the run was started, read by the run's emails as `{{enrollment.}}`. Null when none was given.", "example": { "sale_ends_at": "2026-11-29T23:59:00Z", "discount_percent": 20 } }, "targetNodeId": { "type": [ "string", "null" ], "description": "Step contacts start at.", "example": "node_delay_1" }, "estimatedCount": { "type": "integer", "description": "Audience size estimated when the run started.", "example": 12000 }, "processedCount": { "type": "integer", "description": "Subscribers scanned so far.", "example": 4000 }, "enrolledCount": { "type": "integer", "example": 3800 }, "skippedCount": { "type": "integer", "description": "Matching contacts skipped because they were already in the sequence (or, for one_time sequences, finished it before).", "example": 200 }, "source": { "type": "string", "example": "api" }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "scheduledFor": { "type": [ "string", "null" ], "format": "date-time", "description": "Delayed start. While set and in the future the run stays queued; cancel it before then to prevent the enrollment." }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelRequestedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "SequenceAudienceAutoEnroll": { "type": "object", "description": "Manual countdowns only. Keeps enrolling people who join the audience later (new list members, new segment matches) until the last key date passes; they land on the step the countdown is at. Switching on enrolls the current audience right away and re-checks every few minutes. Ends itself after the last key date. Send null to clear.", "required": [ "audience" ], "properties": { "enabled": { "type": "boolean", "description": "Defaults to true. False keeps the audience but stops syncing.", "example": true }, "audience": { "$ref": "#/components/schemas/SequenceAudience" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "No sync runs before this moment. Pass the scheduledFor of a scheduled initial enrollment so late joiners are not enrolled ahead of everyone else." }, "lastSyncedAt": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "description": "Start time of the last successfully completed sync. Failed or cancelled runs do not advance it. Incremental scans include new or updated contacts and new list memberships." }, "enabledAt": { "type": "string", "format": "date-time", "readOnly": true }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true }, "endedReason": { "type": [ "string", "null" ], "enum": [ "countdown_ended", "disabled", null ], "readOnly": true } } }, "SequenceWaitUntilWeekdayInput": { "type": "object", "description": "Hold until the next occurrence of a weekday inside a local-time window. Contacts already inside the window continue immediately.", "properties": { "day": { "type": "string", "description": "Single weekday convenience alias for days.", "example": "sunday" }, "days": { "type": "array", "items": { "type": "string" }, "description": "Weekdays the wait may release on.", "example": [ "sunday" ] }, "startTime": { "type": "string", "description": "Window start in 24-hour HH:mm local time.", "example": "09:00" }, "untilStartTime": { "type": "string", "description": "Alias for startTime.", "example": "09:00" }, "endTime": { "type": "string", "description": "Window end in 24-hour HH:mm local time. Defaults to the end-of-day boundary 24:00.", "example": "12:00" }, "untilEndTime": { "type": "string", "description": "Alias for endTime.", "example": "12:00" }, "timezone": { "type": "string", "description": "IANA timezone used to evaluate the window.", "example": "America/Los_Angeles" }, "untilTimezone": { "type": "string", "description": "Alias for timezone.", "example": "America/Los_Angeles" } } }, "SequenceDiscountInput": { "type": "object", "description": "Discount configuration for dynamic create_discount steps.", "properties": { "label": { "type": "string", "description": "Builder label for discount steps.", "example": "Create win-back discount" }, "provider": { "type": "string", "enum": [ "stripe", "shopify" ], "description": "Discount provider. Use stripe to dynamically create a Stripe coupon plus promotion code, or shopify to dynamically create a Shopify Admin discount code.", "example": "stripe" }, "discountType": { "type": "string", "enum": [ "percent", "amount" ], "description": "Discount type for create_discount steps.", "example": "percent" }, "percentOff": { "type": "number", "minimum": 1, "maximum": 100, "description": "Percent discount. Required when discountType is percent.", "example": 20 }, "amountOff": { "type": "number", "minimum": 1, "description": "Fixed discount amount in the smallest currency unit, for example 500 for $5. Required when discountType is amount.", "example": 500 }, "currency": { "type": "string", "description": "ISO currency for fixed-amount discounts. Defaults to usd.", "example": "usd" }, "duration": { "type": "string", "enum": [ "once", "forever", "repeating" ], "description": "Discount duration. Defaults to once.", "example": "once" }, "durationInMonths": { "type": "number", "minimum": 1, "description": "Required for repeating discounts.", "example": 3 }, "appliesToAllPlans": { "type": "boolean", "description": "Whether the discount applies to all plans. Defaults to true.", "example": true }, "planIds": { "type": "array", "description": "Provider product IDs when appliesToAllPlans is false. Stripe uses IDs like prod_abc123; Shopify accepts numeric product IDs or gid://shopify/Product/... IDs.", "items": { "type": "string" }, "example": [ "prod_abc123" ] }, "codePrefix": { "type": "string", "description": "Optional prefix for generated dynamic codes. The final code also includes a subscriber/token suffix.", "example": "SAVE" }, "maxRedemptions": { "type": "number", "minimum": 1, "description": "Maximum redemptions for each generated code. Use 1 for subscriber-specific codes.", "example": 1 }, "lockToSubscriber": { "type": "boolean", "description": "Stripe-only. Restrict each generated promotion code to the matched subscriber's Stripe customer.", "example": true }, "expiresAt": { "type": "string", "description": "Optional future expiration date or ISO timestamp. Mutually exclusive with expiresInHours.", "example": "2026-12-31" }, "expiresInHours": { "type": "number", "minimum": 1, "description": "Optional relative expiration in hours, resolved when each subscriber's code is created. Takes precedence over expiresAt.", "example": 48 }, "name": { "type": "string", "description": "Optional display name for each dynamically generated provider discount.", "example": "Win-back coupon" } } }, "SequenceStepInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email", "sms", "create_discount", "discount", "update_subscriber" ], "description": "Step type. Omit or use email for email content; use sms for a native SMS step; use create_discount for a dynamic discount; use update_subscriber for an Update Subscriber action.", "example": "create_discount" }, "nodeType": { "type": "string", "enum": [ "action_email", "action_sms", "action_create_discount", "action_update_attributes" ], "description": "Internal node-type alias for clients that work with automation nodes. Use action_update_attributes with config for Update Subscriber steps." }, "config": { "$ref": "#/components/schemas/SubscriberUpdateConfig" }, "subject": { "type": "string", "description": "Email subject line for email steps.", "example": "Welcome to Acme" }, "previewText": { "type": "string", "description": "Optional email preview text.", "example": "Here is what to do next" }, "text": { "type": "string", "description": "SMS steps only. Plain-text message body; merge tags like {{FIRST_NAME}} work. Do not include opt-out text or a brand prefix - Sequenzy adds both automatically at send time.", "example": "Hey {{FIRST_NAME}}, your order shipped!" }, "imageUrls": { "type": "array", "description": "SMS steps only. Up to 2 publicly reachable image URLs sent as MMS media.", "items": { "type": "string" } }, "ineligibleAction": { "type": "string", "enum": [ "skip", "exit" ], "description": "SMS steps only. skip (default) continues the sequence when the contact can't receive SMS; exit removes them from the sequence." }, "blocks": { "type": "array", "description": "Structured Sequenzy email blocks. Provide either blocks or html. Put visual styling under styles; top-level style keys such as backgroundColor, backgroundOpacity, borderColor, borderWidth, and borderRadius are normalized into styles.", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "html": { "type": "string", "description": "Raw HTML preserved as one HTML block. Provide either html or blocks.", "example": "

Welcome

Thanks for joining.

" }, "isTransactional": { "type": "boolean", "description": "Send this email without the marketing unsubscribe footer." }, "senderProfileId": { "type": "string", "description": "Existing sender profile override for this email step." }, "fromEmail": { "type": "string", "format": "email", "description": "From address used to create a sender profile for this email step. Mutually exclusive with senderProfileId." }, "fromName": { "type": "string", "description": "Display name override for this email step. Alone it only changes the visible name; with fromEmail it also names a newly created sender profile." }, "replyProfileId": { "type": "string", "description": "Existing reply profile override for this email step." }, "replyTo": { "type": "string", "format": "email", "description": "Reply-To address used to create a reply profile for this email step. Mutually exclusive with replyProfileId." }, "replyToName": { "type": "string", "description": "Display name for the step reply profile. Requires replyTo; omit it when using replyProfileId, which already carries its own display name." }, "ccEmails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Addresses CC'd on this email step. Send an empty array to clear them." }, "bccEmails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Addresses BCC'd on this email step in addition to sequence-level BCC. Send an empty array to clear them." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/UrlAttachment" }, "description": "URL-backed file attachments for this email step, fetched at send time. Event-triggered sequences may use {{event.*}} URL templates. Send an empty array to clear them." }, "delay": { "$ref": "#/components/schemas/SequenceDelayInput" }, "waitUntil": { "$ref": "#/components/schemas/SequenceWaitUntilInput" }, "waitUntilWeekday": { "$ref": "#/components/schemas/SequenceWaitUntilWeekdayInput" }, "waitUntilKeyDate": { "$ref": "#/components/schemas/SequenceWaitUntilKeyDateInput" }, "delayMs": { "type": "number", "description": "Delay before this step in milliseconds. Prefer delay for human-authored requests; use delayMs when importing provider waits.", "example": 86400000 }, "name": { "type": "string", "description": "Optional email template name for email steps.", "example": "Welcome Sequence - Email 1" }, "discount": { "allOf": [ { "$ref": "#/components/schemas/SequenceDiscountInput" } ], "description": "Discount configuration for create_discount steps. Prefer this nested shape for new integrations; legacy top-level discount fields are still accepted." }, "label": { "type": "string", "description": "Legacy top-level builder label for discount steps. Prefer discount.label.", "example": "Create win-back discount" }, "provider": { "type": "string", "enum": [ "stripe", "shopify" ], "description": "Legacy top-level discount provider. Prefer discount.provider. Supports stripe and shopify.", "example": "stripe" }, "discountType": { "type": "string", "enum": [ "percent", "amount" ], "description": "Legacy top-level discount type. Prefer discount.discountType.", "example": "percent" }, "percentOff": { "type": "number", "minimum": 1, "maximum": 100, "description": "Percent discount. Required when discountType is percent.", "example": 20 }, "amountOff": { "type": "number", "minimum": 1, "description": "Fixed discount amount in the smallest currency unit, for example 500 for $5. Required when discountType is amount.", "example": 500 }, "currency": { "type": "string", "description": "ISO currency for fixed-amount discounts. Defaults to usd.", "example": "usd" }, "duration": { "type": "string", "enum": [ "once", "forever", "repeating" ], "description": "Discount duration. Defaults to once.", "example": "once" }, "durationInMonths": { "type": "number", "minimum": 1, "description": "Required for repeating discounts.", "example": 3 }, "appliesToAllPlans": { "type": "boolean", "description": "Whether the discount applies to all plans. Defaults to true.", "example": true }, "planIds": { "type": "array", "description": "Provider product IDs when appliesToAllPlans is false. Stripe uses IDs like prod_abc123; Shopify accepts numeric product IDs or gid://shopify/Product/... IDs.", "items": { "type": "string" }, "example": [ "prod_abc123" ] }, "codePrefix": { "type": "string", "description": "Optional prefix for generated dynamic codes. The final code also includes a subscriber/token suffix.", "example": "SAVE" }, "maxRedemptions": { "type": "number", "minimum": 1, "description": "Maximum redemptions for each generated code. Use 1 for subscriber-specific codes.", "example": 1 }, "lockToSubscriber": { "type": "boolean", "description": "Legacy top-level Stripe-only flag. Prefer discount.lockToSubscriber.", "example": true }, "expiresAt": { "type": "string", "description": "Optional future expiration date or ISO timestamp. Mutually exclusive with expiresInHours.", "example": "2026-12-31" }, "expiresInHours": { "type": "number", "minimum": 1, "description": "Optional relative expiration in hours, resolved when each subscriber's code is created. Takes precedence over expiresAt.", "example": 48 } } }, "SequenceStopCondition": { "type": "object", "description": "Auto-stop condition, re-evaluated before every step including the first one. has_tag, added_to_list, entered_segment, field_changed, and event_received stop the run once the thing happens. event_received only counts events received after enrollment - the enrolling event and earlier history never satisfy the stop. does_not_have_tag and removed_from_list stop the run whenever the subscriber lacks that tag or list membership, so they act as a required-tag or required-list allowlist and cancel everyone else before any step sends. Guarded-out contacts still enroll and are then cancelled at the trigger node, so they appear as cancellations there rather than in the active or waiting enrollment counts. Clearing the guard does not retry them: they only receive the sequence if the trigger fires for them again, and on the one_time enrollment mode not even then.", "properties": { "type": { "type": "string", "enum": [ "none", "has_tag", "does_not_have_tag", "added_to_list", "removed_from_list", "entered_segment", "field_changed", "event_received" ] }, "value": { "type": [ "string", "null" ], "description": "Tag name, list ID, segment ID, field path, or event name. For the does_not_have_tag and removed_from_list guards this is the tag or list a subscriber must have to keep receiving the sequence. Null with entry_audience matching means the tag or list that enrolled each contact is used.", "example": "saas.purchase" }, "matchConfig": { "description": "Optional typed match rule. event_received uses event_property_filter propertyFilters (stop only when an event received after enrollment matches every filter, e.g. quota_used greater_than 1) or event_property rules (stop only when the stop event's field equals the same field captured on the enrolling event); field_changed uses a field_value comparison. Tag/list defaults use entry_audience to resolve the required tag or list per enrollment. Tag entry matching requires a tag_added trigger; list entry matching requires a contact_added trigger scoped to at least one specific list.", "anyOf": [ { "oneOf": [ { "type": "object", "required": [ "mode", "propertyFilters" ], "properties": { "mode": { "type": "string", "enum": [ "event_property_filter" ] }, "propertyFilters": { "type": "array", "description": "Filters an event received after enrollment must all match for the stop to fire. Same shape as event trigger propertyFilters.", "items": { "type": "object", "required": [ "path", "operator" ], "properties": { "path": { "type": "string", "description": "Dot-path into the stop event's properties.", "example": "quota_used" }, "operator": { "type": "string", "enum": [ "exists", "not_exists", "equals", "not_equals", "one_of", "contains", "greater_than", "less_than" ] }, "value": { "description": "Comparison value (string, number, or boolean; array of values for one_of). Omit for exists/not_exists." } } } } } }, { "type": "object", "required": [ "mode", "rules" ], "properties": { "mode": { "type": "string", "enum": [ "event_property" ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "entryFieldPath", "eventFieldPath" ], "properties": { "entryFieldPath": { "type": "string" }, "eventFieldPath": { "type": "string" } } } } } }, { "type": "object", "required": [ "mode", "operator", "value" ], "properties": { "mode": { "type": "string", "enum": [ "field_value" ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "contains", "not_contains" ] }, "value": { "type": "string" } } }, { "type": "object", "required": [ "mode", "audience" ], "properties": { "mode": { "type": "string", "enum": [ "entry_audience" ] }, "audience": { "type": "string", "enum": [ "tag", "list" ], "description": "Use the tag or list recorded when this contact enrolled." } } } ] }, { "type": "null" } ] } } }, "SequenceEnrollmentMode": { "type": "string", "enum": [ "unlimited", "one_time", "matching_field" ], "description": "Controls sequence re-entry. `unlimited` allows re-entry after completion but prevents concurrent active runs. `one_time` allows one enrollment ever. `matching_field` is only valid for event-triggered sequences and allows concurrent active runs only when the trigger payload resolves to a different event field value.\n" }, "SequenceSendingWindow": { "type": "object", "description": "Optional local-time sending window applied to every email step in a sequence. Email steps that become due outside the window wait until the next allowed local time.", "properties": { "enabled": { "type": "boolean", "example": true }, "timezone": { "type": "string", "description": "IANA timezone for the window.", "example": "Europe/Kiev" }, "startTime": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Earliest local send time in 24-hour HH:mm format.", "example": "08:00" }, "endTime": { "type": "string", "pattern": "^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$", "description": "Latest local send cutoff in 24-hour HH:mm format, or 24:00 for the end-of-day boundary. Must be later than startTime.", "example": "20:00" }, "days": { "type": "array", "description": "Allowed local days. Omit days when creating or updating to allow every day.", "items": { "type": "string", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ] }, "example": [ "monday", "tuesday", "wednesday", "thursday", "friday" ] } } }, "SequenceTriggerPropertyFilter": { "type": "object", "required": [ "path", "operator" ], "properties": { "path": { "type": "string", "description": "Dot-path into the event properties. Use [] to match items inside arrays.", "example": "lineItems[].providerProductId" }, "operator": { "type": "string", "enum": [ "exists", "not_exists", "equals", "not_equals", "one_of", "contains", "greater_than", "less_than" ], "description": "Comparison operator. Value is required for every operator except exists and not_exists. `one_of` matches when the property equals any entry of the value array.", "example": "equals" }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "maxItems": 50, "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ], "description": "Value to compare against. For `one_of`, pass a non-empty array of strings or numbers (maximum 50 values); all other operators take a single value.", "example": "prod_ABC123" } } }, "SequenceCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "description": { "type": "string", "description": "Optional dashboard description." }, "userCancellable": { "type": "boolean", "description": "Whether recipients can cancel this sequence from email preferences." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Dashboard label names. Missing labels are created." }, "bccEmails": { "type": [ "array", "null" ], "maxItems": 10, "items": { "type": "string", "format": "email" }, "description": "Addresses blind-copied on every sequence email." }, "fromEmail": { "type": "string", "format": "email", "description": "From address for every email in this sequence. Its domain must be configured and verified." }, "fromName": { "type": "string", "description": "Display name recipients see, e.g. 'Brennon at TradeTally'. Selects the sender identity of that name on fromEmail, creating it when the address has no identity by that name; the mailbox's other display names, and everything pinned to them, are untouched. Requires fromEmail; omit it when using senderProfileId, which already carries its own display name." }, "senderProfileId": { "type": "string", "description": "Existing sender profile ID. It already supplies both the From address and display name, so send it on its own and omit fromEmail and fromName. To keep this profile under a different display name, set fromName on the email steps instead, where it is a per-step override." }, "replyTo": { "type": "string", "format": "email", "description": "Reply-To address for every email in this sequence. A profile is created when needed." }, "replyToName": { "type": "string", "description": "Display name for the Reply-To address. Requires replyTo; omit it when using replyProfileId, which already carries its own display name. An address carries one Reply-To name company-wide, so if replyTo already has a saved profile under a different name, that saved name is kept and the response `warnings` array says so." }, "replyProfileId": { "type": "string", "description": "Existing reply profile ID. It already supplies both the Reply-To address and display name, so send it on its own and omit replyTo and replyToName." }, "name": { "type": "string", "example": "Welcome Sequence" }, "trigger": { "$ref": "#/components/schemas/SequenceTriggerType", "description": "Defaults to contact_added when omitted." }, "listId": { "type": "string", "description": "List ID for contact_added triggers. Omit it to use listScope instead. Use listIds to trigger on several lists.", "example": "list_abc123" }, "listIds": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string" }, "description": "Several list IDs for a contact_added trigger. A contact joining ANY of them enrolls. Takes precedence over listId when both are sent. Cannot be combined with listScope.", "example": [ "list_abc123", "list_def456" ] }, "listScope": { "type": "string", "enum": [ "any_contact", "any_list" ], "default": "any_contact", "description": "For contact_added triggers with no list at all. `any_contact` (the default) enrolls every contact added, including contacts that join no list - which is what integrations create when list targeting is empty. `any_list` waits until the contact joins a list. Cannot be combined with listId or listIds.", "example": "any_list" }, "tagName": { "type": "string", "description": "Tag name for tag_added triggers. Use tagNames to trigger on several tags.", "example": "trial" }, "tagNames": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string" }, "description": "Several tag names for a tag_added trigger. Receiving ANY of them enrolls the contact. Takes precedence over tagName when both are sent.", "example": [ "trial", "vip" ] }, "segmentId": { "type": "string", "description": "Segment ID for segment_entered triggers.", "example": "seg_abc123" }, "stopOnSegmentExit": { "type": "boolean", "description": "For segment_entered triggers, cancel enrollment when the subscriber leaves the segment." }, "eventName": { "type": "string", "description": "Event name for event_received, inbound_webhook, inactivity, and frequency triggers.", "example": "onboarding.started" }, "integrationSlug": { "type": "string", "description": "Integration slug for inbound_webhook triggers." }, "integrationEventKey": { "type": "string", "description": "Integration event key for inbound_webhook triggers." }, "customIntegration": { "type": "object", "additionalProperties": true, "description": "Custom inbound-webhook integration metadata." }, "propertyFilters": { "type": "array", "maxItems": 10, "description": "Event property filters for event_received and inbound_webhook triggers. The sequence only starts when the triggering event's properties match all filters. Use [] in the path to match items inside arrays.", "items": { "$ref": "#/components/schemas/SequenceTriggerPropertyFilter" } }, "inactiveDays": { "type": "number", "minimum": 1, "description": "Days of inactivity before the sequence starts.", "example": 14 }, "inactivityBaseline": { "type": "string", "enum": [ "sequence_created_at", "subscriber_created_at" ], "description": "For inactivity triggers, controls when to start counting for subscribers who have never performed the event. Defaults to sequence_created_at.", "example": "sequence_created_at" }, "minCount": { "type": "number", "minimum": 1, "description": "Minimum event count for frequency triggers.", "example": 3 }, "timeWindowDays": { "type": "number", "minimum": 1, "description": "Time window in days for frequency triggers.", "example": 7 }, "enrollmentMode": { "$ref": "#/components/schemas/SequenceEnrollmentMode" }, "enrollmentFieldPath": { "type": "string", "description": "Scalar dot-path event property used by matching_field enrollment, such as order.id or product.providerVariantId. Array traversal with [] is not supported; use propertyFilters for array matching. Applies to event_received and inbound_webhook triggers. Leave empty for built-in Shopify product/variant defaults.", "example": "order.id" }, "sendingWindow": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceSendingWindow" } ] }, { "type": "null" } ] }, "keyDates": { "description": "Named absolute moments for waitUntilKeyDate steps. Null clears them.", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceKeyDates" } ] }, { "type": "null" } ] }, "emailCount": { "type": "number", "minimum": 1, "maximum": 10, "description": "Number of emails for AI-generated content. Defaults to 5. Maximum is 10.", "example": 5 }, "durationDays": { "type": "number", "minimum": 1, "description": "Total duration in days used to space AI-generated emails. Omit this to use the default sequence delay schedule.", "example": 14 }, "emailStyle": { "type": "string", "enum": [ "visual", "plain" ], "description": "Style for the AI-generated emails: visual (designed, with heroes/imagery/rich sections) or plain (personal, text-first notes with a single button). Defaults to the company's saved preference when omitted.", "example": "visual" }, "goal": { "type": "string", "description": "Goal for AI-generated sequence content. Provide either goal or steps, or omit both for a blank dashboard-compatible draft.", "example": "Welcome new users and help them reach activation." }, "stopCondition": { "$ref": "#/components/schemas/SequenceStopCondition" }, "steps": { "type": "array", "description": "Explicit email and action steps. Provide either steps or goal, or omit both for a blank dashboard-compatible draft.", "items": { "$ref": "#/components/schemas/SequenceStepInput" } } } }, "SequenceEmailUpdateInput": { "type": "object", "properties": { "emailId": { "type": "string", "description": "Email template ID to update. You can also pass the node ID here for compatibility.", "example": "email_abc123" }, "nodeId": { "type": "string", "description": "Sequence email node ID to update.", "example": "node_abc123" }, "name": { "type": "string", "description": "Updated step and email template name.", "example": "Welcome Sequence - Email 1" }, "subject": { "type": "string", "description": "Updated subject line.", "example": "Welcome to Acme" }, "previewText": { "type": [ "string", "null" ], "description": "Updated preview text.", "example": "Start here" }, "isTransactional": { "type": "boolean", "description": "Use transactional email chrome for this sequence email." }, "ccEmails": { "type": "array", "items": { "type": "string", "format": "email" } }, "bccEmails": { "type": "array", "items": { "type": "string", "format": "email" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/UrlAttachment" }, "description": "URL-backed file attachments for this email step, fetched at send time. Event-triggered sequences may use {{event.*}} URL templates. Send an empty array to clear them." }, "emailPreset": { "type": "string", "enum": [ "branded", "minimal" ], "description": "Per-email Style > Format for native Sequenzy blocks, including emails that contain supported custom HTML blocks. Minimal removes the company logo and uses the simple footer; branded restores the branded chrome. This is not supported when the entire email is standalone raw HTML and must not be combined with html or htmlContent.", "example": "minimal" }, "emailTheme": { "allOf": [ { "$ref": "#/components/schemas/EmailThemePatch" } ], "description": "Theme override for this step's linked email only. Partial patch merged into the email's current theme; a step with no override merges into the company theme. Null drops the override." }, "blocks": { "type": "array", "description": "Replacement Sequenzy email blocks. Put visual styling under styles; top-level style keys such as backgroundColor, backgroundOpacity, borderColor, borderWidth, and borderRadius are normalized into styles. Replacing blocks keeps that step's existing Style > Format rather than the company default: a step that already had a logo or a footer gets them back even when you omit them, and every block added that way is named in the response warnings array. Send emailPreset to change the format instead. A step stored as one standalone raw HTML block has no format, so replacing it with another standalone raw HTML block stores it exactly as sent and nothing is added; replacing that markup with native blocks is a conversion rather than a markup edit, so the new blocks do get a footer.", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "html": { "type": "string", "description": "Raw HTML preserved as one HTML block. Provide html/htmlContent or blocks.", "example": "

Updated body

" }, "htmlContent": { "type": "string", "description": "Alias for html. Raw HTML is preserved as one HTML block.", "example": "

Updated body

" }, "senderProfileId": { "type": "string", "description": "Sender profile for this step's From identity. Overrides the sequence-level sender for this step. Mutually exclusive with fromEmail.", "example": "sender_abc123" }, "fromEmail": { "type": "string", "format": "email", "description": "From address for this step. Its domain must be configured and verified. Mutually exclusive with senderProfileId." }, "fromName": { "type": "string", "description": "Display name override for this step. Alone it only changes the visible name; with fromEmail it also names a newly created sender profile.", "example": "Michael from Acme" }, "replyProfileId": { "type": "string", "description": "Reply profile for this step's Reply-To. Mutually exclusive with replyTo.", "example": "reply_abc123" }, "replyTo": { "type": "string", "format": "email", "description": "Reply-To address for this step. Mutually exclusive with replyProfileId." }, "replyToName": { "type": "string", "description": "Reply-To display name override for this step. Requires replyTo; omit it when using replyProfileId, which already carries its own display name." } } }, "SequenceBranchConditionInput": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional stable branch ID. Defaults to branch-0, branch-1, etc.", "example": "branch-0" }, "label": { "type": "string", "example": "Has activated tag" }, "conditionType": { "type": "string", "enum": [ "has_tag", "does_not_have_tag", "in_list", "in_segment", "event_received", "link_clicked", "field_equals", "field_contains", "field_greater_than", "field_less_than", "has_phone", "sms_subscribed" ], "description": "Condition for this path. Required on a condition split; must be omitted when the branch sets splitMode to random, where paths are chosen by percentage.", "example": "has_tag" }, "tagId": { "type": "string", "description": "Tag ID or tag name for has_tag and does_not_have_tag conditions.", "example": "activated" }, "tagName": { "type": "string", "description": "Tag name for has_tag and does_not_have_tag conditions.", "example": "activated" }, "listId": { "type": "string", "description": "List ID for in_list conditions.", "example": "list_abc123" }, "segmentId": { "type": "string", "description": "Segment ID for in_segment conditions.", "example": "seg_abc123" }, "segmentName": { "type": "string", "description": "Optional display name for in_segment conditions.", "example": "Project invite recipients" }, "eventName": { "type": "string", "description": "Event name for event_received conditions.", "example": "project.invite.accepted" }, "linkUrl": { "type": "string", "description": "Optional URL substring for link_clicked conditions. Omit to match any clicked link.", "example": "project-invites" }, "activityScope": { "type": "string", "enum": [ "ever", "this_sequence", "previous_email" ], "description": "Scope for event_received and link_clicked conditions.", "example": "this_sequence" }, "fieldName": { "type": "string", "description": "Subscriber attribute name for field conditions.", "example": "plan" }, "fieldValue": { "type": "string", "description": "Comparison value for field conditions.", "example": "pro" }, "targetNodeId": { "type": "string", "description": "Existing node reached by this branch path after any newly created steps. Use the completion node ID to end this path immediately.", "example": "node_sequence_complete" }, "steps": { "type": "array", "description": "Optional steps to create in this branch path. When targetNodeId is also set, the final new step connects to that existing node.", "items": { "$ref": "#/components/schemas/SequenceBranchPathStepInput" } } } }, "SequenceBranchPathStepInput": { "type": "object", "description": "Step created inside a sequence path.", "properties": { "type": { "type": "string", "enum": [ "email", "sms", "delay", "create_discount", "discount", "update_subscriber", "condition", "webhook", "ai" ], "description": "Step type. Omit for email steps, use sms for a native SMS step, or use delay for a standalone wait.", "example": "email" }, "nodeType": { "type": "string", "enum": [ "logic_delay", "action_email", "action_sms", "action_create_discount", "action_add_tag", "action_remove_tag", "action_add_to_list", "action_remove_from_list", "action_update_attributes", "logic_wait_for_event", "logic_condition", "action_webhook", "action_ai" ], "description": "Advanced node type for non-email sequence path actions." }, "config": { "$ref": "#/components/schemas/SequencePathStepConfig" }, "subject": { "type": "string", "description": "Email subject. Required for email steps.", "example": "Can you refer us?" }, "previewText": { "type": [ "string", "null" ], "description": "Email preview text." }, "text": { "type": "string", "description": "SMS steps only. Plain-text message body; merge tags like {{FIRST_NAME}} work.", "example": "Hey {{FIRST_NAME}}, your order shipped!" }, "imageUrls": { "type": "array", "description": "SMS steps only. Up to 2 publicly reachable image URLs sent as MMS media.", "items": { "type": "string" } }, "ineligibleAction": { "type": "string", "enum": [ "skip", "exit" ], "description": "SMS steps only. skip (default) continues the sequence when the contact can't receive SMS; exit removes them from the sequence." }, "label": { "type": "string", "description": "SMS steps only. Display label for the step in the builder.", "example": "Shipping text" }, "blocks": { "type": "array", "description": "Email blocks for email steps. Put visual styling under styles; top-level style keys such as backgroundColor, backgroundOpacity, borderColor, borderWidth, and borderRadius are normalized into styles.", "items": { "$ref": "#/components/schemas/EmailBlock" } }, "html": { "type": "string", "description": "HTML content for email steps.", "example": "

Can you refer us?

" }, "delay": { "$ref": "#/components/schemas/SequenceDelayInput" }, "waitUntil": { "$ref": "#/components/schemas/SequenceWaitUntilInput" }, "waitUntilWeekday": { "$ref": "#/components/schemas/SequenceWaitUntilWeekdayInput" }, "waitUntilKeyDate": { "$ref": "#/components/schemas/SequenceWaitUntilKeyDateInput" }, "delayMs": { "type": "number", "description": "Delay in milliseconds. Useful for standalone delay steps.", "example": 86400000 }, "name": { "type": "string", "description": "Email template name for email steps." }, "senderProfileId": { "type": "string", "description": "Email steps only. Sender profile for the new step. Omit to inherit the sender identity of the email step it is inserted after. Mutually exclusive with fromEmail." }, "fromEmail": { "type": "string", "format": "email", "description": "Email steps only. From address for the new step; its domain must be verified. Mutually exclusive with senderProfileId." }, "fromName": { "type": "string", "description": "Email steps only. Display name override for the new step. With fromEmail, also names a newly created sender profile." }, "replyProfileId": { "type": "string", "description": "Email steps only. Reply profile for the new step. Omit to inherit from the preceding email step. Mutually exclusive with replyTo." }, "replyTo": { "type": "string", "format": "email", "description": "Email steps only. Reply-To address for the new step. Mutually exclusive with replyProfileId." }, "replyToName": { "type": "string", "description": "Email steps only. Reply-To display name override for this step. Requires replyTo; omit it when using replyProfileId, which already carries its own display name." }, "discount": { "type": "object", "description": "Discount configuration for create_discount steps.", "additionalProperties": true } } }, "SequenceBranchInput": { "type": "object", "required": [ "afterNodeId", "branches" ], "properties": { "afterNodeId": { "type": "string", "description": "Existing sequence node ID to insert the branch after.", "example": "node_trigger" }, "label": { "type": "string", "example": "Branching" }, "splitMode": { "type": "string", "enum": [ "condition", "random" ], "default": "condition", "description": "How subscribers are routed. condition evaluates each branch's conditionType in order. random assigns each subscriber a path by percentage when they reach the node, which runs a concurrent A/B test inside the sequence. A random split requires randomPercentages, omits conditionType and condition-specific fields on every branch, and has no else path." }, "randomPercentages": { "type": "array", "items": { "type": "number" }, "description": "Required when splitMode is random. One non-negative percentage per entry in branches, in the same order, summing to 100.", "example": [ 50, 50 ] }, "branches": { "type": "array", "description": "Branch paths. On a condition split they are evaluated in order and an else fallback is created automatically. On a random split each entry is a weighted variant. Each branch should include steps, targetNodeId, or both unless allowEmptyPaths is true.", "items": { "$ref": "#/components/schemas/SequenceBranchConditionInput" } }, "elseSteps": { "type": "array", "description": "Optional steps to create in the else fallback path. When elseTargetNodeId is also set, the final new step connects to that existing node. Rejected when splitMode is random.", "items": { "$ref": "#/components/schemas/SequenceBranchPathStepInput" } }, "elseTargetNodeId": { "type": "string", "description": "Existing node reached by the else fallback path after any elseSteps. Use the original follow-up node to keep that path in the existing flow, or the completion node to end it. Rejected when splitMode is random.", "example": "node_follow_up" }, "allowEmptyPaths": { "type": "boolean", "description": "Set true only when intentionally creating empty UI placeholders. Explicit target node paths do not require this flag.", "default": false } } }, "SequenceLinearStepInsertionInput": { "type": "object", "required": [ "steps" ], "properties": { "afterNodeId": { "type": "string", "description": "Existing sequence node ID to insert after. Omit only to append to an unambiguous linear tail.", "example": "node_migration_email" }, "steps": { "type": "array", "description": "New linear steps to insert. Supports addable step types that do not require companion records; multi-path branches use the branch payload. Email steps require subject plus blocks or html. Inserted email steps inherit the effective identity of the nearest sequence email unless the step sets its own sender fields. After a branch merge, only identity fields shared by every incoming path are inherited; conflicting fields use sequence or company defaults.", "items": { "$ref": "#/components/schemas/SequenceBranchPathStepInput" } } } }, "SequenceGraphEdgeInput": { "type": "object", "required": [ "sourceNodeId", "targetNodeId" ], "properties": { "sourceNodeId": { "type": "string", "description": "Existing source node ID.", "example": "node_trigger" }, "targetNodeId": { "type": "string", "description": "Existing target node ID.", "example": "node_welcome_email" }, "condition": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Exact branch-lane condition for this edge. Omit or set null for an unconditional edge.", "example": { "branchId": "branch-0" } } } }, "SequenceGraphEditInput": { "type": "object", "required": [ "action", "expectedRevision" ], "properties": { "action": { "type": "string", "enum": [ "move_node", "delete_node", "duplicate_node", "replace_edges" ], "description": "Structural graph operation to perform." }, "expectedRevision": { "type": "string", "description": "graphRevision from the latest get-sequence response. The update is rejected if the graph changed after it was read.", "example": "75afbbfe05c1a96dc4f167eecc80b14113a3b76b47fb1b193492ddcd2b1d3e21" }, "nodeId": { "type": "string", "description": "Existing node to move, delete, or duplicate." }, "afterNodeId": { "type": "string", "description": "Insert the moved or duplicated node immediately after this node. Mutually exclusive with beforeNodeId." }, "beforeNodeId": { "type": "string", "description": "Insert the moved or duplicated node immediately before this node. Mutually exclusive with afterNodeId." }, "edges": { "type": "array", "description": "Complete replacement topology for replace_edges. Also supported when deleting a split node whose continuation cannot be inferred safely.", "items": { "$ref": "#/components/schemas/SequenceGraphEdgeInput" } } } }, "EmailThemePatch": { "type": [ "object", "null" ], "additionalProperties": false, "description": "Partial visual theme patch. Omitted fields keep their current value, so {\"colors\": {\"background\": \"#f3f4f6\"}} repaints only the outer canvas, while content controls the inner card the blocks sit on. Colors are 6-digit hex; numeric values are clamped to their supported ranges. Null clears the stored theme.", "properties": { "presetId": { "type": "string", "enum": [ "default", "soft", "editorial", "bold" ] }, "buttonStyle": { "type": "string", "enum": [ "solid", "outline" ] }, "colors": { "type": "object", "additionalProperties": false, "properties": { "primary": { "type": "string" }, "background": { "type": "string", "description": "Outer canvas behind the email." }, "content": { "type": "string", "description": "Inner content card. Omit to preserve its current value; when no content color is stored, the card follows the outer canvas." }, "surface": { "type": "string", "description": "Nested cards and tinted tiles." }, "text": { "type": "string" }, "mutedText": { "type": "string" }, "heading": { "type": "string" }, "border": { "type": "string" }, "link": { "type": "string" }, "buttonText": { "type": "string" } } }, "typography": { "type": "object", "additionalProperties": false, "properties": { "baseFontSize": { "type": "number" }, "leadFontSize": { "type": "number" }, "baseLineHeight": { "type": "number" }, "heading1Size": { "type": "number" }, "heading2Size": { "type": "number" }, "heading3Size": { "type": "number" }, "buttonFontSize": { "type": "number" }, "buttonFontWeight": { "type": "number" }, "headingFontWeight": { "type": "number" }, "headingFontFamily": { "type": "string" }, "headingLetterSpacing": { "type": "number" } } }, "layout": { "type": "object", "additionalProperties": false, "properties": { "contentWidth": { "type": "number" }, "containerPaddingX": { "type": "number" }, "containerPaddingY": { "type": "number" }, "blockSpacing": { "type": "number" }, "baseRadius": { "type": "number" }, "buttonRadius": { "type": "number" }, "sectionPadding": { "type": "number" }, "buttonPaddingX": { "type": "number" }, "buttonPaddingY": { "type": "number" }, "borderedBlockPadding": { "type": "number" } } } } }, "SequenceNodeUpdateInput": { "type": "object", "required": [ "nodeId", "changes" ], "properties": { "nodeId": { "type": "string", "description": "Existing sequence node ID returned by get sequence.", "example": "node_abc123" }, "changes": { "type": "object", "minProperties": 1, "additionalProperties": true, "description": "Type-aware node patch. Use the editableFields and notes from the node's updateHints. Omitted fields are preserved. For action_email nodes, a blocks patch that omits emailPreset never changes the step's format - see blocks on SequenceEmailUpdateInput.", "properties": { "emailPreset": { "type": "string", "enum": [ "branded", "minimal" ], "description": "For action_email nodes, set the linked email's per-email Style > Format. Native block emails may include supported custom HTML blocks. Not supported when the entire email is standalone raw HTML." }, "emailTheme": { "allOf": [ { "$ref": "#/components/schemas/EmailThemePatch" } ], "description": "For action_email nodes, override this step's linked email theme only. The company default and every other email are untouched. The patch merges into the email's current theme, and a step with no override merges into the company theme rather than the platform preset. Send null to drop the override so the step follows the company theme again." } } }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional optimistic-concurrency token from the node's latest updatedAt or updateHints.expectedUpdatedAt value. MCP clients require this field.", "example": "2026-07-17T10:00:00.000Z" } } }, "SequenceUpdateRequest": { "type": "object", "properties": { "description": { "type": "string", "description": "Updated dashboard description." }, "userCancellable": { "type": "boolean", "description": "Whether recipients can cancel this sequence from email preferences." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Replacement dashboard label names. Missing labels are created." }, "fromEmail": { "type": "string", "format": "email", "description": "From address for every email in this sequence. Its domain must be configured and verified." }, "fromName": { "type": "string", "description": "Display name recipients see, e.g. 'Brennon at TradeTally'. Selects the sender identity of that name on fromEmail, creating it when the address has no identity by that name; the mailbox's other display names, and everything pinned to them, are untouched. Requires fromEmail; omit it when using senderProfileId, which already carries its own display name." }, "senderProfileId": { "type": "string", "description": "Existing sender profile ID. It already supplies both the From address and display name, so send it on its own and omit fromEmail and fromName. To keep this profile under a different display name, set fromName on the email steps instead, where it is a per-step override." }, "replyTo": { "type": "string", "format": "email", "description": "Reply-To address for every email in this sequence." }, "replyToName": { "type": "string", "description": "Display name for the Reply-To address. Requires replyTo; omit it when using replyProfileId, which already carries its own display name. An address carries one Reply-To name company-wide, so if replyTo already has a saved profile under a different name, that saved name is kept and the response `warnings` array says so." }, "replyProfileId": { "type": "string", "description": "Existing reply profile ID. It already supplies both the Reply-To address and display name, so send it on its own and omit replyTo and replyToName." }, "name": { "type": "string", "description": "Updated sequence name.", "example": "Updated Welcome Sequence" }, "trigger": { "$ref": "#/components/schemas/SequenceTriggerType", "description": "Atomically replaces the current trigger. Include its typed configuration fields in the same request. Active sequences require confirmLiveChange." }, "listId": { "type": "string", "description": "List ID for a replacement contact_added trigger." }, "listIds": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string" }, "description": "Several list IDs for a replacement contact_added trigger. A contact joining ANY of them enrolls. Cannot be combined with listScope." }, "listScope": { "type": "string", "enum": [ "any_contact", "any_list" ], "default": "any_contact", "description": "For a replacement contact_added trigger with no list. `any_contact` (the default) enrolls every contact added, even one that joins no list; `any_list` waits for a list membership. Cannot be combined with listId or listIds." }, "tagName": { "type": "string", "description": "Tag name for a replacement tag_added trigger." }, "tagNames": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string" }, "description": "Several tag names for a replacement tag_added trigger. Receiving ANY of them enrolls the contact." }, "segmentId": { "type": "string", "description": "Segment ID for a replacement segment_entered trigger." }, "stopOnSegmentExit": { "type": "boolean", "description": "Stop active enrollments when a contact leaves the replacement trigger segment." }, "eventName": { "type": "string", "description": "Event name for event_received, inbound_webhook, inactivity, or frequency triggers." }, "propertyFilters": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/SequenceTriggerPropertyFilter" } }, "integrationSlug": { "type": "string", "description": "Catalog integration slug for an inbound_webhook trigger." }, "integrationEventKey": { "type": "string", "description": "Catalog event key for an inbound_webhook trigger." }, "customIntegration": { "type": "object", "additionalProperties": true, "description": "Custom integration descriptor for an inbound_webhook trigger." }, "inactiveDays": { "type": "number", "minimum": 1 }, "inactivityBaseline": { "type": "string", "enum": [ "sequence_created_at", "subscriber_created_at" ] }, "minCount": { "type": "number", "minimum": 1 }, "timeWindowDays": { "type": "number", "minimum": 1 }, "enrollmentPaused": { "type": "boolean", "description": "Set true to stop new enrollments for an active sequence while current recipients continue. Set false to resume new enrollments.", "example": true }, "confirmStructuralChange": { "type": "boolean", "description": "Required when inserting steps or branches, or editing the graph of an active sequence. Set true only after confirming the live-flow impact for current and future recipients.", "example": true }, "confirmLiveChange": { "type": "boolean", "description": "Required for trigger replacement or nodeUpdates on an active sequence. Set true only after confirming that the edits can affect recipients who reach those nodes in the future.", "example": true }, "enrollmentMode": { "$ref": "#/components/schemas/SequenceEnrollmentMode" }, "enrollmentFieldPath": { "type": [ "string", "null" ], "description": "Scalar dot-path event property used by matching_field enrollment on event_received and inbound_webhook sequences. Array traversal with [] is not supported; use propertyFilters for array matching. Set to null to use built-in defaults.", "example": "order.id" }, "sendingWindow": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceSendingWindow" } ] }, { "type": "null" } ] }, "keyDates": { "description": "Replace the sequence key dates. Contacts already waiting on a key-date step are re-scheduled to the new dates. Set to null to remove them (rejected while a step still waits for one).", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceKeyDates" } ] }, { "type": "null" } ] }, "audienceAutoEnroll": { "description": "Keep enrolling later joiners of an audience until the last key date. Null clears it. Changing the trigger away from manual switches it off (endedReason \"disabled\").", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceAudienceAutoEnroll" } ] }, { "type": "null" } ] }, "bccEmails": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Email addresses that receive a blind copy of every email this sequence sends, such as a customer support inbox (max 10). Set to null to remove them.", "example": [ "cs-team@example.com", "founder@example.com" ] }, "stopCondition": { "$ref": "#/components/schemas/SequenceStopCondition" }, "branch": { "$ref": "#/components/schemas/SequenceBranchInput" }, "insertSteps": { "$ref": "#/components/schemas/SequenceLinearStepInsertionInput" }, "graphEdit": { "$ref": "#/components/schemas/SequenceGraphEditInput" }, "nodeUpdates": { "type": "array", "minItems": 1, "description": "Atomic, type-aware patches for existing sequence nodes. A node may appear only once, and either every patch commits or none do.", "items": { "$ref": "#/components/schemas/SequenceNodeUpdateInput" } }, "emails": { "type": "array", "description": "Existing email step updates. Provide either emails or steps. Items without nodeId or emailId are matched by existing step order and do not create new steps.", "items": { "$ref": "#/components/schemas/SequenceEmailUpdateInput" } }, "steps": { "type": "array", "description": "Alias for emails. Use insertSteps to create new steps.", "items": { "$ref": "#/components/schemas/SequenceEmailUpdateInput" } }, "smsSteps": { "type": "array", "description": "Content updates for existing SMS steps, targeted by action_sms nodeId. Content-only edits; use insertSteps to create new SMS steps.", "items": { "$ref": "#/components/schemas/SequenceSmsStepUpdateInput" } }, "subscriberUpdateSteps": { "type": "array", "description": "Full config replacements for existing action_update_attributes steps, targeted by nodeId.", "items": { "$ref": "#/components/schemas/SequenceSubscriberUpdateStepUpdateInput" } } } }, "SubscriberUpdateConfig": { "type": "object", "description": "Update Subscriber config. String values may use standalone trigger-event merge tags such as {{event.plan}}, {{event.amount}}, or {{event.active}}. Number and boolean values are coerced after resolution.", "additionalProperties": true, "properties": { "label": { "type": "string" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "unsubscribed", "bounced" ] }, "customAttributeUpdates": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "description": "Literal scalar, null to delete, or one standalone merge tag.", "anyOf": [ { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "null" } ] }, "valueType": { "type": "string", "enum": [ "text", "number", "boolean" ] } } } } } }, "SequencePathStepConfig": { "type": "object", "description": "Config for advanced nodeType steps. Required fields depend on nodeType: action_add_tag and action_remove_tag need tagId or tagName; action_add_to_list and action_remove_from_list need listId; action_update_attributes uses the Update Subscriber fields and may reference the trigger event payload; logic_wait_for_event needs eventName plus optional timeoutDays and timeoutAction; logic_condition needs conditionType plus that condition's resource field; action_webhook needs an HTTPS url plus optional method, headers, body, resultKey, and onError; action_ai needs prompt, resultKey, and outputFields plus optional includeTags, includeEventProperties, includeRecentEvents, recentEventLimit, includeAttributes, and onError; logic_delay uses delayDays, delayHours, and delayMinutes. Fields that do not apply to the node type are dropped.", "allOf": [ { "$ref": "#/components/schemas/SubscriberUpdateConfig" } ], "additionalProperties": true, "properties": { "tagId": { "type": "string", "description": "action_add_tag / action_remove_tag. Tag ID; tag actions resolve it by ID only, so pass a name in tagName instead. has_tag and does_not_have_tag also accept a tag name here. Missing tag definitions are created automatically.", "example": "tag_01HZY8Q2N4" }, "tagName": { "type": "string", "description": "action_add_tag / action_remove_tag / has_tag / does_not_have_tag. Tag name; use instead of tagId when you only know the name.", "example": "newsletter-confirmed" }, "listId": { "type": "string", "description": "action_add_to_list / action_remove_from_list / in_list. Must match an existing list in this company; listName is filled in for you." }, "listName": { "type": "string", "description": "Optional cached list display name for list actions." }, "eventName": { "type": "string", "description": "logic_wait_for_event and event_received conditions. Event to wait for or check.", "example": "email.replied" }, "timeoutDays": { "type": "number", "description": "logic_wait_for_event. Maximum wait in whole days from 1 to 365. Defaults to 7." }, "timeoutAction": { "type": "string", "enum": [ "continue", "exit" ], "description": "logic_wait_for_event. Continue to the next node or exit the sequence on timeout. Defaults to continue." }, "conditionType": { "type": "string", "enum": [ "has_tag", "does_not_have_tag", "in_list", "in_segment", "event_received", "link_clicked", "field_equals", "field_contains", "field_greater_than", "field_less_than", "has_phone", "sms_subscribed" ], "description": "logic_condition. Condition evaluated before continuing. has_phone and sms_subscribed need no resource fields." }, "segmentId": { "type": "string", "description": "logic_condition. Segment ID for in_segment." }, "segmentName": { "type": "string", "description": "Optional cached segment display name." }, "linkUrl": { "type": "string", "description": "logic_condition. Optional URL substring for link_clicked. Omit to match any tracked click." }, "activityScope": { "type": "string", "enum": [ "ever", "this_sequence", "previous_email" ], "description": "logic_condition. Scope for event_received and link_clicked checks." }, "fieldName": { "type": "string", "description": "logic_condition. Subscriber attribute name/path for field comparisons." }, "fieldValue": { "type": "string", "description": "logic_condition. Comparison value for field comparisons." }, "url": { "type": "string", "description": "action_webhook. Destination HTTPS URL called when a subscriber reaches this step. Supports merge tags like {{email}} and {{event.order_id}} resolved at execution time." }, "method": { "type": "string", "enum": [ "POST", "GET", "PUT", "PATCH", "DELETE" ], "description": "action_webhook. HTTP method. Defaults to POST." }, "headers": { "type": "object", "description": "action_webhook. Optional string-valued request headers. Values support merge tags. Secret values are redacted on sequence reads.", "additionalProperties": { "type": "string" } }, "body": { "type": "string", "description": "action_webhook. Optional JSON body template for POST/PUT/PATCH requests. Must be valid JSON as written, with merge tags inside quoted string values; a tag in a bare value position is rejected. Tags are resolved at execution time. When omitted, a default payload with the subscriber and sequence context is sent." }, "resultKey": { "type": "string", "description": "action_webhook / action_ai. Where the result is saved for the enrollment. Later steps reference it via {{webhooks.KEY.data.field}} (webhook) or {{ai.KEY.field}} (AI) merge tags. Required for action_ai. Must start with a letter and use only letters, numbers, or underscores (max 64 chars)." }, "onError": { "type": "string", "enum": [ "continue", "exit", "fail" ], "description": "action_webhook / action_ai. Behavior when the step fails - continue to the next step, exit the sequence, or fail the enrollment. Defaults to fail for webhooks and continue for AI steps (fallbacks fill the output fields)." }, "prompt": { "type": "string", "description": "action_ai. Prompt template sent to the model, resolved per contact at execution time. Supports merge tags like {{first_name}}, {{event.plan}}, and {{webhooks.KEY.data.field}}. Max 8000 characters." }, "outputFields": { "type": "array", "description": "action_ai. Named values the model must return (1-10). Each key becomes a {{ai.KEY.}} merge tag for later steps. fallback is used when generation fails so emails still send with sensible copy. Combined field maxLength values must fit the step's conservative 2000-token multilingual response budget plus JSON overhead.", "items": { "type": "object", "required": [ "key" ], "additionalProperties": false, "properties": { "key": { "type": "string", "description": "Field key, e.g. subject_line. Must start with a letter and use only letters, numbers, or underscores (max 64 chars); unique within the step." }, "description": { "type": "string", "description": "What the model should produce for this field. Max 300 characters." }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 4000, "description": "Hard cap on stored characters (1-4000). Defaults to 500. Output beyond it is cut." }, "fallback": { "type": "string", "description": "Text used verbatim when generation fails or the model omits the field." } } } }, "includeTags": { "type": "boolean", "description": "action_ai. Include the contact's tags in the prompt context." }, "includeEventProperties": { "type": "boolean", "description": "action_ai. Include the enrollment's trigger event name and properties in the prompt context." }, "includeRecentEvents": { "type": "boolean", "description": "action_ai. Include the contact's most recent custom events (newest first) in the prompt context." }, "recentEventLimit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "action_ai. How many recent events to include when includeRecentEvents is true. Defaults to 10." }, "includeAttributes": { "type": "array", "items": { "type": "string" }, "description": "action_ai. Custom attribute keys to include in the prompt context (max 30). Only the listed keys are sent." }, "delayDays": { "type": "number", "description": "logic_delay. Whole days to wait." }, "delayHours": { "type": "number", "description": "logic_delay. Hours to wait." }, "delayMinutes": { "type": "number", "description": "logic_delay. Minutes to wait." } } }, "SequenceSubscriberUpdateStepUpdateInput": { "type": "object", "required": [ "nodeId", "config" ], "properties": { "nodeId": { "type": "string", "description": "Target action_update_attributes node ID." }, "config": { "$ref": "#/components/schemas/SubscriberUpdateConfig" } } }, "SequenceSmsStepUpdateInput": { "type": "object", "required": [ "nodeId" ], "properties": { "nodeId": { "type": "string", "description": "Target action_sms node ID from GET /sequences/{sequenceId}.", "example": "node_sms123" }, "text": { "type": "string", "description": "Replacement plain-text message body. Merge tags like {{FIRST_NAME}} work. Provide text or blocks, not both.", "example": "Hey {{FIRST_NAME}}, your order shipped!" }, "blocks": { "type": "array", "description": "Replacement SMS content blocks (text + image subset).", "items": { "type": "object" } }, "imageUrls": { "type": "array", "description": "Up to 2 publicly reachable MMS image URLs. Only valid together with text.", "items": { "type": "string" } }, "label": { "type": "string", "description": "Updated display label for the step.", "example": "Shipping text" }, "ineligibleAction": { "type": "string", "enum": [ "skip", "exit" ], "description": "Updated behavior when the contact can't receive SMS." } } }, "SequencePosition": { "type": "object", "properties": { "x": { "type": "number", "example": 300 }, "y": { "type": "number", "example": 150 } } }, "SequenceNode": { "type": "object", "properties": { "id": { "type": "string", "example": "node_abc123" }, "automationId": { "type": "string", "example": "seq_abc123" }, "nodeType": { "type": "string", "example": "action_email" }, "config": { "type": "object", "additionalProperties": true }, "structuralStepNumber": { "type": "number", "description": "Graph-derived email depth. Present on action_email and action_ab_test nodes reachable from a trigger; parallel branch emails intentionally share a depth.", "example": 1 }, "updatedAt": { "type": "string", "format": "date-time", "description": "Node concurrency timestamp. Return this as expectedUpdatedAt when patching the node.", "example": "2026-07-17T10:00:00.000Z" }, "updateHints": { "type": "object", "description": "Type-aware guidance for safely patching this node.", "properties": { "tool": { "type": "string", "example": "update_sequence_node" }, "editableFields": { "type": "array", "items": { "type": "string" } }, "managedFields": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Ready-to-return optimistic-concurrency token for update_sequence_node or update_sequence_nodes.", "example": "2026-07-17T10:00:00.000Z" } } }, "position": { "$ref": "#/components/schemas/SequencePosition" } } }, "SequenceAbTestStepVariant": { "type": "object", "properties": { "variantId": { "type": "string", "example": "var_b" }, "variantLabel": { "type": "string", "example": "B" }, "emailId": { "type": "string", "description": "Email template holding this variant's stored copy.", "example": "email_variant_b" }, "subject": { "type": [ "string", "null" ], "example": "Your pick is waiting" }, "previewText": { "type": [ "string", "null" ] }, "isWinner": { "type": "boolean" }, "blockCount": { "type": "number", "description": "Number of blocks in this variant's body. Same as blocks.length.", "example": 4 }, "blocks": { "type": "array", "description": "This variant's email body. Present when ab_tests:read is granted. Step-level blocks remain control variant A only.", "items": { "$ref": "#/components/schemas/EmailBlock" } } } }, "AbTestContentEditing": { "type": "object", "description": "Where a sequence A/B step's copy lives and which tools change it.", "required": [ "readTool", "writeTool", "requiredScopes", "note" ], "properties": { "readTool": { "type": "string", "example": "get_ab_test" }, "writeTool": { "type": "string", "example": "update_ab_test_variant" }, "requiredScopes": { "type": "array", "items": { "type": "string" }, "example": [ "ab_tests:read", "ab_tests:write", "sequences:write" ] }, "note": { "type": "string" } } }, "SequenceAbTestStepSummary": { "type": "object", "description": "A/B test attached to an action_ab_test step. The step's own subject, previewText, and blocks are control variant A only. With ab_tests:read, variants[] includes each variant's full blocks. Without ab_tests:read, record-backed fields are null and variants is empty while the configured id and editing guidance remain available.", "properties": { "id": { "type": [ "string", "null" ], "example": "ab_abc123" }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "example": "testing" }, "testType": { "type": [ "string", "null" ], "enum": [ "subject", "content", null ] }, "winnerCriteria": { "type": [ "string", "null" ], "example": "click_rate" }, "winnerThreshold": { "type": [ "number", "null" ] }, "winningVariantId": { "type": [ "string", "null" ] }, "variantCount": { "type": "number", "example": 2 }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceAbTestStepVariant" } }, "contentEditing": { "$ref": "#/components/schemas/AbTestContentEditing" } } }, "SequenceEmail": { "type": "object", "properties": { "nodeId": { "type": "string", "example": "node_abc123" }, "nodeType": { "type": "string", "enum": [ "action_email", "action_ab_test" ], "description": "Step type. action_ab_test steps keep their copy on the A/B test variants; the fields below report control variant A.", "example": "action_email" }, "abTest": { "description": "Null on ordinary email steps. Present on action_ab_test steps.", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceAbTestStepSummary" } ] }, { "type": "null" } ] }, "emailId": { "type": [ "string", "null" ], "example": "email_abc123" }, "stepNumber": { "type": [ "number", "null" ], "example": 1 }, "structuralStepNumber": { "type": [ "number", "null" ], "description": "Graph-derived email depth, or null when the node is not reachable from a trigger. Parallel branch emails intentionally share a depth.", "example": 1 }, "name": { "type": [ "string", "null" ], "example": "Welcome Sequence - Email 1" }, "subject": { "type": [ "string", "null" ], "example": "Welcome to Acme" }, "previewText": { "type": [ "string", "null" ], "example": "Start here" }, "isTransactional": { "type": "boolean" }, "senderProfileId": { "type": [ "string", "null" ] }, "replyProfileId": { "type": [ "string", "null" ] }, "fromName": { "type": [ "string", "null" ] }, "replyTo": { "type": [ "string", "null" ] }, "ccEmails": { "type": [ "array", "null" ], "items": { "type": "string", "format": "email" } }, "bccEmails": { "type": [ "array", "null" ], "items": { "type": "string", "format": "email" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/UrlAttachment" }, "description": "URL-backed file attachments configured on this email step, including event-backed URL templates." }, "emailPreset": { "type": [ "string", "null" ], "enum": [ "branded", "minimal", null ], "description": "Effective per-email Style > Format derived from native persisted blocks, including emails that contain supported custom HTML blocks. Null when the node has no linked email or the entire email is standalone raw HTML.", "example": "minimal" }, "emailTheme": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Theme override stored on this step's linked email. Null when the step has no override and renders on the company theme." }, "delayNodeId": { "type": [ "string", "null" ], "description": "ID of the logic_delay node immediately before this email, when present.", "example": "node_delay_abc123" }, "delayMs": { "type": [ "number", "null" ], "description": "Delay before this email in milliseconds, derived from the preceding logic_delay node when present.", "example": 259200000 }, "delayMode": { "type": [ "string", "null" ], "enum": [ "duration", "until_date", "until_weekday", "until_key_date", null ], "description": "Delay mode for the preceding logic_delay node, when present.", "example": "until_date" }, "waitUntil": { "description": "Date-field wait metadata (field, source, direction, missingAction, pastAction, offset) for dynamic wait-until-date delays.", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceWaitUntilInput" } ] }, { "type": "null" } ] }, "waitUntilWeekday": { "description": "Weekday-window metadata for dynamic wait-until-weekday delays.", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceWaitUntilWeekdayInput" } ] }, { "type": "null" } ] }, "waitUntilKeyDate": { "description": "Key-date wait metadata (key, direction, missingAction, pastAction, offset) for until_key_date delays.", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceWaitUntilKeyDateInput" } ] }, { "type": "null" } ] }, "delayDisplay": { "type": [ "string", "null" ], "description": "Human-readable delay before this email, derived from the preceding logic_delay node when present.", "example": "3 days" }, "delayDescription": { "type": [ "string", "null" ], "description": "Description stored on the preceding logic_delay node, when present.", "example": "Wait 3 days" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlock" } } } }, "SequenceSummary": { "type": "object", "properties": { "id": { "type": "string", "example": "seq_abc123" }, "name": { "type": "string", "example": "Welcome Sequence" }, "description": { "type": [ "string", "null" ] }, "userCancellable": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "labelIds": { "type": "array", "items": { "type": "string" } }, "status": { "$ref": "#/components/schemas/SequenceStatus" }, "enrollmentPaused": { "type": "boolean", "description": "Whether new enrollments are paused while current recipients continue." }, "effectiveStatus": { "$ref": "#/components/schemas/SequenceEffectiveStatus" }, "acceptsNewEnrollments": { "type": "boolean", "description": "Whether new subscribers can enter the sequence right now." }, "processesExistingEnrollments": { "type": "boolean", "description": "Whether subscribers already inside the sequence keep advancing and receiving steps." }, "effectiveStatusSummary": { "type": "string", "description": "One plain-language sentence describing the run state, safe to show a user verbatim." }, "pauseReason": { "type": [ "string", "null" ] }, "pauseSource": { "type": [ "string", "null" ] }, "pausedByUserId": { "type": [ "string", "null" ] }, "pausedByUser": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "pausedAt": { "type": [ "string", "null" ], "format": "date-time" }, "trigger": { "type": [ "string", "null" ], "example": "trigger_list" }, "triggerConfig": { "type": [ "object", "null" ], "additionalProperties": true }, "sendingWindow": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceSendingWindow" } ] }, { "type": "null" } ] }, "keyDates": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceKeyDates" } ] }, { "type": "null" } ] }, "audienceAutoEnroll": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceAudienceAutoEnroll" } ] }, { "type": "null" } ] }, "bccEmails": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Email addresses blind-copied on every email this sequence sends.", "example": [ "cs-team@example.com" ] }, "senderProfileId": { "type": [ "string", "null" ] }, "fromName": { "type": [ "string", "null" ] }, "fromEmail": { "type": [ "string", "null" ], "format": "email" }, "replyProfileId": { "type": [ "string", "null" ] }, "replyToName": { "type": [ "string", "null" ] }, "replyToEmail": { "type": [ "string", "null" ], "format": "email" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SequenceDetails": { "allOf": [ { "$ref": "#/components/schemas/SequenceSummary" }, { "type": "object", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceNode" } }, "edges": { "type": "array", "description": "Editable sequence topology. Pass the complete set back to graphEdit.edges when replacing edges.", "items": { "$ref": "#/components/schemas/SequenceGraphEdgeInput" } }, "graphRevision": { "type": "string", "description": "Revision token for optimistic graph edits. Supply this as graphEdit.expectedRevision.", "example": "75afbbfe05c1a96dc4f167eecc80b14113a3b76b47fb1b193492ddcd2b1d3e21" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceEmail" } }, "stopCondition": { "$ref": "#/components/schemas/SequenceStopCondition" }, "enrichmentStatus": { "type": "string", "enum": [ "pending", "in_progress", "complete" ], "example": "complete" }, "emailCount": { "type": "number", "description": "Number of email-sending steps, including action_ab_test steps.", "example": 2 }, "abTestCount": { "type": "number", "description": "How many of the email steps are A/B test steps.", "example": 1 }, "discountCount": { "type": "number", "example": 1 }, "subscriberUpdateCount": { "type": "number", "example": 1 }, "enrichedCount": { "type": "number", "example": 2 } } } ] }, "SequenceCreateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Sequence created with 2 emails and 1 discount action. Use POST /api/v1/sequences/{id}/enable to activate." }, "sequence": { "type": "object", "properties": { "id": { "type": "string", "example": "seq_abc123" }, "name": { "type": "string", "example": "Welcome Sequence" }, "status": { "$ref": "#/components/schemas/SequenceStatus" }, "enrollmentPaused": { "type": "boolean", "description": "Whether new enrollments are paused while current recipients continue." }, "effectiveStatus": { "$ref": "#/components/schemas/SequenceEffectiveStatus" }, "acceptsNewEnrollments": { "type": "boolean", "description": "Whether new subscribers can enter the sequence right now." }, "processesExistingEnrollments": { "type": "boolean", "description": "Whether subscribers already inside the sequence keep advancing and receiving steps." }, "effectiveStatusSummary": { "type": "string", "description": "One plain-language sentence describing the run state, safe to show a user verbatim." }, "trigger": { "type": "string", "example": "trigger_list" }, "emailCount": { "type": "number", "example": 2 }, "discountCount": { "type": "number", "example": 1 }, "subscriberUpdateCount": { "type": "number", "example": 1 }, "nodeCount": { "type": "number", "example": 5 }, "enrichmentStatus": { "type": "string", "example": "processing" }, "stopCondition": { "$ref": "#/components/schemas/SequenceStopCondition" }, "sendingWindow": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceSendingWindow" } ] }, { "type": "null" } ] }, "keyDates": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceKeyDates" } ] }, { "type": "null" } ] } } }, "warnings": { "$ref": "#/components/schemas/BlockFieldWarnings", "description": "Non-blocking advisories about a created sequence. Besides block and sender-identity advisories, POST /sequences reports request fields that were ignored (such as a nested `triggerConfig`, `delay: 2`, `delayDays` or a body `companyId` that differs from the selected company), `contact_added` list IDs not found in the company, and a `contact_added` trigger sent with no list and no `listScope`. The sequence is still created as a draft; fix these before enabling it. Absent when there is nothing to report." }, "eventTrackingCode": { "type": "string", "description": "Code snippet returned for custom event triggers." }, "eventTracking": { "type": "object", "description": "Endpoint, payload contract, example, documentation, and integration-guide pointer returned for custom event triggers.", "properties": { "endpoint": { "type": "string", "example": "https://api.sequenzy.com/api/v1/subscribers/events" }, "method": { "type": "string", "example": "POST" }, "docsUrl": { "type": "string", "example": "https://docs.sequenzy.com/api-reference/subscribers/events/trigger" }, "integrationGuide": { "type": "object", "properties": { "tool": { "type": "string", "example": "get_integration_guide" }, "arguments": { "type": "object", "additionalProperties": true, "example": { "use_case": "event_tracking" } } } }, "payloadContract": { "type": "object", "properties": { "required": { "type": "array", "items": { "type": "string" } }, "identity": { "type": "string" }, "event": { "type": "string" }, "properties": { "type": "string" }, "requiredPropertyPaths": { "type": "array", "items": { "type": "string" } }, "propertyFilters": { "type": "array", "description": "Normalized trigger filters that the event properties must satisfy before the sequence can enroll the subscriber.", "items": { "$ref": "#/components/schemas/SequenceTriggerPropertyFilter" } } } }, "examplePayload": { "type": "object", "additionalProperties": true, "example": { "email": "user@example.com", "event": "trial.started", "properties": { "trial_id": "" } } }, "examplePayloadMatchesFilters": { "type": "boolean", "description": "Whether examplePayload already satisfies every normalized property filter. When false, adapt properties using payloadContract before sending the sample.", "example": true }, "examplePayloadNote": { "type": "string", "description": "Present when the generated example needs manual property adaptation before it satisfies every filter." } } }, "requiredEvents": { "type": "array", "items": { "type": "string" } } } }, "SequenceActionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Sequence enabled" }, "sequenceId": { "type": "string", "example": "seq_abc123" }, "status": { "$ref": "#/components/schemas/SequenceStatus" }, "enrollmentPaused": { "type": "boolean", "description": "Present for enable/disable and enrollment pause/resume actions.", "example": true }, "effectiveStatus": { "$ref": "#/components/schemas/SequenceEffectiveStatus" }, "acceptsNewEnrollments": { "type": "boolean", "description": "Whether new subscribers can enter the sequence right now." }, "processesExistingEnrollments": { "type": "boolean", "description": "Whether subscribers already inside the sequence keep advancing and receiving steps." }, "effectiveStatusSummary": { "type": "string", "description": "One plain-language sentence describing the run state, safe to show a user verbatim." }, "warnings": { "type": "array", "description": "Enable only. Non-blocking readiness warnings, such as empty branch paths or a `contact_added` trigger with no list, which enrolls every contact added to the company. Absent when there is nothing to report.", "items": { "type": "string" } } } }, "SequenceGoal": { "type": "object", "properties": { "id": { "type": "string" }, "automationId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "triggerType": { "type": "string", "enum": [ "event", "attribute_change", "tag_added" ] }, "triggerEventName": { "type": "string" }, "triggerTagName": { "type": [ "string", "null" ] }, "attributePath": { "type": [ "string", "null" ] }, "attributeCondition": { "type": [ "string", "null" ], "enum": [ "changed", "changed_to", "changed_from_to", null ] }, "attributeValue": { "type": [ "string", "null" ] }, "attributePreviousValue": { "type": [ "string", "null" ] }, "eventPropertyName": { "type": [ "string", "null" ] }, "eventPropertyLabel": { "type": [ "string", "null" ] }, "attributionWindowHours": { "type": "integer" }, "isActive": { "type": "boolean" } } }, "SequenceGoalInput": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "triggerType": { "type": "string", "enum": [ "event", "attribute_change", "tag_added" ] }, "triggerEventName": { "type": [ "string", "null" ] }, "triggerTagName": { "type": [ "string", "null" ] }, "attributePath": { "type": [ "string", "null" ] }, "attributeCondition": { "type": [ "string", "null" ], "enum": [ "changed", "changed_to", "changed_from_to", null ] }, "attributeValue": { "type": [ "string", "null" ] }, "attributePreviousValue": { "type": [ "string", "null" ] }, "eventPropertyName": { "type": [ "string", "null" ] }, "eventPropertyLabel": { "type": [ "string", "null" ] }, "attributionWindowHours": { "type": "integer", "minimum": 1, "maximum": 720 }, "isActive": { "type": "boolean" } } }, "CampaignGoal": { "type": "object", "properties": { "id": { "type": "string" }, "campaignId": { "type": "string" }, "scope": { "type": "string", "enum": [ "campaign" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "triggerType": { "type": "string", "enum": [ "event", "attribute_change", "tag_added" ] }, "triggerEventName": { "type": "string" }, "triggerTagName": { "type": [ "string", "null" ] }, "attributePath": { "type": [ "string", "null" ] }, "attributeCondition": { "type": [ "string", "null" ], "enum": [ "changed", "changed_to", "changed_from_to", null ] }, "attributeValue": { "type": [ "string", "null" ] }, "attributePreviousValue": { "type": [ "string", "null" ] }, "eventPropertyName": { "type": [ "string", "null" ] }, "eventPropertyLabel": { "type": [ "string", "null" ] }, "attributionWindowHours": { "type": "integer" }, "isActive": { "type": "boolean" } } }, "CompanyGoal": { "type": "object", "properties": { "id": { "type": "string" }, "campaignId": { "type": "null" }, "scope": { "type": "string", "enum": [ "company" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "triggerType": { "type": "string", "enum": [ "event", "attribute_change", "tag_added" ] }, "triggerEventName": { "type": "string" }, "triggerTagName": { "type": [ "string", "null" ] }, "attributePath": { "type": [ "string", "null" ] }, "attributeCondition": { "type": [ "string", "null" ], "enum": [ "changed", "changed_to", "changed_from_to", null ] }, "attributeValue": { "type": [ "string", "null" ] }, "attributePreviousValue": { "type": [ "string", "null" ] }, "eventPropertyName": { "type": [ "string", "null" ] }, "eventPropertyLabel": { "type": [ "string", "null" ] }, "attributionWindowHours": { "type": "integer" }, "isActive": { "type": "boolean" } } }, "CampaignGoalInput": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "triggerType": { "type": "string", "enum": [ "event", "attribute_change", "tag_added" ] }, "triggerEventName": { "type": [ "string", "null" ] }, "triggerTagName": { "type": [ "string", "null" ] }, "attributePath": { "type": [ "string", "null" ] }, "attributeCondition": { "type": [ "string", "null" ], "enum": [ "changed", "changed_to", "changed_from_to", null ] }, "attributeValue": { "type": [ "string", "null" ] }, "attributePreviousValue": { "type": [ "string", "null" ] }, "eventPropertyName": { "type": [ "string", "null" ] }, "eventPropertyLabel": { "type": [ "string", "null" ] }, "attributionWindowHours": { "type": "integer", "minimum": 1, "maximum": 720 }, "isActive": { "type": "boolean" } } }, "CampaignGoalMetrics": { "type": "object", "properties": { "goalId": { "type": "string" }, "name": { "type": "string" }, "conversions": { "type": "integer" }, "trackedValue": { "type": "number", "description": "Tracked property total in minor units." } } }, "SequenceInboundWebhook": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string", "description": "Secret URL token. Treat it as a credential." }, "url": { "type": "string", "format": "uri" }, "eventName": { "type": "string" }, "fieldMapping": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceInboundWebhookFieldMapping" } ] }, { "type": "null" } ] }, "samplePayload": { "type": [ "object", "null" ], "additionalProperties": true }, "sampleCapturedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "pending_setup", "active" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "SequenceInboundWebhookFieldMapping": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Dot path to the subscriber email in the webhook payload." }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "type": "string" } } } }, "BulkSubscriberTagRequest": { "type": "object", "required": [ "tags" ], "description": "Provide tags plus at least one identifier list. Identifier lists may be combined and total at most 500 entries per request.", "properties": { "tags": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string", "minLength": 1 }, "description": "Tag names applied to every matched subscriber. Names are normalized the same way as single-subscriber tag endpoints.", "example": [ "derived-churn-risk" ] }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Subscriber emails to update." }, "externalIds": { "type": "array", "items": { "type": "string" }, "description": "Customer-owned subscriber IDs to update." }, "subscriberIds": { "type": "array", "items": { "type": "string" }, "description": "Sequenzy subscriber IDs to update." }, "triggerAutomations": { "type": "boolean", "description": "Add only. Whether tag_added sequences may enroll these contacts. Defaults to false and requires the automations:trigger scope.", "example": false } } }, "BulkSubscriberTagResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "False when any matched subscriber failed to update.", "example": true }, "tags": { "type": "array", "items": { "type": "string" } }, "requested": { "type": "integer", "description": "Identifiers supplied in the request.", "example": 3 }, "matched": { "type": "integer", "description": "Existing subscribers resolved from those identifiers.", "example": 2 }, "updated": { "type": "integer", "description": "Subscribers whose tags actually changed.", "example": 2 }, "unchanged": { "type": "integer", "description": "Subscribers that were already in the target state.", "example": 0 }, "failed": { "type": "integer", "example": 0 }, "notFound": { "type": "object", "description": "Identifiers that did not resolve. These subscribers were not created.", "properties": { "emails": { "type": "array", "items": { "type": "string" } }, "externalIds": { "type": "array", "items": { "type": "string" } }, "subscriberIds": { "type": "array", "items": { "type": "string" } } } }, "failures": { "type": "array", "description": "Up to 50 per-subscriber failures.", "items": { "type": "object", "properties": { "subscriberId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "error": { "type": "string" } } } }, "triggeredAutomations": { "type": "boolean", "description": "Add only. Whether tag automations were allowed to run." }, "message": { "type": "string", "example": "Tagged 2 subscribers (0 already in the target state, 0 failed)." } } }, "SequenceEnrollmentCancelRequest": { "type": "object", "description": "Provide exactly one target: cancelAll, subscriberId, subscriberIds, or fieldValues.", "properties": { "cancelAll": { "type": "boolean", "description": "Cancel every active or waiting enrollment in the sequence, regardless of how contacts entered it. Use this when segment-triggered enrollments share no entry field value. Defaults to dry run unless dryRun is explicitly false.", "example": true }, "subscriberId": { "type": "string", "description": "Subscriber ID to cancel in this sequence.", "example": "sub_abc123" }, "subscriberIds": { "type": "array", "description": "Up to 500 subscriber IDs to cancel in this sequence. IDs that do not resolve are returned in target.notFoundSubscriberIds. Defaults to dry run unless dryRun is explicitly false.", "items": { "type": "string" }, "example": [ "sub_abc123", "sub_def456" ] }, "fieldPath": { "type": "string", "description": "Dot-path inside the token's stored entry event properties. If omitted, the sequence enrollmentFieldPath is used.", "example": "order.id" }, "fieldValues": { "type": "array", "description": "Entry field values to match.", "items": { "type": "string" }, "example": [ "ord_123", "ord_456" ] }, "dryRun": { "type": "boolean", "description": "When true, returns matching enrollments without cancelling them. cancelAll, subscriberIds, and fieldValues default to dry run unless explicitly false; a single subscriberId cancels immediately.", "example": false }, "reason": { "type": "string", "description": "Optional reason stored on cancelled enrollment tokens.", "example": "Order cancelled" } } }, "SequenceEnrollmentMoveRequest": { "type": "object", "required": [ "fromNodeId" ], "properties": { "fromNodeId": { "type": "string", "description": "Node ID the contacts are currently sitting on, such as the delay step they are waiting at.", "example": "node_delay_2" }, "targetNodeId": { "type": "string", "description": "Node ID to move them onto. Defaults to the source step's only next step, and is required when that step branches or is terminal. Cannot be the trigger node.", "example": "node_email_3" }, "limit": { "type": "number", "description": "Maximum enrollments to move in this call. Defaults to 100, maximum 500.", "example": 180 }, "sort": { "type": "string", "enum": [ "wait_until_asc", "wait_until_desc", "enrolled_at_asc", "enrolled_at_desc" ], "description": "Which enrollments to take first. Defaults to wait_until_asc, the contacts that have been waiting longest for their next step.", "example": "wait_until_asc" }, "subscriberIds": { "type": "array", "description": "Optional narrowing filter. Only move these subscribers, up to 500.", "items": { "type": "string" }, "example": [ "sub_abc123", "sub_def456" ] }, "dailyLimit": { "type": "number", "description": "Refuses to move more than this many enrollments onto targetNodeId in a rolling 24 hours, counting the moves recorded by earlier calls.", "example": 500 }, "tags": { "type": "array", "description": "Existing tag names applied to the moved contacts. Requires the subscribers:tag scope. Applying them never enrolls contacts in tag_added sequences.", "items": { "type": "string" }, "example": [ "wave-3-released" ] }, "reason": { "type": "string", "description": "Note stored on every moved enrollment and returned as moveReason when listing enrollments.", "example": "Wave 3" }, "dryRun": { "type": "boolean", "description": "When true (the default), reports which enrollments would move without moving them.", "example": false } } }, "SequenceEnrollmentMoveResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "sequenceId": { "type": "string", "example": "seq_abc123" }, "dryRun": { "type": "boolean", "example": false }, "fromNodeId": { "type": "string", "example": "node_delay_2" }, "targetNodeId": { "type": "string", "example": "node_email_3" }, "sort": { "type": "string", "example": "wait_until_asc" }, "requestedLimit": { "type": "number", "example": 180 }, "effectiveLimit": { "type": "number", "description": "How many this call was allowed to move after the daily guardrail was applied.", "example": 180 }, "matchedCount": { "type": "number", "description": "Movable enrollments parked on fromNodeId when the request started.", "example": 4320 }, "movedCount": { "type": "number", "example": 180 }, "remainingCount": { "type": "number", "description": "Movable enrollments still on fromNodeId. Repeat the same request while this is above zero.", "example": 4140 }, "skippedCount": { "type": "number", "description": "Enrollments excluded because they are active, a worker is mid-step on them, or they are parked awaiting double opt-in. Only safely parked waiting tokens can be moved.", "example": 0 }, "dailyLimit": { "type": [ "number", "null" ], "example": 500 }, "movedInWindow": { "type": "number", "description": "Moves onto targetNodeId already recorded in the rolling 24-hour window.", "example": 0 }, "dailyRemaining": { "type": [ "number", "null" ], "example": 320 }, "enqueuedCount": { "type": "number", "description": "Moved enrollments handed to the worker queue. Zero while the sequence is not running.", "example": 180 }, "enqueueErrors": { "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "example": "tok_abc123" }, "error": { "type": "string", "example": "Redis connection lost" } } } }, "tagResult": { "type": [ "object", "null" ], "additionalProperties": true }, "enrollments": { "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "example": "tok_abc123" }, "subscriberId": { "type": "string", "example": "sub_abc123" }, "subscriberEmail": { "type": [ "string", "null" ], "example": "customer@example.com" }, "status": { "type": "string", "example": "waiting" }, "enrollmentKey": { "type": "string", "example": "__default__" } } } }, "hasMore": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Moved 180 enrollments. 4140 still wait on the source step; repeat this request to release more." } } }, "SequenceEnrollmentCancelResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "sequenceId": { "type": "string", "example": "seq_abc123" }, "dryRun": { "type": "boolean", "example": false }, "target": { "type": "object", "additionalProperties": true }, "matchedCount": { "type": "number", "description": "Active or waiting enrollments matching the target when the request started.", "example": 2 }, "cancelledCount": { "type": "number", "description": "Enrollments cancelled by this request. Bulk cancellation is capped at 1000 per request.", "example": 2 }, "remainingCount": { "type": "number", "description": "Enrollments still matching the target after this request. Repeat the same request while this is above zero.", "example": 0 }, "enrollments": { "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "example": "tok_abc123" }, "subscriberId": { "type": "string", "example": "sub_abc123" }, "subscriberEmail": { "type": [ "string", "null" ], "example": "customer@example.com" }, "status": { "type": "string", "example": "cancelled" }, "enrollmentKey": { "type": "string", "example": "event:ecommerce.order_placed:field:order.id:ord_123" } } } }, "hasMore": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Cancelled 2 sequence enrollments." } } }, "SequenceEnrollmentRealignRequest": { "type": "object", "description": "All fields are optional. With no body, every waiting enrollment in the sequence is previewed.", "properties": { "nodeIds": { "type": "array", "description": "Step IDs to limit realignment to. Defaults to every step.", "minItems": 1, "items": { "type": "string" }, "example": [ "node_week_14" ] }, "subscriberIds": { "type": "array", "description": "Up to 500 subscriber IDs to limit realignment to. Defaults to every waiting contact.", "minItems": 1, "maxItems": 500, "items": { "type": "string" }, "example": [ "sub_abc123", "sub_def456" ] }, "cursor": { "type": "string", "description": "Opaque continuation cursor. When a response has hasMore true, pass its nextCursor here to continue after the enrollments already scanned." }, "dryRun": { "type": "boolean", "description": "When true (the default), returns the new wait times without writing them. Set false to apply.", "example": false } } }, "SequenceEnrollmentRealignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "sequenceId": { "type": "string", "example": "seq_abc123" }, "sequenceName": { "type": "string", "example": "52-Week Medicine Wheel" }, "dryRun": { "type": "boolean", "example": false }, "sendingWindow": { "type": [ "object", "null" ], "description": "The sequence sending window realignment anchored on, or null when only per-step weekday gates applied.", "additionalProperties": true }, "scannedCount": { "type": "number", "description": "Waiting enrollments inspected by this request.", "example": 330 }, "realignedCount": { "type": "number", "description": "Waiting enrollments moved earlier, or that would move on a dry run. Capped at 1000 per request.", "example": 330 }, "unchangedCount": { "type": "number", "example": 0 }, "unchangedReasons": { "type": "object", "description": "Counts per reason an enrollment did not move: already_at_window_start, already_due, day_not_allowed, no_shared_opening, no_window, not_email_bound, send_retry, raced.", "additionalProperties": { "type": "number" } }, "requeueFailedCount": { "type": "number", "description": "Enrollments whose new wait time was stored but whose wake-up could not be re-queued. The stuck-enrollment sweeper recovers these within a few minutes.", "example": 0 }, "changes": { "type": "array", "description": "Sample of up to 50 realigned enrollments.", "items": { "type": "object", "properties": { "enrollmentId": { "type": "string", "example": "tok_abc123" }, "subscriberId": { "type": "string", "example": "sub_abc123" }, "subscriberEmail": { "type": [ "string", "null" ], "example": "customer@example.com" }, "currentNodeId": { "type": "string", "example": "node_week_14" }, "waitUntil": { "type": "string", "format": "date-time", "example": "2026-08-16T18:13:00.000Z" }, "newWaitUntil": { "type": "string", "format": "date-time", "example": "2026-08-16T15:00:00.000Z" }, "movedEarlierMinutes": { "type": "number", "example": 193 } } } }, "hasMore": { "type": "boolean", "description": "True when a per-request cap stopped the scan early. Continue with nextCursor while this is true.", "example": false }, "nextCursor": { "type": "string", "description": "Opaque continuation cursor to pass as cursor on the next request when hasMore is true." }, "maxRealignmentsPerRequest": { "type": "number", "example": 1000 }, "message": { "type": "string", "example": "Realigned 330 waiting enrollments to the sending-window opening on the day they were already scheduled for." } } }, "SequenceEnrollmentRealignQueuedResponse": { "type": "object", "required": [ "success", "sequenceId", "dryRun", "status", "jobId", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "sequenceId": { "type": "string", "example": "seq_abc123" }, "sequenceName": { "type": "string", "example": "52-Week Medicine Wheel" }, "dryRun": { "type": "boolean", "enum": [ false ] }, "status": { "type": "string", "enum": [ "queued" ] }, "jobId": { "type": "string", "example": "realign-sequence-enrollments-seq_abc123-550e8400-e29b-41d4-a716-446655440000" }, "message": { "type": "string" } } }, "SequenceEnrollmentRealignJobResponse": { "type": "object", "required": [ "success", "sequenceId", "dryRun", "status", "jobId", "result", "error", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "sequenceId": { "type": "string", "example": "seq_abc123" }, "sequenceName": { "type": "string", "example": "52-Week Medicine Wheel" }, "dryRun": { "type": "boolean", "enum": [ false ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "jobId": { "type": "string" }, "result": { "type": [ "object", "null" ], "description": "Completed realignment result; null while queued, running, or failed.", "additionalProperties": true }, "error": { "type": [ "string", "null" ] }, "message": { "type": "string" } } }, "SequenceEnrollmentListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "sequenceId": { "type": "string", "example": "seq_abc123" }, "sequenceName": { "type": "string", "example": "Onboarding" }, "statuses": { "type": "array", "description": "Enrollment statuses included in this response.", "items": { "type": "string" }, "example": [ "active", "waiting" ] }, "stopCondition": { "$ref": "#/components/schemas/SequenceStopCondition", "description": "The sequence's single configured stop condition, including any matchConfig event-property filters or field comparison. A sequence holds exactly one, so a stop event with any other name never applies. It is re-evaluated when an enrollment next runs a step, not when its event arrives." }, "stopConditionMatchEvaluatedCount": { "type": "integer", "description": "How many enrollments in this page were actually evaluated for a current stop-condition match. 0 when stopConditionMatch was not requested, the sequence has no stop condition, or no returned enrollment was still active or waiting.", "example": 1 }, "enrollments": { "type": "array", "items": { "type": "object", "properties": { "enrollmentId": { "type": "string", "description": "Enrollment token ID. Stable identifier for this one run through the sequence.", "example": "tok_abc123" }, "sequenceId": { "type": "string", "example": "seq_abc123" }, "subscriberId": { "type": "string", "example": "sub_abc123" }, "email": { "type": [ "string", "null" ], "description": "Subscriber email address. Falls back to the address captured at enrollment when the subscriber record no longer exists.", "example": "customer@example.com" }, "firstName": { "type": [ "string", "null" ], "example": "Wanda" }, "lastName": { "type": [ "string", "null" ], "example": "Waiter" }, "subscriberStatus": { "type": [ "string", "null" ], "example": "active" }, "status": { "type": "string", "enum": [ "active", "waiting", "completed", "failed", "cancelled" ], "example": "waiting" }, "currentNodeId": { "type": "string", "description": "Sequence node this enrollment is currently sitting on.", "example": "node_wave_1" }, "currentNodeType": { "type": "string", "description": "Omitted when the node no longer exists in the sequence graph.", "example": "logic_delay" }, "currentNodeLabel": { "type": "string", "description": "Node label or email subject when available.", "example": "Start at Wave 1" }, "currentNodeMissing": { "type": "boolean", "example": false }, "enrollmentKey": { "type": "string", "example": "__default__" }, "enrollmentStartedAt": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00.000Z" }, "waitUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "When a waiting enrollment is scheduled to resume, or null when nothing is scheduled.", "example": "2026-01-04T00:00:00.000Z" }, "lastUpdatedAt": { "type": "string", "format": "date-time", "description": "Last change to this enrollment. For a waiting enrollment this is when it arrived at its current node.", "example": "2026-01-01T00:00:00.000Z" }, "failedReason": { "type": [ "string", "null" ], "description": "Why this enrollment stopped, for status `failed`. Null for every other status and for failures recorded before this field existed. The same reason repeated across enrollments on one `currentNodeId` points at that step rather than at the contacts.", "example": "Automation seq_abc123 not found" }, "movedFromNodeId": { "type": [ "string", "null" ], "description": "Step this enrollment was released from by POST /sequences/{sequenceId}/enrollments/move, or null when it reached its current step on its own.", "example": "node_delay_2" }, "movedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When that release happened, or null when the enrollment was never moved.", "example": "2026-03-01T09:00:00.000Z" }, "moveReason": { "type": [ "string", "null" ], "description": "Note recorded with that release, or null when none was given.", "example": "Wave 3" }, "stopConditionMatches": { "type": [ "boolean", "null" ], "description": "Whether the sequence stop condition matches for this contact right now. Null when it was not determined - stopConditionMatch was not requested, the sequence has no stop condition, this enrollment is no longer active or waiting, or it fell outside the evaluated window. Null never means \"does not match\". This is a non-atomic snapshot; the worker re-checks before a future step, but the condition can change and a step already past its stop check may still finish.", "example": true }, "stopConditionMatchReason": { "type": [ "string", "null" ], "description": "Human-readable reason the stop condition matches. Null when stopConditionMatches is not true.", "example": "Subscriber received stop event: onboarding.completed" }, "enteredVia": { "type": "object", "description": "What put this contact into the sequence. The distinguishing detail when a trigger covers several lists or tags.", "properties": { "kind": { "type": "string", "enum": [ "list", "tag", "segment", "event", "inactivity", "frequency", "manual", "test_run", "unknown" ], "description": "`inactivity` and `frequency` identify time-based evaluation of the monitored event rather than an ordinary event-received enrollment. `manual` is a dashboard or API enrollment that bypassed the trigger. `unknown` covers enrollments recorded before this field existed.", "example": "list" }, "value": { "type": [ "string", "null" ], "description": "The list ID, tag name, segment ID, event name, or monitored event name. Null for `manual`, `test_run`, and `unknown`.", "example": "list_abc123" }, "name": { "type": [ "string", "null" ], "description": "Resolved list or segment name. Set for list and segment kinds, and null when the referenced resource has since been deleted.", "example": "Newsletter" }, "description": { "type": "string", "description": "Ready-to-display attribution line.", "example": "Added to list \"Newsletter\"" } } }, "entryContext": { "$ref": "#/components/schemas/SequenceEnrollmentEntryContext" }, "branchDecisions": { "type": "array", "description": "Bounded redacted if/else and random-split verdicts, oldest first within the retained window. Compared values are summaries (missing, empty, nonempty, equals_expected), never the raw field or event-property value. Empty on enrollments recorded before this field existed; use GET /sequences/{sequenceId}/enrollments/{enrollmentId} to reconstruct those from ClickHouse.", "items": { "$ref": "#/components/schemas/SequenceEnrollmentBranchDecision" } }, "branchDecisionCount": { "type": "integer", "minimum": 0, "description": "Total decisions taken, including decisions omitted from the bounded array." }, "branchDecisionsTruncated": { "type": "boolean", "description": "Whether older decisions were omitted from branchDecisions." } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "number", "example": 50 }, "offset": { "type": "number", "example": 0 }, "count": { "type": "number", "example": 1 }, "total": { "type": "number", "example": 1 }, "hasMore": { "type": "boolean", "example": false } } } } }, "SequenceEnrollmentEntryContext": { "type": "object", "description": "Event or manual-enrollment context captured at entry. Property keys only; values from the enrolling payload are never returned.", "properties": { "triggerType": { "type": [ "string", "null" ], "description": "Stored entryTriggerType, such as event_received or manual_enrollment. Null when never stamped.", "example": "event_received" }, "eventId": { "type": [ "string", "null" ], "description": "Durable ID of the enrolling event, or null.", "example": "evt_abc123" }, "eventName": { "type": [ "string", "null" ], "description": "Enrolling event name, or null.", "example": "producer.activation.needed" }, "hasEventProperties": { "type": "boolean", "description": "Whether any event property keys were stored on this enrollment." }, "eventPropertyKeys": { "type": "array", "description": "Keys present on the enrolling event payload. Values are omitted.", "items": { "type": "string" }, "example": [ "catalogueStage" ] }, "hasFieldSnapshots": { "type": "boolean", "description": "Whether subscriber field snapshots were stored at enrollment." }, "fieldSnapshotKeys": { "type": "array", "description": "Subscriber field paths snapshotted at enrollment. Values are omitted.", "items": { "type": "string" } } } }, "SequenceEnrollmentBranchDecision": { "type": "object", "description": "One if/else or random-split verdict. Compared values are summaries, never the raw recipient value.", "properties": { "nodeId": { "type": "string", "example": "node_branch" }, "decidedAt": { "type": "string", "format": "date-time" }, "splitMode": { "type": "string", "enum": [ "condition", "random" ] }, "selectedPath": { "type": "string", "enum": [ "matched", "else" ] }, "matchedBranchId": { "type": [ "string", "null" ] }, "matchedBranchIndex": { "type": "integer", "example": -1 }, "routedEdgeBranchId": { "type": [ "string", "null" ], "example": "else" }, "evaluations": { "type": "array", "items": { "type": "object", "properties": { "branchId": { "type": [ "string", "null" ] }, "branchIndex": { "type": "integer" }, "conditionType": { "type": [ "string", "null" ], "example": "field_equals" }, "fieldName": { "type": [ "string", "null" ], "example": "catalogueStage" }, "outcome": { "type": "string", "enum": [ "pass", "fail", "skip" ] }, "compared": { "type": [ "object", "null" ], "properties": { "present": { "type": "boolean" }, "summary": { "type": "string", "enum": [ "missing", "empty", "nonempty", "equals_expected" ] }, "kind": { "type": [ "string", "null" ], "enum": [ "string", "number", "boolean", "object", "array", "null", null ] } } }, "reason": { "type": "string", "description": "Human-readable, already redacted. Never includes the compared value.", "example": "Field catalogueStage not found on subscriber" } } } } } }, "SequenceEnrollmentGetResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "sequenceId": { "type": "string", "example": "seq_abc123" }, "sequenceName": { "type": "string", "example": "New Producer Activation" }, "stopCondition": { "$ref": "#/components/schemas/SequenceStopCondition" }, "enrollment": { "$ref": "#/components/schemas/SequenceEnrollmentListResponse/properties/enrollments/items", "description": "Same row shape as list sequence enrollments, including enteredVia, entryContext, and branchDecisions." }, "nodeHistory": { "type": "array", "description": "ClickHouse graph-walk events for this token, oldest first.", "items": { "type": "object", "properties": { "nodeId": { "type": "string" }, "nodeType": { "type": "string" }, "nodeLabel": { "type": "string" }, "eventType": { "type": "string", "example": "completed" }, "eventTime": { "type": "string", "format": "date-time" }, "branchDecision": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/SequenceEnrollmentBranchDecision" } ] }, { "type": "null" } ] } } } }, "nodeHistoryTruncated": { "type": "boolean", "description": "Whether additional node events exist beyond the returned bounded history." }, "nodeHistoryLimit": { "type": "integer", "minimum": 1, "description": "Maximum number of node events returned." }, "historySource": { "type": "string", "enum": [ "node_events", "token_context", "both", "none" ], "description": "Where the branch history came from." } } }, "OutboundWebhookEventType": { "type": "string", "enum": [ "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.failed", "email.complained", "email.opened", "email.clicked", "email.replied", "email.unsubscribed", "campaign.sent", "sms.sent", "sms.delivered", "sms.failed", "sms.opted_out", "subscriber.invalid", "subscriber.created", "subscriber.updated", "subscriber.unsubscribed", "subscriber.list_subscribed", "subscriber.list_unsubscribed", "subscriber_import.completed", "sequence.finished", "sequence.failed", "poll.answered" ] }, "NotificationPreference": { "type": "object", "required": [ "event", "mode" ], "properties": { "event": { "type": "string", "enum": [ "new_subscriber", "form_submitted", "campaign_completed", "weekly_report" ], "description": "Which notification to configure. weekly_report is the Monday summary of last week's sends, engagement, new subscribers, revenue, goals, and sequence trends; it is on by default for the workspace owner, off by default for invited members, and only sent for weeks with more than 10 emails sent." }, "mode": { "type": "string", "enum": [ "off", "instant", "daily", "weekly" ], "description": "How to receive it. \"instant\" sends one email per occurrence, \"daily\" one summary per day, \"weekly\" one report per week. Instant form_submitted notifications stop after 50 per workspace per UTC day. \"daily\" is not supported for form_submitted or campaign_completed; weekly_report accepts only \"off\" or \"weekly\"." } } }, "NotificationPreferences": { "type": "object", "properties": { "success": { "type": "boolean" }, "notificationPreferences": { "type": "array", "description": "Every notification event available to this client with its current mode, defaults included. Node and Undici clients that omit x-sequenzy-client receive the three legacy events for compatibility.", "items": { "$ref": "#/components/schemas/NotificationPreference" } }, "supportedModes": { "type": "object", "description": "Modes each event accepts, keyed by event.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "defaults": { "type": "object", "description": "Mode each event uses when the user has never configured it, resolved for the API key's user. The workspace owner defaults to weekly_report \"weekly\"; invited members default to \"off\".", "additionalProperties": { "type": "string" } } } }, "OutboundWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "example": "webhook_abc123" }, "name": { "type": "string", "example": "Production webhook" }, "url": { "type": "string", "format": "uri", "example": "https://example.com/sequenzy/webhooks" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/OutboundWebhookEventType" } }, "consecutiveFailures": { "type": "integer", "description": "Consecutive failed delivery attempts used for endpoint backoff." }, "circuitOpenedAt": { "type": [ "string", "null" ], "format": "date-time" }, "circuitOpenUntil": { "type": [ "string", "null" ], "format": "date-time" }, "signingSecret": { "type": "string", "description": "Returned only when creating a webhook or adding a signing secret.", "example": "whsec_..." }, "signingSecrets": { "type": "array", "description": "Active signing secret metadata. Secret values are returned only once.", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "sec_abc123" }, "prefix": { "type": "string", "example": "whsec_abcd12" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastFailureAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OutboundWebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "$ref": "#/components/schemas/OutboundWebhookEventType" }, "status": { "type": "string", "enum": [ "pending", "delivering", "succeeded", "failed", "skipped" ] }, "attempts": { "type": "integer" }, "queuedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastStatusCode": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "lastResponseBody": { "type": [ "string", "null" ] }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OutboundWebhookDeliveryAttempt": { "type": "object", "properties": { "id": { "type": "string" }, "attemptNumber": { "type": "integer" }, "status": { "type": "string", "enum": [ "succeeded", "failed" ] }, "statusCode": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "responseBody": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "TeamMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Member or invitation ID. The owner entry uses the literal id \"owner\".", "example": "member_abc123" }, "kind": { "type": "string", "enum": [ "owner", "member", "invitation" ] }, "userId": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "marketer", "viewer", "restricted" ] }, "canManageBilling": { "type": "boolean" }, "user": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": "string", "format": "email" }, "image": { "type": [ "string", "null" ] } } }, "status": { "type": "string", "enum": [ "joined", "pending", "expired" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "invitedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "invitedBy": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": "string", "format": "email" } } } } }, "ConversationSummary": { "type": "object", "properties": { "id": { "type": "string", "example": "conv_abc123" }, "subscriberId": { "type": [ "string", "null" ] }, "subscriberEmail": { "type": "string", "format": "email" }, "subscriberName": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "messageCount": { "type": "integer" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "lastMessageBy": { "type": "string", "example": "subscriber" }, "hasUnread": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lastMessagePreview": { "type": [ "object", "null" ], "description": "Plain-text preview of the latest subscriber or team reply, with quoted history, signatures and markup removed and truncated to 200 characters. Internal notes are not included. Null when no reply has readable text.", "properties": { "type": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "`inbound` for a subscriber reply, `outbound` for a team reply." }, "text": { "type": "string", "example": "Thanks, Thursday works for me." } }, "required": [ "type", "text" ] }, "context": { "type": "object", "properties": { "type": { "type": "string", "description": "Originating email type (campaign, sequence, transactional, or unknown).", "example": "campaign" }, "label": { "type": [ "string", "null" ], "description": "Campaign or sequence name." } } } } }, "ConversationMessage": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_abc123" }, "conversationId": { "type": "string" }, "type": { "type": "string", "enum": [ "inbound", "outbound", "note" ] }, "subject": { "type": [ "string", "null" ] }, "bodyText": { "type": [ "string", "null" ] }, "bodyHtml": { "type": [ "string", "null" ] }, "fromEmail": { "type": [ "string", "null" ] }, "fromName": { "type": [ "string", "null" ] }, "fromUserId": { "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "isRead": { "type": "boolean" }, "deliveryStatus": { "type": [ "string", "null" ], "description": "pending, sent, or failed for outbound messages. Null for notes." }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "paths": { "/subscribers/operations": { "post": { "summary": "Start a subscriber operation", "operationId": "startSubscriberOperation", "tags": [ "Subscribers" ], "description": "Requires subscribers:read. Tagging and cancelling a tagging task also require subscribers:tag; creating tag definitions requires tags:write; triggering automations requires automations:trigger. Personal keys retain current company role restrictions. Company keys retain company-scoped authority. Workers recheck authority on every page. Returns immediately with a durable ID. Retry the same requestKey after an uncertain response. Active tasks have a seven-day processing deadline. Completed/failed/cancelled records are retained seven days. Inspect failures before retrying interrupted tagging; an uncertain action is never automatically replayed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberOperationStart" } } } }, "responses": { "202": { "description": "Operation accepted or existing operation replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberOperationResponse" } } } }, "400": { "description": "Invalid tagging input. `error` summarizes the failing fields, and `issues` lists their paths with the accepted values for fixed choices such as `kind`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or company role is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Operation does not exist in this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request key conflict or cancellation race", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Operation could not be created; retry with the same request key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List subscriber operations", "operationId": "listSubscriberOperations", "tags": [ "Subscribers" ], "description": "Returns up to twenty recent retained operations for the company. Requires subscribers:read. Tagging and cancelling a tagging task also require subscribers:tag; creating tag definitions requires tags:write; triggering automations requires automations:trigger. Personal keys retain current company role restrictions. Company keys retain company-scoped authority. Workers recheck authority on every page.", "responses": { "200": { "description": "Recent operations", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "operations" ], "properties": { "success": { "type": "boolean" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberOperation" } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or company role is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/operations/{id}": { "get": { "summary": "Get a subscriber operation", "operationId": "getSubscriberOperation", "tags": [ "Subscribers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Requires subscribers:read. Tagging and cancelling a tagging task also require subscribers:tag; creating tag definitions requires tags:write; triggering automations requires automations:trigger. Personal keys retain current company role restrictions. Company keys retain company-scoped authority. Workers recheck authority on every page.", "responses": { "200": { "description": "Current progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberOperationResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or company role is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Operation does not exist in this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/operations/{id}/cancel": { "post": { "summary": "Cancel a subscriber operation", "operationId": "cancelSubscriberOperation", "tags": [ "Subscribers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Requires subscribers:read. Tagging and cancelling a tagging task also require subscribers:tag; creating tag definitions requires tags:write; triggering automations requires automations:trigger. Personal keys retain current company role restrictions. Company keys retain company-scoped authority. Workers recheck authority on every page. Cancellation stops future pages and keeps applied tags. An action already in flight may finish; its contact is reported as uncertain. Terminal cancellation is idempotent.", "responses": { "200": { "description": "Cancelled or already terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberOperationResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope or company role is missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Operation does not exist in this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request key conflict or cancellation race", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/email-blocks/line-items/assist": { "post": { "summary": "Preview cart items and suggest mappings", "operationId": "previewCartItems", "tags": [ "Email Blocks" ], "description": "Requires authentication, accepts existing restricted keys, and operates only on supplied data. Does not save or send. Safe to retry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 50, "default": [], "items": { "type": "object", "additionalProperties": true } }, "itemFields": { "type": "object", "description": "Existing relative dotted paths. Blank values use defaults; unsafe prototype paths are rejected. Suggestions do not replace existing mappings.", "properties": { "title": { "type": "string", "maxLength": 200 }, "variantTitle": { "type": "string", "maxLength": 200 }, "quantity": { "type": "string", "maxLength": 200 }, "priceCents": { "type": "string", "maxLength": 200 }, "price": { "type": "string", "maxLength": 200 }, "imageUrl": { "type": "string", "maxLength": 200 }, "url": { "type": "string", "maxLength": 200 }, "currency": { "type": "string", "maxLength": 200 } } }, "scenario": { "type": "string", "enum": [ "real", "one", "many", "empty", "missing-images", "long-names" ], "default": "real", "description": "Many returns 12 cloned rows; nonempty sample scenarios use a sample product if items are empty. Real preserves supplied items." }, "priceUnit": { "type": "string", "enum": [ "minor", "major" ], "default": "minor", "description": "Numeric item prices use cents or explicit major units. The separate total remains in cents." } } } } } }, "responses": { "200": { "description": "Mapping suggestions, isolated preview data and design presets. No persistent changes.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "suggestions", "priceCandidates", "previewItems", "scenario", "isSample", "presets" ], "properties": { "success": { "type": "boolean", "const": true }, "suggestions": { "type": "array", "items": { "type": "object", "required": [ "field", "path", "example" ], "properties": { "field": { "type": "string" }, "path": { "type": "string" }, "example": { "type": "string" } } } }, "priceCandidates": { "type": "array", "description": "Numeric prices requiring explicit unit selection.", "items": { "type": "object", "required": [ "path", "example", "units" ], "properties": { "path": { "type": "string" }, "example": { "type": "string" }, "units": { "type": "string", "const": "unknown" } } } }, "previewItems": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "scenario": { "type": "string", "enum": [ "real", "one", "many", "empty", "missing-images", "long-names" ] }, "isSample": { "type": "boolean", "description": "True for every scenario except real." }, "presets": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "description", "settings" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "settings": { "type": "object", "properties": { "imageSize": { "type": "integer", "minimum": 32, "maximum": 120 }, "rowSpacing": { "type": "integer", "minimum": 0, "maximum": 32 }, "fontSize": { "type": "integer", "minimum": 12, "maximum": 24 }, "imageFit": { "type": "string", "enum": [ "cover", "contain" ] } } } } } } } } } } }, "400": { "description": "Invalid items, mappings, scenario or price units. Returns success false, error and validation details." }, "401": { "description": "Missing or invalid authentication." }, "403": { "description": "Authentication access restriction." } } } }, "/email-blocks": { "get": { "summary": "List email block types", "description": "Lists every block type accepted by the `blocks` array on campaigns, sequence email steps, templates, transactional emails, and email components, with the required and optional fields of each. Derived from the same schemas that validate a write, so it cannot drift from what those endpoints accept.", "operationId": "listEmailBlockTypes", "tags": [ "Email Blocks" ], "parameters": [ { "name": "creatableOnly", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Hide structural block types the editor manages for you." } ], "responses": { "200": { "description": "Block types listed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "blockTypes": { "type": "array", "items": { "$ref": "#/components/schemas/EmailBlockTypeReference" } }, "conditionFields": { "type": "array", "description": "The per-field table for block conditions, always returned with the list. This is the call made to find out what exists, and the table adds about 9% to it.", "items": { "$ref": "#/components/schemas/EmailBlockConditionFieldReference" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/email-blocks/{type}": { "get": { "summary": "Get email block type", "description": "Returns the full field reference for one block type, with a minimal valid example and authoring notes. For line-items, includes optional itemFields mappings from display fields to relative dotted paths within each item. Omitted or blank mappings use standard field names. Mapping values must be strings of at most 200 characters.", "operationId": "getEmailBlockType", "tags": [ "Email Blocks" ], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Block type, for example list, steps, text, or hero.", "example": "steps" }, { "name": "conditionFields", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Include the per-field condition table in the response. Not needed for `conditional-group`, which always carries it. The table is several times the size of one block type's reference, so a targeted lookup does not carry it unless asked." } ], "responses": { "200": { "description": "Block type reference", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "blockType": { "$ref": "#/components/schemas/EmailBlockTypeReference" }, "conditionFields": { "type": "array", "description": "The per-field table for block conditions. Returned when `type` is `conditional-group`, or when `conditionFields=true` is passed.", "items": { "$ref": "#/components/schemas/EmailBlockConditionFieldReference" } }, "conditionFieldsHint": { "type": "string", "description": "Returned in place of `conditionFields` when the table was not included, saying that conditions are per-field and how to request the table.", "example": "Every block also takes a `conditions` array, and each condition field accepts only its own operators. Request this endpoint with ?conditionFields=true, or GET /email-blocks, for `conditionFields`: the operators, value format, and render-preview support of every condition field." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown block type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/email-components": { "get": { "summary": "List email components", "description": "Lists reusable email components newest first, including the components pinned as company defaults.", "operationId": "listEmailComponents", "tags": [ "Email Components" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "section", "footer" ] }, "description": "Filter by component type." }, { "name": "slot", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "footer" ] }, "description": "Filter by default slot." }, { "name": "defaultsOnly", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Return only components pinned as a company default." } ], "responses": { "200": { "description": "Components listed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/EmailComponent" } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "summary": "Create email component", "description": "Creates a reusable email component from a block list. Component names are unique per company.", "operationId": "createEmailComponent", "tags": [ "Email Components" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "blocks" ], "properties": { "name": { "type": "string", "example": "Promo banner" }, "description": { "type": [ "string", "null" ] }, "blocks": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/EmailBlock" } }, "componentType": { "type": "string", "enum": [ "section", "footer" ], "description": "Defaults to section. Creating a footer component does not pin it as the company default." } } } } } }, "responses": { "201": { "description": "Component created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "component": { "$ref": "#/components/schemas/EmailComponent" }, "warnings": { "$ref": "#/components/schemas/BlockFieldWarnings" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Component name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/email-components/defaults/{slot}/preview": { "post": { "summary": "Preview default footer application", "description": "Read-only affected counts and optional layout HTML. Requires the same write scopes and admin role as applying. No subscriber-specific personalization or sending.", "operationId": "previewDefaultEmailComponent", "tags": [ "Email Components" ], "parameters": [ { "name": "slot", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "footer" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blocks", "application" ], "properties": { "blocks": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/EmailBlock" } }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "application": { "$ref": "#/components/schemas/FooterApplicationOptions" }, "renderPreview": { "type": "boolean", "default": false }, "sample": { "type": "object", "required": [ "id", "kind" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "email", "ab_variant", "localization" ] } } } } } } } }, "responses": { "200": { "description": "Preview created without writes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "application": { "$ref": "#/components/schemas/FooterApplicationPreview" }, "renderedPreview": { "$ref": "#/components/schemas/FooterRenderedPreview" }, "warnings": { "$ref": "#/components/schemas/BlockFieldWarnings" } } } } } }, "400": { "description": "Invalid blocks or unsupported slot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing application permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Component name conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request shape validation failed (missing fields or invalid option types)" }, "500": { "description": "Preview failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/email-components/defaults/{slot}": { "get": { "summary": "Get default email component", "description": "Returns the component used as the company default for a slot. A 404 means emails fall back to the generated footer.", "operationId": "getDefaultEmailComponent", "tags": [ "Email Components" ], "parameters": [ { "name": "slot", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "footer" ] } } ], "responses": { "200": { "description": "Default component returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "component": { "$ref": "#/components/schemas/EmailComponent" } } } } } }, "400": { "description": "Unsupported slot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No default component set for this slot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "put": { "summary": "Set default email component", "description": "Creates or replaces the company default component for a slot. New sequence, campaign, and AI-generated emails clone this component when they are built. A default footer always keeps its unsubscribe link enabled; transactional sends hide it at render time. Emails that already exist keep their footer unless application options and a valid previewToken are provided. Preview first to review selected scopes. Personal keys require admin access; keys need emails:write, each selected category write scope, and ab_tests:write for campaigns or sequences.", "operationId": "setDefaultEmailComponent", "tags": [ "Email Components" ], "parameters": [ { "name": "slot", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "footer" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blocks" ], "properties": { "blocks": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/EmailBlock" } }, "name": { "type": "string", "description": "Defaults to \"Default Footer\" when creating the footer default." }, "description": { "type": [ "string", "null" ] }, "application": { "$ref": "#/components/schemas/FooterApplicationOptions" }, "previewToken": { "type": "string", "description": "Required for applying a preview to existing content." } } } } } }, "responses": { "200": { "description": "Default component saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "component": { "$ref": "#/components/schemas/EmailComponent" }, "application": { "$ref": "#/components/schemas/FooterApplicationPreview" }, "warnings": { "$ref": "#/components/schemas/BlockFieldWarnings" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing application permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Component name already exists or preview is stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request shape validation failed (missing fields or invalid option types)" }, "500": { "description": "Application failed without partial writes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/email-components/{componentId}": { "get": { "summary": "Get email component", "description": "Returns a single email component by id.", "operationId": "getEmailComponent", "tags": [ "Email Components" ], "parameters": [ { "name": "componentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Component returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "component": { "$ref": "#/components/schemas/EmailComponent" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Component not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "summary": "Update email component", "description": "Updates component metadata or replaces its blocks. Replacing blocks bumps the component version; emails built earlier keep the copy they were created with. Editing the component pinned as the default footer keeps its unsubscribe link enabled.", "operationId": "updateEmailComponent", "tags": [ "Email Components" ], "parameters": [ { "name": "componentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "blocks": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/EmailBlock" } }, "componentType": { "type": "string", "enum": [ "section", "footer" ] } } } } } }, "responses": { "200": { "description": "Component updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "component": { "$ref": "#/components/schemas/EmailComponent" }, "warnings": { "$ref": "#/components/schemas/BlockFieldWarnings" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Component not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Component name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete email component", "description": "Deletes an email component. Emails that already rendered it keep their copied blocks. Deleting the pinned default footer makes new emails fall back to the generated footer.", "operationId": "deleteEmailComponent", "tags": [ "Email Components" ], "parameters": [ { "name": "componentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Component deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "cmp_123" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Component not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/emails": { "post": { "summary": "Create email", "description": "Creates an email template with block content. Raw HTML is stored as a native HTML body.", "operationId": "createEmail", "tags": [ "Emails" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EmailBodyInput" }, { "type": "object", "required": [ "name", "subject" ], "properties": { "name": { "type": "string", "example": "Welcome email" }, "subject": { "type": "string", "example": "Welcome" }, "previewText": { "type": [ "string", "null" ], "example": "Here's what to do next" } } } ] } } } }, "responses": { "201": { "description": "Email created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "email": { "$ref": "#/components/schemas/Email" }, "warnings": { "$ref": "#/components/schemas/BlockFieldWarnings" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/emails/{emailId}": { "patch": { "summary": "Update email", "description": "Updates email metadata or replaces the email body.", "operationId": "updateEmail", "tags": [ "Emails" ], "parameters": [ { "name": "emailId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EmailBodyInput" }, { "type": "object", "properties": { "name": { "type": "string" }, "subject": { "type": "string" }, "previewText": { "type": [ "string", "null" ] } } } ] } } } }, "responses": { "200": { "description": "Email updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "email": { "$ref": "#/components/schemas/Email" }, "warnings": { "$ref": "#/components/schemas/BlockFieldWarnings" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/emails/{emailId}/blocks": { "patch": { "summary": "Update email blocks", "description": "Replaces an email body or mutates an existing block type.", "operationId": "updateEmailBlocks", "tags": [ "Emails" ], "parameters": [ { "name": "emailId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EmailBodyInput" }, { "type": "object", "properties": { "blockId": { "type": "string", "description": "Existing block ID to mutate." }, "type": { "type": "string", "description": "New block type. Type mutation supports text and html.", "enum": [ "text", "html" ] }, "content": { "type": "string", "description": "Optional replacement content for the mutated block." } } } ] } } } }, "responses": { "200": { "description": "Email blocks updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "email": { "$ref": "#/components/schemas/Email" }, "warnings": { "$ref": "#/components/schemas/BlockFieldWarnings" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email or block not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/email-sends": { "get": { "summary": "List sent emails", "description": "Lists the recent 14-day delivery history with dashboard-equivalent subject, recipient, status, type, bounce, source, pagination, and sorting filters. Pending, successful, and failed test sends are listed with `isTestEmail` set to true. Copied-recipient bookkeeping rows remain hidden except bounced or complained copied recipients.", "operationId": "listEmailSends", "tags": [ "Email Sends" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive subject/title or recipient search. `q` is accepted as an alias." }, { "name": "q", "in": "query", "deprecated": true, "schema": { "type": "string" }, "description": "Compatibility alias for `search`." }, { "name": "subject", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive subject/title filter. `title` is accepted as an alias." }, { "name": "title", "in": "query", "deprecated": true, "schema": { "type": "string" }, "description": "Compatibility alias for `subject`." }, { "name": "recipient", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive recipient email filter." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "sent", "delivered", "opened", "clicked", "bounced", "complained", "failed", "suppressed" ] }, "description": "Delivery status. Opened includes clicked deliveries." }, { "name": "emailType", "in": "query", "schema": { "type": "string", "enum": [ "campaign", "transactional", "sequence" ] } }, { "name": "bounceType", "in": "query", "schema": { "type": "string", "enum": [ "Permanent", "Transient" ] } }, { "name": "campaignId", "in": "query", "schema": { "type": "string" } }, { "name": "transactionalEmailId", "in": "query", "schema": { "type": "string" } }, { "name": "automationId", "in": "query", "schema": { "type": "string" } }, { "name": "automationNodeId", "in": "query", "schema": { "type": "string" }, "description": "Filter to one email step of a sequence. Take the node ID from the `steps` array of the sequence metrics endpoint. Combined with `automationId` the two intersect." }, { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 14, "default": 14 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "sortField", "in": "query", "schema": { "type": "string", "enum": [ "recipientEmail", "subject", "status", "eventAt", "sentAt", "createdAt" ], "default": "createdAt" } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Paginated sent-email history", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "retentionDays": { "type": "integer", "example": 14 }, "emailSends": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/EmailSend" }, { "type": "object", "properties": { "eventAt": { "type": "string", "format": "date-time" }, "opened": { "type": "boolean" }, "clicked": { "type": "boolean" } } } ] } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid filter or pagination value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/email-sends/{emailSendId}": { "get": { "summary": "Get email send", "description": "Gets an email delivery snapshot by ID, including queued and test sends, the stored HTML body when available, and retained ClickHouse events when the short-lived row has been cleaned up. Test sends appear in sent-email history and are available through this exact-ID endpoint while their row is retained.", "operationId": "getEmailSend", "tags": [ "Email Sends" ], "parameters": [ { "name": "emailSendId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email send ID" } ], "responses": { "200": { "description": "Email send found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "source": { "type": "string", "enum": [ "database", "clickhouse_events" ] }, "message": { "type": [ "string", "null" ] }, "emailSend": { "$ref": "#/components/schemas/EmailSend" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EmailSendEvent" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email send not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/suppressions": { "get": { "summary": "List suppressed recipients", "description": "Lists the recipients this company cannot reach, newest suppression first by default.\n\nFour product-level suppression types appear:\n\n- `suppressionType: invalid_recipient` - SMTP evidence conclusively identifies an invalid destination. It is global, visible to companies associated with the address, and protected.\n- `suppressionType: unknown_hard_bounce` - a permanent/undetermined failure without enough evidence to declare the inbox invalid. It is company-scoped and protected.\n- `suppressionType: soft_bounce_escalation` - repeated delivery failures from this company. It is company-scoped and removable.\n- `suppressionType: complaint` - the recipient reported this company's email as spam. It is company-scoped and protected.\n\nThe platform-wide list is never exposed: a global row is returned only when the address is already associated with the authenticated company.\n", "operationId": "listRecipientSuppressions", "tags": [ "Suppressions" ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Case-insensitive substring filter on the recipient email address." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "1-based page number." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 }, "description": "Entries per page (max 100)." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "suppressedAt", "email", "status" ], "default": "suppressedAt" }, "description": "Field to order by. `status` lists removable workspace escalations before protected\nsuppressions. An unrecognized value falls back to `suppressedAt` rather than failing the\nrequest - read `sortBy` in the response to confirm what was applied.\n" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort direction. Defaults to `desc` for `suppressedAt` and `status`, `asc` for `email`.\n" } ], "responses": { "200": { "description": "Suppressed recipients", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "suppressions": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "suppressionType": { "type": "string", "enum": [ "invalid_recipient", "unknown_hard_bounce", "soft_bounce_escalation", "complaint" ], "description": "Stable product-level classification independent of provider bounce sub-types." }, "reason": { "type": "string", "enum": [ "bounced", "complaint" ] }, "scope": { "type": "string", "enum": [ "global", "company" ], "description": "global blocks every workspace; company blocks only this one." }, "source": { "type": "string", "enum": [ "bounced_email", "email_send_complaint" ] }, "bounceType": { "type": [ "string", "null" ] }, "bounceSubType": { "type": [ "string", "null" ] }, "bounceCount": { "type": [ "integer", "null" ] }, "suppressedAt": { "type": "string", "format": "date-time" }, "delistable": { "type": "boolean", "description": "True only for company-scoped soft-bounce escalations." } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "sortBy": { "type": "string", "enum": [ "suppressedAt", "email", "status" ], "description": "The sort field actually applied." }, "sortOrder": { "type": "string", "enum": [ "asc", "desc" ], "description": "The sort direction actually applied." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/suppressions/{email}": { "get": { "summary": "Get recipient suppression", "description": "Checks one exact recipient against Sequenzy's bounce and complaint safeguards. Sequenzy suppresses solely from its own bounce records; the email provider's account-level suppression list is not consulted. The lookup does not expose unrelated recipients.", "operationId": "getRecipientSuppression", "tags": [ "Suppressions" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" }, "description": "Exact recipient email address" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "example": "us-east-1" }, "description": "Deprecated: accepted and ignored. It previously limited a provider-side suppression lookup, which no longer happens." } ], "responses": { "200": { "description": "Recipient suppression status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "suppression": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "knownRecipient": { "type": "boolean" }, "suppressed": { "type": "boolean" }, "local": { "type": "object", "properties": { "suppressed": { "type": "boolean" }, "suppressionType": { "type": [ "string", "null" ], "enum": [ "invalid_recipient", "unknown_hard_bounce", "soft_bounce_escalation", "complaint", null ], "description": "Stable product-level classification. Null when no typed local suppression row exists." }, "reason": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "suppressionId": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ], "enum": [ "global", "company", null ], "description": "global when the block applies platform-wide, company when it is contained to this workspace. Null when the recipient is not locally suppressed." }, "delistable": { "type": "boolean", "description": "True only for a company-scoped soft-bounce escalation." } } }, "ses": { "type": "object", "properties": { "regionsChecked": { "type": "array", "items": { "type": "string" } }, "entries": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "region": { "type": "string" }, "reason": { "type": "string", "enum": [ "BOUNCE", "COMPLAINT" ] }, "lastUpdateTime": { "type": [ "string", "null" ], "format": "date-time" }, "messageId": { "type": [ "string", "null" ] }, "feedbackId": { "type": [ "string", "null" ] } } } } } } } } } } } } }, "400": { "description": "Invalid email address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "delete": { "summary": "Remove a workspace soft-bounce escalation", "description": "Removes one company-associated recipient's workspace-scoped soft-bounce escalation and reactivates a bounced company subscriber. Global invalid-recipient suppressions, other companies' scoped rows, complaints, and unsubscribes are protected.", "operationId": "removeRecipientSuppression", "tags": [ "Suppressions" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" }, "description": "Exact company-associated recipient email address" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "example": "us-east-1" }, "description": "Deprecated: accepted and ignored. It previously limited a provider-side suppression lookup, which no longer happens." } ], "responses": { "200": { "description": "Suppression cleanup result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "email": { "type": "string", "format": "email" }, "removed": { "type": "boolean" }, "removedLocalBounce": { "type": "boolean" }, "removedSesRegions": { "type": "array", "description": "Always empty. Sequenzy suppresses solely from its own bounce records and neither reads nor writes the email provider's suppression list. Retained for response compatibility.", "items": { "type": "string" } }, "reactivatedSubscriberIds": { "type": "array", "items": { "type": "string" } }, "remainingSuppression": { "type": "object", "description": "Recipient suppression status after cleanup" } } } } } }, "400": { "description": "Invalid email address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recipient is not associated with the selected company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The matching suppression is global, provider-level, complaint-based, or otherwise protected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/subscribers": { "get": { "summary": "List subscribers", "description": "Lists subscribers with stable pagination and optional filtering by status, free-text query, tags, list, segment, attribute, or email. Non-attribute results are ordered by createdAt descending with subscriber ID as a deterministic tie-breaker. Attribute-filtered results use ClickHouse-first cursor pagination ordered by subscriber ID ascending and do not include a total count.\n\n**Pulling a full audience:** every response includes `pagination.nextCursor` and `pagination.hasMore`. Follow `nextCursor` rather than incrementing `page`. Cursor pagination keeps results stable while subscribers are being created or deleted mid-pull (page numbers can skip or repeat rows as the underlying set shifts) and skips the total-count query, so `pagination.total` and `pagination.totalPages` are `null` on cursor requests. Combined with `limit=1000`, a 10,000-subscriber export takes ten requests instead of a hundred.\n", "operationId": "listSubscribers", "tags": [ "Subscribers" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number. Cannot be combined with `cursor`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 1000 }, "description": "Number of items per page (max 1000)" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned as pagination.nextCursor. Cannot be combined with `page`. Attribute-filtered requests return their own cursor, which is not interchangeable with the default-ordering cursor." }, { "name": "includeTotal", "in": "query", "schema": { "type": "string", "enum": [ "false" ] }, "description": "Pass `false` to skip the total-count query on page-numbered requests. Cursor requests always skip it." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "unsubscribed", "bounced", "all" ] }, "description": "Filter by subscriber status. Use all to disable status filtering." }, { "name": "query", "in": "query", "schema": { "type": "string" }, "description": "Free-text search across email, first name, last name, and tags" }, { "name": "email", "in": "query", "schema": { "type": "string" }, "description": "Legacy alias for a partial email search" }, { "name": "tags", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated tag names. Subscribers must have all provided tags." }, { "name": "attribute", "in": "query", "schema": { "type": "string" }, "description": "Custom attribute filter using attributeName:value syntax, such as plan:pro or mrr:50." }, { "name": "attributeOperator", "in": "query", "schema": { "type": "string", "enum": [ "is", "contains", "gt", "gte", "lt", "lte", "is_not_empty" ], "default": "is" }, "description": "Attribute filter operator for direct cursor pagination. Use saved segments for exclusion operators such as is_not, not_contains, or is_empty." }, { "name": "list", "in": "query", "schema": { "type": "string" }, "description": "Subscriber list ID or exact list name. The API tries ID first, then exact name." }, { "name": "listId", "in": "query", "schema": { "type": "string" }, "description": "Filter by subscriber list ID." }, { "name": "listName", "in": "query", "schema": { "type": "string" }, "description": "Filter by exact subscriber list name when the list ID is not known." }, { "name": "segmentId", "in": "query", "schema": { "type": "string" }, "description": "Filter by an existing segment ID" }, { "name": "unsubscribedAfter", "in": "query", "schema": { "type": "string" }, "description": "Only return contacts whose `unsubscribedAt` is on or after this ISO 8601 date or datetime. Bare dates use UTC midnight; datetimes must include `Z` or an explicit offset. Contacts with no recorded opt-out date are excluded.", "example": "2026-07-01" }, { "name": "unsubscribedBefore", "in": "query", "schema": { "type": "string" }, "description": "Only return contacts whose `unsubscribedAt` is on or before this ISO 8601 date or datetime. Bare dates use UTC midnight; datetimes must include `Z` or an explicit offset. Combine with `unsubscribedAfter` to audit a window of opt-outs.", "example": "2026-08-01" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "subscribers": { "type": "array", "items": { "$ref": "#/components/schemas/Subscriber" } }, "pagination": { "$ref": "#/components/schemas/SubscriberListPagination" } } } } } }, "400": { "description": "Invalid status filter, malformed cursor, or cursor combined with page. With segmentId, also returned when the segment's references exceed the segment reference limits (code SEGMENT_REFERENCE_DEPTH_EXCEEDED or SEGMENT_REFERENCE_COUNT_EXCEEDED, see Get segment count).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Segment or list not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "summary": "Create or update subscriber", "description": "Creates a new subscriber or handles existing ones based on the `duplicateStrategy` parameter.\n\nRequires `subscribers:write`, including when supplying a nonempty `lists` array. Explicit sequence enrollment and writes that can send a double opt-in confirmation require `automations:trigger`.\n\n**Duplicate Strategies:**\n- `skip` (default): Don't update existing subscribers\n- `merge`: Only fill in missing fields, never overwrite existing values\n- `overwrite`: Replace all fields (but never reactivate unsubscribed users)\n", "operationId": "createSubscriber", "tags": [ "Subscribers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Required when creating a new subscriber unless a phone is provided (which creates a phone-only SMS contact). Optional when externalId identifies an existing subscriber.", "example": "user@example.com" }, "externalId": { "type": "string", "description": "Customer-owned app/customer/user ID. Unique per company when provided.", "example": "user_123" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "timezone": { "type": [ "string", "null" ], "maxLength": 64, "description": "IANA timezone identifier (e.g. America/New_York) used for recipient-local campaign delivery. Invalid values fail with a 400 validation error; null clears the stored value.", "example": "America/New_York" }, "phone": { "type": [ "string", "null" ], "description": "Phone number in E.164 format or national format. Stored normalized to E.164. Invalid values fail with a 400 validation error. Does not affect SMS consent. With no email or externalId, creates or matches a phone-only (SMS) contact.", "example": "+15551234567" }, "phoneCountry": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country used to read a national-format phone, defaulting to US. A parsing hint only - the stored phoneCountry always comes from the parsed number. Sending it without phone fails with a 400 validation error.", "example": "IT" }, "smsConsent": { "type": "boolean", "description": "SMS marketing consent. true sets smsStatus to subscribed with consent source api, false sets unsubscribed, omitted leaves SMS status unchanged. Never inferred from phone presence." }, "status": { "type": "string", "enum": [ "active", "unsubscribed", "bounced" ], "default": "active", "description": "Initial subscriber status." }, "optInMode": { "type": "string", "enum": [ "default", "confirmed", "double_opt_in" ], "default": "default", "description": "Consent handling for this request:\n- `default`: obey the company double opt-in setting for new active subscribers; existing unsubscribed contacts are not sent confirmation email\n- `confirmed`: create or keep active immediately when you have verified consent\n- `double_opt_in`: send a confirmation email and keep the contact unsubscribed until they confirm\n" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "newsletter" ] }, "lists": { "type": "array", "items": { "type": "string" }, "description": "List IDs to add subscriber to, covered by subscribers:write. If not provided, a subscriber this call creates follows the workspace default lists setting and an existing subscriber keeps the memberships they already have, so an attribute-only upsert never changes list membership. If empty array, subscriber is added to NO lists.", "example": [ "list-id-1", "list-id-2" ] }, "customAttributes": { "type": "object", "additionalProperties": true, "example": { "plan": "free" } }, "enrollInSequences": { "type": "boolean", "description": "Whether to enroll the subscriber in matching sequences. Defaults to true for API calls, or to false when createdAt is supplied. Explicitly passing true requires the automations:trigger scope and returns 403 when that scope is missing." }, "createdAt": { "type": "string", "format": "date-time", "description": "Original signup date, for importing history from another platform. Preserves the real date so date-relative segments are correct immediately. An existing contact's date only ever moves earlier, regardless of duplicateStrategy. Supplying this defaults enrollInSequences to false, and updatedAt is never backdated. New-subscriber account notifications remain eligible when the signup date is at most one hour old; older dates do not notify on creation. Double opt-in confirmation can notify even for imported contacts. Your notification preferences, double opt-in and the daily cap still apply.", "example": "2019-03-14T09:30:00Z" }, "duplicateStrategy": { "type": "string", "enum": [ "skip", "merge", "overwrite" ], "default": "skip", "description": "How to handle existing subscribers:\n- `skip`: Don't update existing subscribers (default)\n- `merge`: Only fill in missing fields, never overwrite existing values\n- `overwrite`: Replace all fields (but never reactivate unsubscribed users)\n" } } } } } }, "responses": { "200": { "description": "Subscriber created or handled based on duplicate strategy", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "subscriber": { "allOf": [ { "$ref": "#/components/schemas/Subscriber" }, { "type": "object", "properties": { "created": { "type": "boolean", "description": "Whether the subscriber was newly created", "example": true }, "updated": { "type": "boolean", "description": "Whether the subscriber was updated (merge/overwrite strategies)", "example": false }, "skipped": { "type": "boolean", "description": "Whether the subscriber was skipped (skip strategy on existing)", "example": false } } } ] }, "optIn": { "type": "object", "description": "Present when the subscriber is awaiting double opt-in confirmation.", "properties": { "required": { "type": "boolean", "example": true }, "emailQueued": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "Validation error, for example an invalid phone number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing subscribers:write, or enrollment or double opt-in delivery requested without automations:trigger", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/imports": { "post": { "summary": "Create subscriber import", "operationId": "createSubscriberImport", "tags": [ "Subscribers" ], "description": "Queues an asynchronous full-record subscriber import of up to 5,000 contacts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subscribers" ], "properties": { "subscribers": { "type": "array", "minItems": 1, "maxItems": 5000, "items": { "$ref": "#/components/schemas/SubscriberImportRecord" } }, "duplicateStrategy": { "type": "string", "enum": [ "skip", "merge", "overwrite" ], "default": "skip" }, "fileName": { "type": "string", "maxLength": 255 }, "listIds": { "type": "array", "items": { "type": "string" } }, "enrollInSequences": { "type": "boolean", "default": false }, "defaultPhoneCountry": { "type": "string", "minLength": 2, "maxLength": 2 }, "smsConsent": { "type": "boolean" }, "optInMode": { "type": "string", "enum": [ "default", "confirmed", "double_opt_in" ], "default": "default" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Caller-owned key (1-255 characters, not blank) that makes retrying this request safe. The key is scoped to the request content - resending the same request returns the already-queued import with deduplicated true, while different content under the same key queues a new import. A blank key is rejected with 400." } } } } } }, "responses": { "200": { "description": "Idempotency key replay - the original import is returned and nothing new is queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "deduplicated": { "type": "boolean", "example": true }, "import": { "$ref": "#/components/schemas/SubscriberImport" }, "message": { "type": "string" } } } } } }, "202": { "description": "Import queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "deduplicated": { "type": "boolean", "description": "Present and true when this 202 response re-enqueued or reused the same logical keyed import rather than creating another import.", "example": true }, "import": { "$ref": "#/components/schemas/SubscriberImport" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid list or request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Import could not be queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Another request is still enqueueing this idempotent import. Retry the same request after the Retry-After delay.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying the same idempotency key." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "retryable": { "type": "boolean", "example": true }, "importId": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "/subscribers/imports/{importId}": { "get": { "summary": "Get subscriber import", "operationId": "getSubscriberImport", "tags": [ "Subscribers" ], "description": "Returns progress, counts, and failure summaries by import ID or batch ID. Every excluded row is explained - skippedReasons sums to skippedCount and failedReasons sums to failedCount. Status completed means row processing has finished; custom-attribute sync can still be pending, so attribute-based segment counts may take roughly 30–35 seconds or longer to reflect the updates.", "parameters": [ { "name": "importId", "in": "path", "required": true, "description": "Import ID or batch ID returned by the create endpoint.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Import status returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "import": { "$ref": "#/components/schemas/SubscriberImport" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscriber import not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/subscribers/external": { "get": { "summary": "Get subscriber by external ID", "description": "Retrieves a subscriber by their customer-owned external ID, including notes, list memberships, sequence enrollments, email stats, and recent activity.", "operationId": "getSubscriberByExternalId", "tags": [ "Subscribers" ], "parameters": [ { "name": "externalId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "External ID. Query form supports IDs containing slashes." }, { "name": "includeMachineEngagement", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include detected scanner, preview, and tracked asset open/click events in subscriber email stats and recent activity." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "subscriber": { "$ref": "#/components/schemas/DetailedSubscriber" } } } } } }, "400": { "description": "Missing external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "summary": "Update subscriber by external ID", "description": "Updates a subscriber's email, external ID, first name, last name, status, tags, or custom attributes.", "operationId": "updateSubscriberByExternalId", "tags": [ "Subscribers" ], "parameters": [ { "name": "externalId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "External ID. Query form supports IDs containing slashes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "New delivery email. Fails with 409 if another subscriber owns it." }, "externalId": { "x-fern-property-name": "newExternalId", "type": "string", "description": "New external ID. Fails with 409 if another subscriber owns it." }, "firstName": { "type": "string", "description": "Maximum 255 Unicode characters. Excess trailing ASCII spaces are accepted as by PostgreSQL. Longer names return 400 before any changes; correct the name before retrying. Omit to keep unchanged, or send an empty string to clear; null is not accepted." }, "lastName": { "type": "string", "description": "Maximum 255 Unicode characters. Excess trailing ASCII spaces are accepted as by PostgreSQL. Longer names return 400 before any changes; correct the name before retrying. Omit to keep unchanged, or send an empty string to clear; null is not accepted." }, "timezone": { "type": [ "string", "null" ], "maxLength": 64, "description": "IANA timezone identifier (e.g. America/New_York) used for recipient-local campaign delivery. Invalid values fail with a 400 validation error; null clears the stored value.", "example": "America/New_York" }, "phone": { "type": [ "string", "null" ], "description": "Phone number in E.164 format or national format. Stored normalized to E.164. Invalid values fail with a 400 validation error. Does not affect SMS consent. Changing it resets SMS consent unless smsConsent is sent in the same request. null or \"\" clears the phone, except on a phone-only (SMS) contact, where clearing its only identity fails with a 400 validation error.", "example": "+15551234567" }, "phoneCountry": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country used to read a national-format phone, defaulting to US. A parsing hint only - the stored phoneCountry always comes from the parsed number. Sending it without phone fails with a 400 validation error.", "example": "IT" }, "smsConsent": { "type": "boolean", "description": "SMS marketing consent. true sets smsStatus to subscribed with consent source api, false sets unsubscribed, omitted leaves SMS status unchanged. Never inferred from phone presence." }, "status": { "type": "string", "enum": [ "active", "unsubscribed", "bounced" ], "description": "Setting `unsubscribed` performs the unsubscribe workflow." }, "tags": { "type": "array", "items": { "type": "string" } }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Custom attributes to update. Defaults to replacing the existing public custom-attribute map." }, "customAttributesStrategy": { "type": "string", "enum": [ "replace", "merge" ], "default": "replace", "description": "How to apply customAttributes. replace replaces the existing public custom-attribute map. merge overwrites only provided keys and retains unspecified existing keys." } } } } } }, "responses": { "200": { "description": "Subscriber updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "subscriber": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "400": { "description": "Missing external ID or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete subscriber by external ID", "description": "Deletes a subscriber by their customer-owned external ID.", "operationId": "deleteSubscriberByExternalId", "tags": [ "Subscribers" ], "parameters": [ { "name": "externalId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "External ID. Query form supports IDs containing slashes." } ], "responses": { "200": { "description": "Subscriber deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted": { "type": "boolean" } } } } } }, "400": { "description": "Missing external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/subscribers/external/{externalId}": { "get": { "summary": "Get subscriber by external ID path", "description": "Compatibility route for external IDs that do not contain path separators. Use `/subscribers/external?externalId=...` for IDs containing slashes.", "operationId": "getSubscriberByExternalIdPath", "tags": [ "Subscribers" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded external ID without path separators" }, { "name": "includeMachineEngagement", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include detected scanner, preview, and tracked asset open/click events in subscriber email stats and recent activity." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "subscriber": { "$ref": "#/components/schemas/DetailedSubscriber" } } } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "summary": "Update subscriber by external ID path", "description": "Compatibility route for external IDs that do not contain path separators. Use `/subscribers/external?externalId=...` for IDs containing slashes.", "operationId": "updateSubscriberByExternalIdPath", "tags": [ "Subscribers" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded external ID without path separators" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "New delivery email. Fails with 409 if another subscriber owns it." }, "externalId": { "type": "string", "description": "New external ID. Fails with 409 if another subscriber owns it." }, "firstName": { "type": "string", "description": "Maximum 255 Unicode characters. Excess trailing ASCII spaces are accepted as by PostgreSQL. Longer names return 400 before any changes; correct the name before retrying. Omit to keep unchanged, or send an empty string to clear; null is not accepted." }, "lastName": { "type": "string", "description": "Maximum 255 Unicode characters. Excess trailing ASCII spaces are accepted as by PostgreSQL. Longer names return 400 before any changes; correct the name before retrying. Omit to keep unchanged, or send an empty string to clear; null is not accepted." }, "timezone": { "type": [ "string", "null" ], "maxLength": 64, "description": "IANA timezone identifier (e.g. America/New_York) used for recipient-local campaign delivery. Invalid values fail with a 400 validation error; null clears the stored value.", "example": "America/New_York" }, "phone": { "type": [ "string", "null" ], "description": "Phone number in E.164 format or national format. Stored normalized to E.164. Invalid values fail with a 400 validation error. Does not affect SMS consent. Changing it resets SMS consent unless smsConsent is sent in the same request. null or \"\" clears the phone, except on a phone-only (SMS) contact, where clearing its only identity fails with a 400 validation error.", "example": "+15551234567" }, "phoneCountry": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country used to read a national-format phone, defaulting to US. A parsing hint only - the stored phoneCountry always comes from the parsed number. Sending it without phone fails with a 400 validation error.", "example": "IT" }, "smsConsent": { "type": "boolean", "description": "SMS marketing consent. true sets smsStatus to subscribed with consent source api, false sets unsubscribed, omitted leaves SMS status unchanged. Never inferred from phone presence." }, "status": { "type": "string", "enum": [ "active", "unsubscribed", "bounced" ], "description": "Setting `unsubscribed` performs the unsubscribe workflow." }, "tags": { "type": "array", "items": { "type": "string" } }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Custom attributes to update. Defaults to replacing the existing public custom-attribute map." }, "customAttributesStrategy": { "type": "string", "enum": [ "replace", "merge" ], "default": "replace", "description": "How to apply customAttributes. replace replaces the existing public custom-attribute map. merge overwrites only provided keys and retains unspecified existing keys." } } } } } }, "responses": { "200": { "description": "Subscriber updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "subscriber": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "400": { "description": "Validation error, for example an overlong name or invalid phone number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete subscriber by external ID path", "description": "Compatibility route for external IDs that do not contain path separators. Use `/subscribers/external?externalId=...` for IDs containing slashes.", "operationId": "deleteSubscriberByExternalIdPath", "tags": [ "Subscribers" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded external ID without path separators" } ], "responses": { "200": { "description": "Subscriber deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted": { "type": "boolean" } } } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/subscribers/external/notes": { "get": { "summary": "List subscriber notes by external ID", "description": "Lists internal notes for a subscriber identified by customer-owned external ID.", "operationId": "listSubscriberNotesByExternalId", "tags": [ "Subscribers" ], "parameters": [ { "name": "externalId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "External ID. Query form supports IDs containing slashes." } ], "responses": { "200": { "description": "Subscriber notes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberNote" } } } } } } }, "400": { "description": "Missing external ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "summary": "Create subscriber note by external ID", "description": "Creates an internal note for a subscriber identified by customer-owned external ID.", "operationId": "createSubscriberNoteByExternalId", "tags": [ "Subscribers" ], "parameters": [ { "name": "externalId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "External ID. Query form supports IDs containing slashes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 5000, "description": "Internal note body." } } } } } }, "responses": { "200": { "description": "Subscriber note created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "note": { "$ref": "#/components/schemas/SubscriberNote" } } } } } }, "400": { "description": "Missing external ID or invalid note body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/notes/{noteId}": { "delete": { "summary": "Delete subscriber note", "description": "Deletes one internal subscriber note by note ID.", "operationId": "deleteSubscriberNote", "tags": [ "Subscribers" ], "parameters": [ { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Subscriber note ID." } ], "responses": { "200": { "description": "Subscriber note deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted": { "type": "boolean" }, "id": { "type": "string" }, "subscriberId": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Note not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/subscribers/{email}/notes": { "get": { "summary": "List subscriber notes", "description": "Lists internal notes for a subscriber identified by email address.", "operationId": "listSubscriberNotes", "tags": [ "Subscribers" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded email address" } ], "responses": { "200": { "description": "Subscriber notes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberNote" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "summary": "Create subscriber note", "description": "Creates an internal note for a subscriber identified by email address.", "operationId": "createSubscriberNote", "tags": [ "Subscribers" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded email address" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 5000, "description": "Internal note body." } } } } } }, "responses": { "200": { "description": "Subscriber note created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "note": { "$ref": "#/components/schemas/SubscriberNote" } } } } } }, "400": { "description": "Invalid note body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/{email}": { "get": { "summary": "Get subscriber by email", "description": "Retrieves a subscriber by their email address, including notes, list memberships, sequence enrollments, email stats, and recent activity.", "operationId": "getSubscriber", "tags": [ "Subscribers" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded email address" }, { "name": "includeMachineEngagement", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Include detected scanner, preview, and tracked asset open/click events in subscriber email stats and recent activity." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "subscriber": { "$ref": "#/components/schemas/DetailedSubscriber" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Subscriber not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "summary": "Update subscriber", "description": "Updates a subscriber's first name, last name, status, tags, or custom attributes. Setting `status` to `unsubscribed` performs the full unsubscribe workflow, including list unsubscription and sequence cancellation.", "operationId": "updateSubscriber", "tags": [ "Subscribers" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded email address" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "New delivery email. Fails with 409 if another subscriber owns it." }, "externalId": { "type": "string", "description": "New customer-owned external ID. Fails with 409 if another subscriber owns it." }, "firstName": { "type": "string", "description": "Maximum 255 Unicode characters. Excess trailing ASCII spaces are accepted as by PostgreSQL. Longer names return 400 before any changes; correct the name before retrying. Omit to keep unchanged, or send an empty string to clear; null is not accepted.", "example": "Jane" }, "lastName": { "type": "string", "description": "Maximum 255 Unicode characters. Excess trailing ASCII spaces are accepted as by PostgreSQL. Longer names return 400 before any changes; correct the name before retrying. Omit to keep unchanged, or send an empty string to clear; null is not accepted.", "example": "Smith" }, "timezone": { "type": [ "string", "null" ], "maxLength": 64, "description": "IANA timezone identifier such as America/New_York, stored as a native profile field and used for recipient-local campaign delivery. An invalid identifier returns 400 VALIDATION_ERROR. Omit to keep unchanged, or send null to clear.", "example": "America/New_York" }, "phone": { "type": [ "string", "null" ], "description": "Phone number in E.164 format or national format. Stored normalized to E.164. Invalid values fail with a 400 validation error. Does not affect SMS consent. Changing it resets SMS consent unless smsConsent is sent in the same request. null or \"\" clears the phone, except on a phone-only (SMS) contact, where clearing its only identity fails with a 400 validation error.", "example": "+15551234567" }, "phoneCountry": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country used to read a national-format phone, defaulting to US. A parsing hint only - the stored phoneCountry always comes from the parsed number. Sending it without phone fails with a 400 validation error.", "example": "IT" }, "smsConsent": { "type": "boolean", "description": "SMS marketing consent. true sets smsStatus to subscribed with consent source api, false sets unsubscribed, omitted leaves SMS status unchanged. Never inferred from phone presence." }, "status": { "type": "string", "enum": [ "active", "unsubscribed", "bounced" ], "description": "Setting `unsubscribed` performs a full global unsubscribe." }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "premium", "vip" ] }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Custom attributes to update. Defaults to replacing the existing public custom-attribute map." }, "customAttributesStrategy": { "type": "string", "enum": [ "replace", "merge" ], "default": "replace", "description": "How to apply customAttributes. replace replaces the existing public custom-attribute map. merge overwrites only provided keys and retains unspecified existing keys." } } } } } }, "responses": { "200": { "description": "Subscriber updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "subscriber": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "400": { "description": "Validation error, for example an overlong name or invalid phone number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete subscriber", "description": "Deletes a subscriber by their email address.", "operationId": "deleteSubscriber", "tags": [ "Subscribers" ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded email address" } ], "responses": { "200": { "description": "Subscriber deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "deleted": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/accounts": { "get": { "summary": "List accounts", "description": "Lists the B2B accounts (organizations) in the workspace. Search matches name, external ID and domain. Sort with `sort` (updatedAt, createdAt, name, memberCount, lastEventAt) and `order` (asc, desc).", "operationId": "listAccounts", "tags": [ "Accounts" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "updatedAt", "createdAt", "name", "memberCount", "lastEventAt" ] } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Accounts page", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "hasMore": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "summary": "Create or update account", "description": "Upserts an account by its customer-owned externalId. Attributes merge into the stored attributes (null deletes a key; replaceAttributes replaces them all). Optional members are added in the same call. Account attributes fan out to every member for segments and `{{account.*}}` merge tags.", "operationId": "upsertAccount", "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUpsertInput" } } } }, "responses": { "200": { "description": "Account updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUpsertResponse" } } } }, "201": { "description": "Account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUpsertResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "The first account would turn Accounts on, but contacts already use a custom attribute named `account` or `account.*`. Rename those contact attributes, then retry. Workspaces that already have Accounts on never receive this error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/{externalId}": { "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "Customer-owned organization ID (URL-encode slashes).", "schema": { "type": "string" } } ], "get": { "summary": "Get account", "description": "Returns the account and up to 100 members, owners first.", "operationId": "getAccountByExternalId", "tags": [ "Accounts" ], "responses": { "200": { "description": "Account with members", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/AccountMember" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Update account", "description": "Updates name, domain and attributes of an existing account. Returns 404 when the account does not exist.", "operationId": "updateAccount", "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPatchInput" } } } }, "responses": { "200": { "description": "Account updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete account", "description": "Deletes the account and its memberships. Contacts are kept; their `account.*` attributes are cleared.", "operationId": "deleteAccount", "tags": [ "Accounts" ], "responses": { "200": { "description": "Account deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted": { "type": "boolean" }, "membersCleared": { "type": "integer" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/accounts/{externalId}/members": { "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List account members", "description": "Lists the contacts that belong to the account with their role. Owners first, then admins, then members.", "operationId": "listAccountMembers", "tags": [ "Accounts" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 500, "maximum": 5000 } } ], "responses": { "200": { "description": "Members", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/AccountReference" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/AccountMember" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Add account member", "description": "Adds a contact to the account (creating the contact when `email` is new). Re-adding an existing member with a role updates it; without a role keeps the current one.", "operationId": "addAccountMember", "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "externalId": { "type": "string", "description": "Contact external ID, as an alternative to email." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } } } } }, "responses": { "200": { "description": "Existing membership updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountMemberChangeResponse" } } } }, "201": { "description": "Member added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountMemberChangeResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Remove account member", "description": "Removes a contact from the account. The contact is kept; its `account.*` attributes are cleared or replaced by another account it belongs to.", "operationId": "removeAccountMember", "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "externalId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Membership removed (or was not present)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" }, "removed": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/accounts/{externalId}/events": { "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List account events", "description": "Recent events recorded on the account timeline, newest first (maximum 500).", "operationId": "listAccountEvents", "tags": [ "Accounts" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 500 } } ], "responses": { "200": { "description": "Account events", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/AccountReference" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/AccountEvent" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Trigger account event", "description": "Records an event on the account timeline and delivers it as a contact event to the chosen recipients (`owners` by default, falling back to admins when there is no owner; `admins` includes owners; `all` every member; `none` records only). Each delivery runs the normal event pipeline with `event.account.*` properties. Pass `eventId` to make retries idempotent. Retries reuse the original recipients and event data, skip completed deliveries, and resume failed work without duplicating events or sequence enrollments.", "operationId": "triggerAccountEvent", "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "example": "trial_ending" }, "properties": { "type": "object", "additionalProperties": true }, "recipients": { "type": "string", "enum": [ "owners", "admins", "all", "none" ], "default": "owners" }, "eventId": { "type": "string", "description": "Idempotency key scoped to this account, including when accounts share members. Retries keep the original recipients, properties and event time and resume incomplete deliveries." }, "occurredAt": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Event recorded and delivered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "$ref": "#/components/schemas/Account" }, "event": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "time": { "type": "string", "format": "date-time" } } }, "recipients": { "type": "string", "enum": [ "owners", "admins", "all", "none" ] }, "recipientCount": { "type": "integer" }, "truncated": { "type": "boolean", "description": "True when the account has more matching members than the 5,000 fan-out cap." }, "duplicate": { "type": "boolean", "description": "True when a caller-supplied eventId had already been recorded; nothing new was written." }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "subscriberId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "success": { "type": "boolean" }, "automationsTriggered": { "type": "array", "items": { "type": "string" } }, "skipped": { "type": "string", "enum": [ "contact_deleted" ], "description": "Present when the recipient was deleted after the event was recorded. The delivery counts as finished and retries do not attempt it again." }, "error": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/account-suggestions": { "get": { "summary": "List account suggestions", "description": "Suggests accounts from work email domains that several contacts share, with up to 10 sample emails each. Personal and disposable providers (gmail.com, outlook.com, yopmail.com, ...), the workspace's own sending domains and their subdomains, domains where any contact already belongs to an account, and domains an account already uses (as its domain or external ID) are skipped. Largest domains first. Read-only; nothing is created until you accept a suggestion.", "operationId": "listAccountSuggestions", "tags": [ "Accounts" ], "parameters": [ { "name": "minContacts", "in": "query", "description": "Contacts a domain needs to be suggested. Values outside 2-1000 are clamped; non-numeric values use the default.", "schema": { "type": "integer", "default": 3, "minimum": 2, "maximum": 1000 } }, { "name": "limit", "in": "query", "description": "Number of suggestions. Values outside 1-100 are clamped; non-numeric values use the default.", "schema": { "type": "integer", "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "Suggestions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSuggestion" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key lacks `subscribers:read`, or no company is selected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Accept account suggestions", "description": "Creates an account for each domain (external ID and domain set to the domain, name derived from it) and adds the domain's contacts that belong to no account as members. When one account already uses the domain as its domain or external ID, contacts are added to it instead; with several, the domain is skipped (`multiple_accounts`). A domain whose contacts already partly belong to another account is skipped (`already_in_account`) so an organization is not duplicated. Domains without eligible contacts are skipped (`no_contacts`). Existing roles, names and domains are kept, no sync rules run, segment-entered sequences are not triggered, and retries are safe. Accounts hold at most 5,000 members, the attribute fan-out limit; `truncated` reports contacts left out.", "operationId": "acceptAccountSuggestions", "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string", "maxLength": 255 }, "description": "Domains to accept, such as `acme.com`. Normalized to lowercase; duplicates are ignored. Personal and disposable providers are rejected." } } } } } }, "responses": { "200": { "description": "Per-domain outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSuggestionsAcceptResponse" } } } }, "400": { "description": "A domain is invalid, a personal or disposable email provider, or one of the workspace's own sending domains. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key lacks `subscribers:write`, or no company is selected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accepting would turn Accounts on, but contacts already use a custom attribute named `account` or `account.*`. Rename those contact attributes, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request shape validation failed (missing `domains`, empty array or more than 25 entries)." } } } }, "/account-suggestions/organization-ids": { "get": { "summary": "Detect organization ID keys", "description": "Finds event properties from the last 180 days (such as `workspaceId` or `organization_id`) and contact attributes (such as `account_id`) that look like your own organization ID, so you can create accounts from data you already send. Most useful first. Read-only; preview a candidate before creating accounts from it.", "operationId": "detectAccountOrganizationIds", "tags": [ "Accounts" ], "responses": { "200": { "description": "Detected keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/AccountOrganizationIdCandidate" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key lacks `subscribers:read`, or no company is selected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create accounts from an organization ID", "description": "Starts a background job that creates one account per distinct value of `propertyKey` and adds each contact seen with that value as a `member`. Accounts are named from `nameKey` when set, otherwise after the work email domain most of their contacts share; existing names, domains and roles are kept. No emails are sent, no sync rules run and segment-entered sequences are not triggered. A run already queued or running for the same key is returned with `alreadyRunning` set instead of starting another; its `job.settings` show the source and name key it uses. Reruns are safe. Accounts is turned on before the job is queued and stays on even if the job fails.", "operationId": "createAccountsFromOrganizationId", "tags": [ "Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountOrganizationIdKey" } } } }, "responses": { "202": { "description": "Job queued, or the run already in progress for this key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "jobId": { "type": "string", "description": "Pass to `GET /account-suggestions/organization-ids/jobs/{jobId}`." }, "alreadyRunning": { "type": "boolean", "description": "True when a run for this key was already queued or running, so none was started." }, "job": { "$ref": "#/components/schemas/AccountOrganizationIdJob" } } } } } }, "400": { "description": "`propertyKey` is blank after trimming. Nothing is written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key lacks `subscribers:write`, or no company is selected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Creating accounts would turn Accounts on, but contacts already use a custom attribute named `account` or `account.*`. Rename those contact attributes, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request shape validation failed (missing `propertyKey` or an unknown `source`)." } } } }, "/account-suggestions/organization-ids/preview": { "get": { "summary": "Preview accounts from an organization ID", "description": "Shows the biggest organizations that creating accounts from `propertyKey` would make, with the name each account would get and sample contacts. Read-only.", "operationId": "previewAccountsFromOrganizationId", "tags": [ "Accounts" ], "parameters": [ { "name": "propertyKey", "in": "query", "required": true, "description": "Event property or contact attribute holding your organization ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "source", "in": "query", "description": "Where the ID lives.", "schema": { "type": "string", "enum": [ "event", "attribute" ], "default": "event" } }, { "name": "nameKey", "in": "query", "description": "Property or attribute holding the organization name.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "limit", "in": "query", "description": "Organizations to return. Values outside 1-50 are clamped; non-numeric values use the default.", "schema": { "type": "integer", "default": 5, "maximum": 50 } } ], "responses": { "200": { "description": "Biggest organizations first", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/AccountOrganizationIdPreview" } } } } } } }, "400": { "description": "`propertyKey` is blank after trimming.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key lacks `subscribers:read`, or no company is selected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request shape validation failed (missing `propertyKey` or an unknown `source`)." } } } }, "/account-suggestions/organization-ids/jobs/{jobId}": { "get": { "summary": "Get an organization ID account job", "description": "Reports a job started by `POST /account-suggestions/organization-ids`. Finished jobs are kept for a limited time, after which this returns 404; the accounts stay.", "operationId": "getAccountOrganizationIdJob", "tags": [ "Accounts" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The `jobId` returned when the job started, URL-encoded.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "job": { "$ref": "#/components/schemas/AccountOrganizationIdJob" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key lacks `subscribers:read`, or no company is selected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The job does not exist, has expired, or belongs to another workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/tags": { "post": { "summary": "Add tag to subscriber", "description": "Adds a tag to a subscriber. Creates the subscriber if they don't exist. Creates the tag definition if it doesn't exist. When the workspace has double opt-in enabled, a brand-new subscriber is created pending confirmation, the confirmation email is queued, and tag automations wait at their trigger until the subscriber confirms.", "operationId": "addTag", "tags": [ "Subscribers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tag" ], "properties": { "email": { "type": "string", "format": "email", "description": "Required when creating a new subscriber. Optional when externalId identifies an existing subscriber.", "example": "user@example.com" }, "externalId": { "type": "string", "description": "Customer-owned app/customer/user ID", "example": "user_123" }, "firstName": { "type": "string", "description": "First name to set if creating the subscriber.", "example": "John" }, "lastName": { "type": "string", "description": "Last name to set if creating the subscriber.", "example": "Doe" }, "tag": { "type": "string", "minLength": 1, "example": "premium" }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Optional attributes to set on the subscriber if created" } } } } } }, "responses": { "200": { "description": "Tag added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "subscriber": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ], "description": "Null for phone-only (SMS) contacts." }, "tags": { "type": "array", "items": { "type": "string" } }, "created": { "type": "boolean", "description": "Whether the subscriber was newly created" } } }, "tag": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "created": { "type": "boolean", "description": "Whether the tag definition was newly created" } } }, "optIn": { "type": "object", "description": "Present when this request created a brand-new subscriber while workspace double opt-in is enabled. The tag is applied, but the subscriber stays pending and tag automations wait until they confirm.", "properties": { "required": { "type": "boolean" }, "emailQueued": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/tags/bulk": { "post": { "summary": "Add multiple tags to subscriber", "description": "Adds multiple tags to a subscriber. Creates the subscriber if they don't exist. Creates tag definitions if they don't exist. When the workspace has double opt-in enabled, a brand-new subscriber is created pending confirmation, the confirmation email is queued, and tag automations wait at their trigger until the subscriber confirms.", "operationId": "addTagsBulk", "tags": [ "Subscribers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tags" ], "properties": { "email": { "type": "string", "format": "email", "description": "Required when creating a new subscriber. Optional when externalId identifies an existing subscriber.", "example": "user@example.com" }, "externalId": { "type": "string", "description": "Customer-owned app/customer/user ID", "example": "user_123" }, "firstName": { "type": "string", "description": "First name to set if creating the subscriber.", "example": "John" }, "lastName": { "type": "string", "description": "Last name to set if creating the subscriber.", "example": "Doe" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "example": [ "premium", "newsletter", "vip" ] }, "customAttributes": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Tags added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "subscriber": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ], "description": "Null for phone-only (SMS) contacts." }, "tags": { "type": "array", "items": { "type": "string" } }, "created": { "type": "boolean" } } }, "tags": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" }, "description": "Tag names that were added" }, "created": { "type": "array", "items": { "type": "string" }, "description": "Tag definitions that were newly created" } } }, "optIn": { "type": "object", "description": "Present when this request created a brand-new subscriber while workspace double opt-in is enabled. The tags are applied, but the subscriber stays pending and tag automations wait until they confirm.", "properties": { "required": { "type": "boolean" }, "emailQueued": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/tags/remove": { "post": { "summary": "Remove tag from subscriber", "description": "Removes a tag from a subscriber. Creates the subscriber if they don't exist (without the tag).", "operationId": "removeTag", "tags": [ "Subscribers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tag" ], "properties": { "email": { "type": "string", "format": "email", "description": "Required when creating a new subscriber. Optional when externalId identifies an existing subscriber.", "example": "user@example.com" }, "externalId": { "type": "string", "description": "Customer-owned app/customer/user ID", "example": "user_123" }, "tag": { "type": "string", "minLength": 1, "example": "premium" }, "firstName": { "type": "string", "description": "First name (used if creating new subscriber)" }, "lastName": { "type": "string", "description": "Last name (used if creating new subscriber)" } } } } } }, "responses": { "200": { "description": "Tag removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "subscriber": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ], "description": "Null for phone-only (SMS) contacts." }, "tags": { "type": "array", "items": { "type": "string" } }, "created": { "type": "boolean", "description": "Whether the subscriber was newly created" } } }, "tag": { "type": "object", "properties": { "name": { "type": "string" }, "removed": { "type": "boolean", "description": "Whether the tag was removed from the subscriber" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/bulk/tags/add": { "post": { "summary": "Add tags to many subscribers", "description": "Adds one or more tags to up to 500 existing subscribers identified by email, externalId, or subscriberId. Built for reconciling historical or derived tags, so identifiers that do not match an existing subscriber are returned in notFound rather than creating contacts. Tag automations are skipped unless triggerAutomations is true, which requires the automations:trigger scope.", "operationId": "bulkAddSubscriberTags", "tags": [ "Subscribers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSubscriberTagRequest" }, "examples": { "backfill": { "summary": "Backfill a derived tag without enrolling anyone", "value": { "tags": [ "derived-churn-risk" ], "emails": [ "one@example.com", "two@example.com" ] } } } } } }, "responses": { "200": { "description": "Bulk tag update completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSubscriberTagResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "triggerAutomations requested without the automations:trigger scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/bulk/tags/remove": { "post": { "summary": "Remove tags from many subscribers", "description": "Removes one or more tags from up to 500 existing subscribers identified by email, externalId, or subscriberId. Identifiers that do not match an existing subscriber are returned in notFound.", "operationId": "bulkRemoveSubscriberTags", "tags": [ "Subscribers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSubscriberTagRequest" }, "examples": { "rollback": { "summary": "Roll back a derived tag backfill", "value": { "tags": [ "derived-churn-risk" ], "subscriberIds": [ "sub_abc123", "sub_def456" ] } } } } } }, "responses": { "200": { "description": "Bulk tag update completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSubscriberTagResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/events": { "post": { "summary": "Trigger event for subscriber", "description": "Triggers an event for a subscriber. Creates the subscriber if they don't exist and applies the workspace default lists setting. Creates the event definition if it doesn't exist. When the workspace has double opt-in enabled, a brand-new subscriber is created pending confirmation, the confirmation email is queued, and matching sequences wait at their trigger until the subscriber confirms.", "operationId": "triggerEvent", "tags": [ "Subscribers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event" ], "properties": { "email": { "type": "string", "format": "email", "description": "Required when creating a new subscriber. Optional when externalId identifies an existing subscriber.", "example": "user@example.com" }, "externalId": { "type": "string", "description": "Customer-owned app/customer/user ID", "example": "user_123" }, "firstName": { "type": "string", "description": "First name to set if creating the subscriber.", "example": "John" }, "lastName": { "type": "string", "description": "Last name to set if creating the subscriber.", "example": "Doe" }, "event": { "type": "string", "minLength": 1, "example": "purchase.completed" }, "properties": { "type": "object", "additionalProperties": true, "description": "Event properties/metadata", "example": { "amount": 9900, "currency": "USD", "productId": "prod_123" } }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Optional attributes to set on the subscriber if created" }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the event actually happened. Defaults to now. More than an hour in the past records it as history - stored with the real timestamp and counted by segments, but running no sequences, sync rules, waiting steps, goal conversions or webhooks, and the response carries historical=true. Older than the 5-year event retention window is rejected with 400.", "example": "2024-11-02T10:00:00Z" }, "account": { "description": "Attach the contact to an account (your customer's organization, unrelated to your Sequenzy account). Pass the account's externalId as a string, or an object with externalId plus optional name, domain, role (owner, admin, member) and attributes. The account is created when missing and its context is added to the event as `event.account.*`. Only used once the workspace has Accounts on (it has at least one account, or Accounts was turned on in the dashboard). Before that, the field is ignored in any shape and the response includes `accountIgnored`.", "oneOf": [ { "type": "string", "example": "org_123" }, { "type": "object", "required": [ "externalId" ], "properties": { "externalId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "attributes": { "type": "object", "additionalProperties": true } } } ] }, "eventId": { "type": "string", "description": "Caller-owned event ID used as an idempotency key on both paths. A repeated live event returns the existing event with duplicate=true. A repeated historical event remains a historical response and increments duplicates instead. Best-effort for live events sent within about a second of each other, so a producer needing a strict guarantee should keep its own ledger.", "example": "inv_9182" } } } } } }, "responses": { "200": { "description": "Event triggered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "subscriber": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ], "description": "Null for phone-only (SMS) contacts." }, "created": { "type": "boolean" } } }, "event": { "type": "object", "properties": { "id": { "type": "string", "description": "The created event record ID" }, "name": { "type": "string" }, "definitionCreated": { "type": "boolean", "description": "Whether the event definition was newly created" } } }, "account": { "type": "object", "description": "Present when `account` attached the contact to an account.", "properties": { "externalId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "created": { "type": "boolean", "description": "Whether this request created the account." } } }, "accountIgnored": { "type": "object", "description": "Present when the request included `account` but the workspace has not turned Accounts on, so the field was ignored. Create an account with POST /accounts or turn Accounts on in the dashboard.", "properties": { "reason": { "type": "string", "enum": [ "accounts_not_enabled" ] }, "message": { "type": "string" } } }, "duplicate": { "type": "boolean", "description": "Present and true when a live event's supplied eventId was already recorded for this contact and event name. Nothing was written and no side effects ran; event holds the existing event. Historical responses use duplicates instead.", "example": true }, "historical": { "type": "boolean", "description": "Present and true when occurredAt selected the historical import path.", "example": true }, "events": { "type": "array", "description": "Historical event results. Present instead of event on the historical path.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" } } } }, "inserted": { "type": "integer", "description": "Historical event rows inserted by this request.", "example": 1 }, "duplicates": { "type": "integer", "description": "Historical event rows skipped because their idempotency receipt already existed.", "example": 0 }, "sideEffectFailures": { "type": "array", "items": { "type": "string" }, "description": "Present when the event was recorded but one or more side-effect stages (e.g. apply-sync-rules, trigger-event-automations) failed. Retry-sensitive callers should treat these as partial failures.", "example": [ "apply-sync-rules" ] }, "optIn": { "type": "object", "description": "Present when this event created a brand-new subscriber while workspace double opt-in is enabled. The subscriber stays pending and matching sequences wait until they confirm.", "properties": { "required": { "type": "boolean" }, "emailQueued": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/events/bulk": { "post": { "summary": "Trigger multiple events for subscriber", "description": "Triggers multiple events for a subscriber. Creates the subscriber if they don't exist and applies the workspace default lists setting. Creates event definitions if they don't exist. Events are processed independently, so an error response may still include events that were already triggered. When the workspace has double opt-in enabled, a brand-new subscriber is created pending confirmation, a single confirmation email is queued for the request, and matching sequences wait at their trigger until the subscriber confirms.", "operationId": "triggerEventsBulk", "tags": [ "Subscribers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "events" ], "properties": { "email": { "type": "string", "format": "email", "description": "Required when creating a new subscriber. Optional when externalId identifies an existing subscriber.", "example": "user@example.com" }, "externalId": { "type": "string", "description": "Customer-owned app/customer/user ID", "example": "user_123" }, "firstName": { "type": "string", "description": "First name to set if creating the subscriber.", "example": "John" }, "lastName": { "type": "string", "description": "Last name to set if creating the subscriber.", "example": "Doe" }, "events": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "example": "page.viewed" }, "properties": { "type": "object", "additionalProperties": true, "example": { "page": "/pricing" } }, "occurredAt": { "type": "string", "format": "date-time", "description": "When this event actually happened. Defaults to now. When every event in the batch is more than an hour old the batch is imported as history in one idempotent write, running no sequences, sync rules, waiting steps, goal conversions or webhooks.", "example": "2024-11-02T10:00:00Z" }, "eventId": { "type": "string", "description": "Caller-owned event ID that makes a re-run idempotent on both the live and historical paths. On the live path a repeated ID is skipped and its response entry carries duplicate=true.", "example": "inv_9182" } } } }, "customAttributes": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Events triggered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "subscriber": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ], "description": "Null for phone-only (SMS) contacts." }, "created": { "type": "boolean" } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "definitionCreated": { "type": "boolean" }, "duplicate": { "type": "boolean", "description": "Present and true when this event's eventId was already recorded for the contact and event name, so nothing was written and no side effects ran.", "example": true }, "sideEffectFailures": { "type": "array", "items": { "type": "string" }, "description": "Present when this event was recorded but one or more side-effect stages (e.g. apply-sync-rules, trigger-event-automations) failed." } } } }, "optIn": { "type": "object", "description": "Present when this request created a brand-new subscriber while workspace double opt-in is enabled. The subscriber stays pending and matching sequences wait until they confirm.", "properties": { "required": { "type": "boolean" }, "emailQueued": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/events/imports": { "post": { "summary": "Import events for many subscribers", "description": "Records a bounded batch of up to 25 events for many subscribers. Email is required to create a contact; externalId-only rows must resolve to an existing contact. Events are grouped per contact - a contact whose rows are all more than an hour old is imported silently as history, including no double-opt-in email, while any recent row makes that contact's whole group live. Stable eventIds keep one receipt and let retries re-attempt downstream recovery idempotently.", "operationId": "importSubscriberEvents", "tags": [ "Subscribers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 25, "description": "Events to record. Each event identifies its own subscriber.", "items": { "type": "object", "required": [ "name", "eventId" ], "properties": { "email": { "type": [ "string", "null" ], "format": "email", "description": "Subscriber email address. Required when the event may create a new contact; null is treated as absent.", "example": "user@example.com" }, "externalId": { "type": [ "string", "null" ], "description": "Customer-owned subscriber ID. It can be used alone only when it resolves to an existing contact; null is treated as absent.", "example": "user_123" }, "name": { "type": "string", "description": "Event name.", "example": "purchase_completed" }, "properties": { "type": "object", "additionalProperties": true, "description": "Event properties. Unrecognized keys outside these documented fields are ignored - keep row data inside properties." }, "occurredAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the event happened (ISO 8601, null treated as absent). Only when every row for that contact is more than an hour old is the group historical; any recent row makes the whole group live." }, "eventId": { "type": "string", "minLength": 1, "description": "Required source-owned id for this event, used as an idempotency key so re-running the import records nothing twice.", "example": "order_12345" } } } } } } } } }, "responses": { "200": { "description": "Import processed. success is false when any event failed - recorded events are kept, so treat errors as partial success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "total": { "type": "integer", "description": "Events submitted in this request." }, "recorded": { "type": "integer", "description": "Events recorded by this request." }, "duplicates": { "type": "integer", "description": "Events skipped because their eventId was already recorded." }, "failed": { "type": "integer", "description": "Events that failed to record." }, "sideEffectFailed": { "type": "integer", "description": "Receipt rows whose downstream side effects or historical automation shielding failed. This is orthogonal to receipt accounting and may accompany either recorded or duplicate rows during recovery." }, "subscribers": { "type": "integer", "description": "Distinct subscriber identities in the request." }, "failures": { "type": "array", "description": "Failed events by input index.", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "error": { "type": "string" } } } }, "sideEffectFailures": { "type": "array", "description": "Post-write failures by input index. The receipt exists (new or duplicate); retry with the same eventId for recovery.", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "stages": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } } } }, "error": { "type": "string", "description": "First failure message when any event failed." } } } } } }, "400": { "description": "Invalid request - a row is missing identity or carries a bad timestamp", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segments": { "get": { "summary": "List segments", "description": "Lists saved segments with counts recalculated from their filters for the authenticated company. subscriberCount includes every status; activeSubscriberCount includes only active subscribers. Custom-attribute updates sync asynchronously and may take roughly 30–35 seconds or longer to appear, even after an import completes.", "operationId": "listSegments", "tags": [ "Segments" ], "responses": { "200": { "description": "Segments returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } } } } } }, "400": { "$ref": "#/components/responses/SegmentReferenceLimitExceeded" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "summary": "Create segment", "description": "Creates a saved segment from either flat filters or a nested filter root.", "operationId": "createSegment", "tags": [ "Segments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "filters": { "type": "array", "description": "Legacy v1 flat filter shape. Provide either filters or root.", "items": { "$ref": "#/components/schemas/FilterLeaf" } }, "filterJoinOperator": { "type": "string", "enum": [ "and", "or" ] }, "root": { "description": "Nested v2 filter tree. Provide either root or filters.", "$ref": "#/components/schemas/FilterGroup" } }, "required": [ "name" ], "anyOf": [ { "required": [ "filters" ] }, { "required": [ "root" ] } ] } } } }, "responses": { "200": { "description": "Segment created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "segment": { "$ref": "#/components/schemas/Segment" }, "warnings": { "type": "array", "description": "Non-fatal cautions, such as an attribute filter referencing a custom attribute no subscriber has a synced value for (which would match no subscribers, or every subscriber for exclusion operators like is_empty). Absent when there is nothing to warn about.", "items": { "type": "string" } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidTagOperator": { "value": { "success": false, "error": "Operator \"is not\" is not supported for Tag filters. Use one of: contains, does not contain, is empty, is not empty." } }, "malformedFilterTree": { "value": { "success": false, "error": "Invalid segment filters: root.children[1].children: must be an array of filters and groups", "issues": [ { "path": "root.children[1].children", "message": "must be an array of filters and groups" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Segment name conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFriendlyError" } } } } } } }, "/segments/{segmentId}": { "patch": { "summary": "Update segment", "description": "Updates a saved segment's name or filter definition.", "operationId": "updateSegment", "tags": [ "Segments" ], "parameters": [ { "name": "segmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/FilterLeaf" } }, "filterJoinOperator": { "type": "string", "enum": [ "and", "or" ] }, "root": { "$ref": "#/components/schemas/FilterGroup" } } } } } }, "responses": { "200": { "description": "Segment updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "segment": { "$ref": "#/components/schemas/Segment" }, "warnings": { "type": "array", "description": "Non-fatal cautions, such as an attribute filter referencing a custom attribute no subscriber has a synced value for (which would match no subscribers, or every subscriber for exclusion operators like is_empty). Absent when there is nothing to warn about.", "items": { "type": "string" } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidTagOperator": { "value": { "success": false, "error": "Operator \"is not\" is not supported for Tag filters. Use one of: contains, does not contain, is empty, is not empty." } }, "malformedFilterTree": { "value": { "success": false, "error": "Invalid segment filters: root.children[1].children: must be an array of filters and groups", "issues": [ { "path": "root.children[1].children", "message": "must be an array of filters and groups" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Segment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteSegment", "summary": "Delete segment", "description": "Deletes a saved segment. Subscribers matched by the segment are not affected.", "tags": [ "Segments" ], "parameters": [ { "name": "segmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Segment ID." } ], "responses": { "200": { "description": "Segment deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Segment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/segments/{segmentId}/count": { "get": { "summary": "Get segment count", "description": "Recalculates the active subscriber count from a saved segment's filters. Matches activeSubscriberCount from listSegments when underlying data is unchanged. Custom-attribute updates sync asynchronously and may take roughly 30–35 seconds or longer to appear, even after an import completes.", "operationId": "getSegmentCount", "tags": [ "Segments" ], "parameters": [ { "name": "segmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Segment count returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "segmentId": { "type": "string" }, "count": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/SegmentReferenceLimitExceeded" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Segment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/migrations/{runId}": { "get": { "summary": "Get migration run", "description": "Returns provider-neutral migration status, discovery, plan, progress, and report.", "operationId": "getMigrationRun", "tags": [ "Migrations" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Migration run returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "run_123", "status": "awaiting_approval", "discovery": { "provider": "kit", "resources": [ { "id": "subscribers", "type": "subscribers", "count": 3470 }, { "id": "campaigns", "type": "campaigns", "count": 108 }, { "id": "automations", "type": "automations", "count": 42 } ] }, "approvedPlan": {}, "progress": {}, "report": { "subscribersQueued": 0, "draftCampaignsCreated": 0, "draftSequencesCreated": 0, "draftTransactionalEmailsCreated": 0 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Migration run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/migrations/{runId}/agent-package": { "get": { "summary": "Get migration agent package", "description": "Returns endpoint URLs and exact call sequence for an agent-assisted migration.", "operationId": "getMigrationAgentPackage", "tags": [ "Migrations" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent package returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true } } }, "example": { "success": true, "data": { "runId": "run_123", "provider": "kit", "providerLabel": "Kit", "systemPrompt": "Preserve provider email HTML exactly...", "instructions": [ "Do not convert migrated HTML into Sequenzy blocks or recreate the email from its visible text." ], "endpoints": { "connectSource": "https://api.sequenzy.com/api/v1/migrations/run_123/connect-source" }, "sequence": [ "POST connect-source with the provider credential." ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Migration run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/migrations/{runId}/connect-source": { "post": { "summary": "Connect migration source", "description": "Stores a provider credential on an existing migration run connection.", "operationId": "connectMigrationSource", "tags": [ "Migrations" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "credential" ], "properties": { "provider": { "type": "string", "description": "Provider adapter ID. Supported values include `active-campaign`, `brevo`, `constant-contact`, `customer-io`, `drip`, `hubspot`, `kit`, `klaviyo`, `loops`, `mailchimp`, `mailerlite`, `mailjet`, `omnisend`, `resend`, and `sendgrid`." }, "credential": { "type": "string", "description": "Provider API credential." }, "providerLabel": { "type": "string", "description": "Optional display label for manual providers." } } } } } }, "responses": { "200": { "description": "Source connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Migration run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/migrations/{runId}/discover": { "post": { "summary": "Discover migration source", "description": "Queues provider discovery for a migration run.", "operationId": "discoverMigrationSource", "tags": [ "Migrations" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Discovery queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Migration run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/migrations/{runId}/approve-plan": { "post": { "summary": "Approve migration plan", "description": "Approves provider-neutral resources and freezes the execution plan for a migration run.", "operationId": "approveMigrationPlan", "tags": [ "Migrations" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resourceIds" ], "properties": { "resourceIds": { "type": "array", "items": { "type": "string" } }, "resourceOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } } } } } }, "responses": { "200": { "description": "Plan approved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Invalid approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Approval failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/migrations/{runId}/start": { "post": { "summary": "Start migration", "description": "Queues execution for an approved migration run. Queued or running runs return their current state without another execution or plan change. Completed, failed, canceled and cancel_requested runs return 400. At least one selected resource is required, from resourceIds or the previously approved plan. resourceOptions applies only with a nonempty resourceIds selection.", "operationId": "startMigration", "tags": [ "Migrations" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceIds": { "type": "array", "items": { "type": "string" } }, "resourceOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true } } } } } } }, "responses": { "200": { "description": "Migration queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Run cannot start in its current state, or no resources were selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Migration run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/migrations/{runId}/cancel": { "post": { "summary": "Cancel migration", "description": "Cancels queued/pre-execution runs immediately. Running imports move to cancel_requested while workers stop linked subscriber import chunks, then finish as canceled.", "operationId": "cancelMigration", "tags": [ "Migrations" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Migration canceled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Migration run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audience-syncs": { "get": { "summary": "List audience syncs", "description": "Lists segment-to-Meta-audience syncs with schedule and last sync status.", "operationId": "listAudienceSyncs", "tags": [ "Audience Syncs" ], "responses": { "200": { "description": "Audience syncs returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "audienceSyncs": { "type": "array", "items": { "$ref": "#/components/schemas/AudienceSync" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "summary": "Create audience sync", "description": "Pushes a segment to a Meta custom audience and keeps it synced on a schedule. Provide segmentId for an existing segment or predefinedSegmentId for a ready-made template (for example zero-ltv, no-purchase-1y, recent-buyers); template segments are created automatically on first use. The first upload runs immediately. Audiences are add-only - subscribers who later leave the segment stay in the Meta audience. Requires the Meta Ads integration to be connected in the dashboard.", "operationId": "createAudienceSync", "tags": [ "Audience Syncs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "segmentId": { "type": "string", "description": "Existing segment ID. Provide either segmentId or predefinedSegmentId, not both." }, "predefinedSegmentId": { "type": "string", "description": "Ready-made segment template ID (for example recent-buyers). The template segment is created on first use and reused afterwards; an unrelated same-named segment with different filters causes a 409." }, "adAccountId": { "type": "string", "description": "Meta ad account ID (act_...). See GET /ad-accounts." }, "audienceName": { "type": "string", "description": "Name for the custom audience in Meta Ads Manager." }, "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ], "default": "daily" } }, "required": [ "adAccountId", "audienceName" ], "anyOf": [ { "required": [ "segmentId" ] }, { "required": [ "predefinedSegmentId" ] } ] } } } }, "responses": { "200": { "description": "Audience sync created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "audienceSync": { "$ref": "#/components/schemas/AudienceSync" } } } } } }, "400": { "description": "Validation error (for example both segmentId and predefinedSegmentId provided) or Meta Ads not connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Segment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Segment already synced to that ad account, or the template's name is taken by an unrelated segment with different filters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audience-syncs/{syncId}": { "patch": { "summary": "Update audience sync", "description": "Changes an audience sync's frequency or pauses/resumes it.", "operationId": "updateAudienceSync", "tags": [ "Audience Syncs" ], "parameters": [ { "name": "syncId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "hourly", "daily", "weekly" ] }, "isActive": { "type": "boolean", "description": "false pauses the sync, true resumes it." } } } } } }, "responses": { "200": { "description": "Audience sync updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "audienceSync": { "$ref": "#/components/schemas/AudienceSync" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Audience sync not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete audience sync", "description": "Removes the sync mapping. The Meta audience itself is kept so running ads are not disrupted - only future syncs stop.", "operationId": "deleteAudienceSync", "tags": [ "Audience Syncs" ], "parameters": [ { "name": "syncId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Audience sync deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Audience sync not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/audience-syncs/{syncId}/sync": { "post": { "summary": "Run audience sync now", "description": "Triggers an immediate upload outside the regular schedule. The sync must be active.", "operationId": "runAudienceSyncNow", "tags": [ "Audience Syncs" ], "parameters": [ { "name": "syncId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "queued": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Sync is paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Audience sync not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ad-accounts": { "get": { "summary": "List ad accounts", "description": "Lists the Meta ad accounts reachable through the connected Meta Ads integration.", "operationId": "listAdAccounts", "tags": [ "Audience Syncs" ], "responses": { "200": { "description": "Ad accounts returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "adAccounts": { "type": "array", "items": { "$ref": "#/components/schemas/AdAccount" } } } } } } }, "400": { "description": "Meta Ads not connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/transactional": { "get": { "summary": "List transactional emails", "description": "Lists transactional email templates with their linked subjects and all-time delivery metrics. Search name, slug, or subject; filter active state; and sort by engagement. Human engagement is used by default.", "operationId": "listTransactionalEmails", "tags": [ "Transactional" ], "parameters": [ { "name": "label", "in": "query", "description": "Filter by company label names, matching any. Repeat the parameter for multiple names; commas are literal characters. Combined with search and status. Unknown names match no templates.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive search across template name, API slug, and linked email subject/title." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "all", "active", "disabled" ], "default": "all" }, "description": "Filter by template active state." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "date", "sends", "opens", "open-rate", "clicks", "ctr" ], "default": "date" }, "description": "Sort by creation date or all-time engagement metrics." }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction." }, { "name": "includeMachineEngagement", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include detected bot, scanner, preview, and privacy-proxy engagement in open and click metrics." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "transactional": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionalEmailListItem" } } } } } } }, "400": { "description": "Invalid label filter, including blank or overlong names.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient API-key permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request query does not match the schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "summary": "Create transactional email", "description": "Creates a saved transactional email template from exactly one of prompt, HTML, or Sequenzy blocks. Prompt-created templates default to disabled.", "operationId": "createTransactionalEmail", "tags": [ "Transactional" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EmailBodyInput" }, { "type": "object", "required": [ "name" ], "properties": { "labels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Company label names. Trimmed and deduplicated; missing names are created. Replaces all assignments; [] clears them. Omit to preserve assignments on update or start without labels on create. Null and blank names are rejected." }, "name": { "type": "string", "example": "Password Reset" }, "slug": { "type": "string", "description": "Optional API slug used when sending by slug. If omitted, one is generated from the name.", "example": "password-reset" }, "subject": { "type": "string", "description": "Required with HTML or blocks; optional with prompt, where it overrides the generated subject.", "example": "Reset your password, {{NAME}}" }, "previewText": { "type": [ "string", "null" ], "example": "Use this link to reset your password." }, "prompt": { "type": "string", "minLength": 1, "description": "Natural-language request for branded transactional blocks." }, "style": { "type": "string", "description": "Generation style; valid only with prompt. Pass designed or plain to force the designed or plain-text email style; other values are freeform prompt guidance. Defaults to the company's email style preference." }, "tone": { "type": "string", "description": "Generation tone; valid only with prompt." }, "enabled": { "type": "boolean", "description": "Defaults to false with prompt and true with explicit HTML or blocks.", "example": true } } } ] } } } }, "responses": { "201": { "description": "Transactional email created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "transactional": { "$ref": "#/components/schemas/TransactionalEmailDetails" }, "warnings": { "$ref": "#/components/schemas/BlockFieldWarnings" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing-content": { "summary": "Missing content source", "value": { "success": false, "error": "Provide exactly one of prompt, html, or blocks." } }, "mixed-content": { "summary": "Content sources cannot be mixed", "value": { "success": false, "error": "Provide exactly one of prompt, html, or blocks." } }, "missing-sender": { "summary": "Sender profile is required", "value": { "success": false, "error": "No sender profile configured. Please create a sender profile first." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient API-key permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "A transactional email with slug \"password-reset\" already exists" } } } }, "422": { "description": "Request body does not match the schema, including null or non-array labels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transactional/{idOrSlug}": { "get": { "summary": "Get transactional email", "description": "Gets details of a transactional email template by ID or slug, including linked body content and available template variables.", "operationId": "getTransactionalEmail", "tags": [ "Transactional" ], "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Transactional email ID or slug", "example": "welcome-email" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "transactional": { "$ref": "#/components/schemas/TransactionalEmailDetails" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient API-key permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Transactional email not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Transactional email \"welcome-email\" not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "summary": "Update transactional email", "description": "Updates transactional email metadata and labels or replaces the linked email body using raw HTML or Sequenzy blocks. Code-managed emails (`managedBy: code`, created by sends with `trackAs`) accept only `name`, `enabled` and `labels`; their content comes from each send, so `subject`, `previewText`, `html` and `blocks` return 400.", "operationId": "updateTransactionalEmail", "tags": [ "Transactional" ], "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Transactional email ID or slug", "example": "welcome-email" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EmailBodyInput" }, { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Company label names. Trimmed and deduplicated; missing names are created. Replaces all assignments; [] clears them. Omit to preserve assignments on update or start without labels on create. Null and blank names are rejected." }, "name": { "type": "string", "example": "Welcome Email" }, "enabled": { "type": "boolean", "example": true }, "subject": { "type": "string", "example": "Welcome, {{NAME}}" }, "previewText": { "type": [ "string", "null" ], "example": "Your account is ready." } } } ] } } } }, "responses": { "200": { "description": "Transactional email updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "transactional": { "$ref": "#/components/schemas/TransactionalEmailDetails" }, "warnings": { "$ref": "#/components/schemas/BlockFieldWarnings" } } } } } }, "400": { "description": "Validation error, including content changes to a code-managed email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "This transactional email is managed in code. Its content comes from each send; update name, enabled or labels instead." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient API-key permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Transactional email not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request body does not match the schema, including null or non-array labels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete transactional email", "description": "Permanently deletes a saved transactional email template by ID or slug, so its slug stops sending and becomes free to reuse.\n\nAlready-sent deliveries are untouched: send history, stats, and stored HTML live on the deliveries themselves.\n\nThe email content is kept as a reusable template and returned as `deleted.emailId`; pass that to `DELETE /api/v1/templates/{templateId}` to remove the content too. Code-managed emails (`managedBy: code`) are the exception: their content snapshot is deleted with them, so the returned `emailId` no longer exists. To stop sends without losing the template, update it with `enabled: false` instead.\n\nRequires an API key with the `transactional:delete` scope.\n", "operationId": "deleteTransactionalEmail", "tags": [ "Transactional" ], "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Transactional email ID or slug", "example": "welcome-email" } ], "responses": { "200": { "description": "Transactional email deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Transactional email deleted" }, "deleted": { "type": "object", "properties": { "id": { "type": "string", "example": "txn_abc123" }, "slug": { "type": "string", "example": "welcome-email" }, "name": { "type": "string", "example": "Welcome Email" }, "emailId": { "type": "string", "description": "The email content kept as a reusable template. Delete it separately with `DELETE /api/v1/templates/{templateId}`. For a code-managed email this id no longer exists; see `emailDeleted`.", "example": "email_abc123" }, "emailDeleted": { "type": "boolean", "description": "True when the content was deleted with the email (code-managed emails, whose content is a snapshot of a real send). False when it was kept as a reusable template.", "example": false } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing the transactional:delete scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Transactional email not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Transactional email \"welcome-email\" not found" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/transactional/send": { "post": { "summary": "Send transactional or marketing email", "description": "Queues an email for sending. The default `emailType` is `transactional`. Set it to `marketing` for a consented single-recipient lifecycle or promotional message. Marketing mode creates or links a minimal subscriber, honors unsubscribe suppression, adds the standard marketing footer, and emits RFC 8058 one-click-unsubscribe headers. The caller remains responsible for having consent or another lawful basis.\n\nFor callers that may retry, send a stable `Idempotency-Key` header. The same key and request returns the original `emailSendId` for 14 days without another delivery. Reusing a key with different request content returns 409.\n\nRepeated identical transactional content reaching many distinct recipients can trigger a junk/list-testing review. Sending continues while review is pending or unavailable. A substantiated verdict can reject later matching deliveries before sending; these become terminal `failed` sends with an `errorMessage` beginning `Transactional content rejected:`. Read GET /email-sends/{emailSendId} for the final outcome. Failed deliveries are not held or replayed automatically, and replaying the same Idempotency-Key returns the original acceptance response. Dashboard retries of rejected deliveries also fail without sending, even after the decision expires. Correct the content or contact support before deliberately submitting a new logical send. This check does not pause the company or ban the account.\n\nYou can either:\n- Provide a canonical `slug` (or compatibility alias `templateId`) to use a saved template\n- Provide `subject` and canonical `body` (or compatibility alias `html`) to send custom content directly\n\nIf both a canonical field and its alias are provided, `slug` must match `templateId` and `body` must match `html`.\n\n**Tracking direct-content sends:**\n- Set `trackAs` on a direct-content send (for example `weekly-report`) to count it under one code-managed transactional email. The first send with a new value creates it with `managedBy: code`; later sends with the same value link to it. The value may use up to 255 ASCII letters, digits, spaces and `. _ - : /`, and is normalized like a slug (`Weekly Report` and `weekly-report` are the same email). Other values, including empty ones, return 400 `INVALID_TRACK_AS`.\n- Opens, clicks, bounces and the other transactional stats then aggregate on that email, and it appears in `GET /transactional` next to your saved templates. Its subject, preview text and HTML are a snapshot of a recent send, refreshed at most every 10 minutes and stored before variable substitution.\n- Disabling the code-managed email makes further sends with that `trackAs` fail with 400 `TRACKED_EMAIL_DISABLED` until you enable it again. Deleting it lets the next send recreate it with fresh stats.\n- `trackAs` cannot be combined with `slug`/`templateId`, cannot reuse the slug of a template managed in the dashboard, and a company can have at most 100 code-managed emails. Use a stable name for an email type, never per-recipient values. Code-managed emails cannot be sent by `slug`.\n- The email is created after the send passes request validation, so an invalid send does not create it. A send that fails later, for example on an `Idempotency-Key` conflict, can still leave the newly created email with no sends.\n\n**Recipients:**\n- `to` can be a single email or an array of up to 50 emails\n- Duplicate emails are automatically deduplicated\n- Marketing mode requires exactly one `to` recipient and does not support `cc` or `bcc`\n\n**Attachments:**\n- Attachments can be provided as Base64-encoded content or URLs\n- Maximum 10 attachments and 15MB total per email\n- Any file type supported (PDFs, images, documents, etc.)\n- Set `contentId` on an attachment to embed it as an inline image referenced from the HTML as ``\n\nA successful response means the email was accepted for background processing. Transactional emails are not blocked by subscriber unsubscribe or double opt-in status. If a recipient is suppressed because of a hard bounce or spam complaint, the worker records the send as `suppressed` instead of delivering it.\n\nOptionally set `from` (domain must be verified) and `replyTo` addresses. When reply tracking is enabled, Sequenzy uses a unique trackable `Reply-To` header and treats the resolved reply destination as the forwarding destination for captured replies.\nWithout a reply identity override, saved-template sends prefer the template reply profile. Otherwise sends prefer the effective sending domain's default reply profile, then the company default, then the first company reply profile. The resolved destination is retained whether or not reply tracking is enabled; it is sent as the Reply-To header only when reply tracking is disabled.\nVariables can be passed to customize the email content. Nested objects and arrays are supported for repeat blocks, such as `items`. `{{viewInBrowserUrl}}` is generated automatically for a hosted copy link. For a single recipient, Sequenzy matches an existing subscriber by `subscriberExternalId` or email and backfills stored first and last names when the corresponding request variables are omitted; explicit variables take precedence. Returns immediately with a durable `emailSendId` and the accepted `emailType`. If Sequenzy detects likely missing or unused variables before queueing, the successful response includes a non-blocking `diagnostics` warning object. Missing values do not block queueing or sending; a required variable that is not provided and has no default renders as an empty string.\n\nSelect existing identities with senderProfileId or fromEmail (and optional fromName), and replyProfileId or replyTo (with optional replyToName). These inputs look up profiles rather than create them. Use emailType, not isMarketing, to choose delivery policy.", "operationId": "sendTransactionalEmail", "tags": [ "Transactional" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Caller-owned key for one logical email. Reuse the same key and request on retries to receive the original send for 14 days. Reusing the key with different content returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to" ], "properties": { "to": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50, "minItems": 1 } ], "description": "Recipient email address(es). Can be a single email string or an array of up to 50 emails.\n", "example": "recipient@example.com" }, "cc": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 } ], "description": "Visible carbon-copy recipient email address(es). Duplicates already present in `to` are removed.", "example": "manager@example.com" }, "bcc": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 } ], "description": "Blind-carbon-copy recipient email address(es). Duplicates already present in `to` or `cc` are removed.", "example": "archive@example.com" }, "slug": { "type": "string", "description": "Canonical slug of the transactional email template to use (mutually exclusive with direct content).", "example": "welcome-email" }, "templateId": { "type": "string", "description": "Compatibility alias for `slug`. Despite the field name, pass the saved transactional email API slug, not its database ID. Must match `slug` when both are provided.", "example": "welcome-email" }, "subscriberExternalId": { "type": "string", "maxLength": 255, "description": "Customer-owned subscriber ID for single-recipient sends. If it matches an existing subscriber, analytics and localization use that subscriber; the value is also stored on the send and emitted as external_id in outbound email webhooks even when no subscriber exists. Maximum length is 255 characters.", "example": "user_123" }, "emailType": { "type": "string", "enum": [ "transactional", "marketing" ], "default": "transactional", "description": "Delivery policy. Marketing mode requires one recipient, creates or links a minimal subscriber, honors unsubscribe suppression, adds the standard footer, and emits RFC 8058 List-Unsubscribe and List-Unsubscribe-Post headers.", "example": "marketing" }, "subject": { "type": "string", "description": "Email subject (required if not using slug)", "example": "Welcome to our platform!" }, "body": { "type": "string", "description": "Canonical email body HTML content (required if not using a template slug).", "example": "

Welcome!

Thanks for signing up.

" }, "html": { "type": "string", "description": "Compatibility alias for `body`. Accepted with `subject` for direct sends and must match `body` when both are provided.", "example": "

Welcome!

Thanks for signing up.

" }, "preview": { "type": "string", "description": "Preview text for the email (only used with direct content)", "example": "Welcome to our platform" }, "trackAs": { "type": "string", "description": "Direct content only. Names the email type so its sends are counted under one code-managed transactional email, created on first use. Up to 255 ASCII letters, digits, spaces and `. _ - : /`, including at least one letter or digit; it is normalized like a slug. Cannot be combined with `slug`/`templateId`.", "example": "weekly-report" }, "variables": { "type": "object", "additionalProperties": true, "description": "Variables for template replacement (works with both modes). Values can be scalars, nested objects, or arrays used by repeat blocks. For a single recipient, stored subscriber first and last names fill missing name variables; explicit request variables take precedence. Raw HTML templates can use simple subscriber/custom-attribute conditionals such as `{{#if subscriber.plan}}...{{else}}...{{/if}}` and `{{#unless subscriber.plan}}...{{/unless}}`. Variables are always HTML-escaped; a template can prefix a tag with `html.` (`{{html.prerenderedHtml}}`) to insert a trusted HTML value unescaped. Injected HTML is sanitized (scripts, event handlers, and dangerous URLs are stripped), only applies in HTML text position, and must not contain end-user input. Likely variable issues are returned as non-blocking diagnostics when possible; missing required variables without defaults render as empty strings and do not block sending.", "example": { "NAME": "John", "event": { "items": [ { "title": "Pro plan", "description": "Monthly subscription" } ] } } }, "from": { "type": "string", "description": "Custom from address. Format: \"Name \" or just \"email\".\nThe domain must be verified for your account. If not verified, this field is silently ignored.\nWhen the address exactly matches an existing sender identity (the display name disambiguates if\nseveral identities share the address), that identity - including its sending route - is used for\nthe send; otherwise the template or company-default identity is kept and this field only changes\nthe visible From.\n Mutually exclusive with senderProfileId, fromEmail and fromName.", "example": "Notifications " }, "replyTo": { "type": "string", "description": "Reply-to address as \"Name \" or a bare email, optionally paired with replyToName. Mutually exclusive with replyProfileId. With reply tracking enabled, Sequenzy sends a trackable Reply-To and stores this address as its forwarding destination. Without a reply override, saved-template sends prefer the template reply profile; otherwise sends prefer the effective sending-domain default, then company default, then the first company reply profile.", "example": "Support " }, "attachments": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/Attachment" }, "description": "File attachments for the email. Each attachment must have a filename and either:\n- `content`: Base64-encoded file content\n- `path`: URL to fetch the file from\n\nSet `contentId` to embed the file as an inline image the HTML references with `` instead of attaching it.\n\nMaximum 10 attachments and 15MB total per email.\n", "example": [ { "filename": "invoice.pdf", "path": "https://example.com/invoices/123.pdf" } ] }, "trackingSettings": { "type": "object", "description": "Per-send tracking opt-outs. Omitted fields follow the company Transactional API open/click defaults. Set false to disable tracking for this send. Neither true nor omission can enable tracking disabled by account-wide or Transactional API settings.", "properties": { "clickTracking": { "type": "boolean", "description": "Set `false` to skip link rewriting so the original URLs are delivered unchanged. Useful when the click-tracking redirect domain breaks iOS/Android universal links or deep links in transactional emails." }, "openTracking": { "type": "boolean", "description": "Set `false` to skip the open-tracking pixel for this send only." } }, "example": { "clickTracking": false } }, "headers": { "type": "object", "description": "Extra email headers as header name to string value, up to 50 applied. Names use letters, digits and hyphens (max 100 characters); values are one line of printable ASCII and each `Name: value` line fits in 998 characters. A transactional send can carry your own `List-Unsubscribe`, plus `List-Unsubscribe-Post: List-Unsubscribe=One-Click` for RFC 8058 one-click unsubscribe; unsubscribes through your link are not suppressed in Sequenzy. Marketing sends always use Sequenzy's signed unsubscribe headers, so `List-Unsubscribe`, `List-Unsubscribe-Post`, `Precedence` and `Feedback-ID` are not applied. Headers Sequenzy manages (From, Sender, To, Cc, Bcc, Reply-To, Subject, Date, Message-ID, MIME-Version, Return-Path, Received, Received-SPF, Delivered-To, DKIM-Signature, Authentication-Results, and names starting with Content-, X-Sequenzy-, X-SES-, ARC- or Resent-) are never applied. A header that cannot be applied never fails the request; it is listed in the response `ignoredHeaders`. Names match case-insensitively; when names differ only in case, only the first one is considered, even if it is not applied. A retry of a failed delivery (dashboard or outage recovery) resends without these headers.", "additionalProperties": { "type": "string" }, "example": { "List-Unsubscribe": "", "List-Unsubscribe-Post": "List-Unsubscribe=One-Click" } }, "senderProfileId": { "type": "string", "description": "Existing verified sender profile ID. Mutually exclusive with fromEmail, fromName and from. Selects that identity and its sending route; does not create a profile." }, "fromEmail": { "type": "string", "description": "Address of an existing verified sender profile in this company. Mutually exclusive with senderProfileId and from. If several identities share the address, select one with fromName." }, "fromName": { "type": "string", "description": "Display name selecting an existing identity on fromEmail. Requires fromEmail; mutually exclusive with senderProfileId and from. Does not create a profile." }, "replyProfileId": { "type": "string", "description": "Existing reply profile ID. Mutually exclusive with replyTo and replyToName. Overrides the saved template and default reply identity." }, "replyToName": { "type": "string", "description": "Display name for a bare replyTo address. Requires replyTo and is mutually exclusive with replyProfileId. Does not create a profile." } } }, "examples": { "slug-based": { "summary": "Send using template slug", "value": { "to": "recipient@example.com", "slug": "welcome-email", "variables": { "NAME": "John" } } }, "repeat-array-data": { "summary": "Send array data to a repeat block", "value": { "to": "recipient@example.com", "slug": "order-confirmation", "variables": { "NAME": "John", "event": { "items": [ { "title": "Pro plan", "description": "Monthly subscription" }, { "title": "Priority support", "description": "Account add-on" } ] } } } }, "direct-content": { "summary": "Send with direct content", "value": { "to": "recipient@example.com", "subject": "Your order confirmation", "body": "

Order Confirmed

Thank you for your order, {{NAME}}!

", "preview": "Your order has been confirmed", "variables": { "NAME": "John" } } }, "tracked-direct-content": { "summary": "Track direct content under one code-managed email", "value": { "to": "recipient@example.com", "subject": "Your week in review", "html": "

Your week

{{SUMMARY}}

", "trackAs": "weekly-report", "variables": { "SUMMARY": "3 new subscribers" } } }, "compatibility-aliases": { "summary": "Send direct content using the HTML alias", "value": { "to": "recipient@example.com", "subject": "Connection test", "html": "

Connected.

" } }, "with-custom-from-and-reply": { "summary": "Send with custom from and reply-to", "value": { "to": "recipient@example.com", "slug": "order-confirmation", "variables": { "NAME": "John", "ORDER_ID": "12345" }, "from": "Notifications ", "replyTo": "Support " } }, "multiple-recipients": { "summary": "Send to multiple recipients", "value": { "to": [ "user1@example.com", "user2@example.com" ], "slug": "order-confirmation", "variables": { "ORDER_ID": "12345" } } }, "with-attachments": { "summary": "Send with file attachments", "value": { "to": "customer@example.com", "slug": "invoice", "variables": { "INVOICE_NUMBER": "INV-2025-001" }, "attachments": [ { "filename": "invoice.pdf", "path": "https://example.com/invoices/INV-2025-001.pdf" }, { "filename": "terms.pdf", "content": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC..." } ] } } } } } }, "responses": { "200": { "description": "Email queued successfully", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "title": "Slug-based response", "properties": { "success": { "type": "boolean", "example": true }, "emailSendId": { "type": "string", "example": "send_abc123", "description": "Durable email delivery ID. Use this with GET /email-sends/{emailSendId}." }, "emailType": { "type": "string", "enum": [ "marketing", "transactional" ], "description": "Delivery policy accepted for the queued email." }, "jobId": { "type": "string", "example": "job_abc123", "deprecated": true, "description": "Legacy queue identifier retained for response compatibility." }, "idempotentReplay": { "type": "boolean", "description": "True when this response replays an earlier request with the same Idempotency-Key." }, "to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "recipient@example.com" }, "transactional": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" } } }, "diagnostics": { "$ref": "#/components/schemas/TransactionalSendDiagnostics" }, "ignoredHeaders": { "$ref": "#/components/schemas/TransactionalSendIgnoredHeaders" }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Deduplicated CC recipients; omitted when empty." }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Deduplicated BCC recipients; omitted when empty." } } }, { "type": "object", "title": "Direct content response", "properties": { "success": { "type": "boolean", "example": true }, "emailSendId": { "type": "string", "example": "send_abc123", "description": "Durable email delivery ID. Use this with GET /email-sends/{emailSendId}." }, "emailType": { "type": "string", "enum": [ "marketing", "transactional" ], "description": "Delivery policy accepted for the queued email." }, "jobId": { "type": "string", "example": "job_abc123", "deprecated": true, "description": "Legacy queue identifier retained for response compatibility." }, "idempotentReplay": { "type": "boolean", "description": "True when this response replays an earlier request with the same Idempotency-Key." }, "to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "recipient@example.com" }, "transactional": { "type": "object", "description": "Code-managed transactional email the send is counted under. Present only when the request set `trackAs`.", "properties": { "id": { "type": "string", "example": "tx_weekly123" }, "slug": { "type": "string", "example": "weekly-report" }, "name": { "type": "string", "example": "Weekly report" } } }, "diagnostics": { "$ref": "#/components/schemas/TransactionalSendDiagnostics" }, "ignoredHeaders": { "$ref": "#/components/schemas/TransactionalSendIgnoredHeaders" }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Deduplicated CC recipients; omitted when empty." }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Deduplicated BCC recipients; omitted when empty." } } } ] } } } }, "400": { "description": "Bad request (validation error, disabled template, attachment errors, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing-params": { "summary": "Missing required parameters", "value": { "success": false, "error": "Either 'slug'/'templateId' OR both 'subject' and 'body'/'html' are required" } }, "disabled": { "summary": "Template is disabled", "value": { "success": false, "error": "Transactional email \"welcome-email\" is disabled" } }, "track-as-with-slug": { "summary": "trackAs combined with a saved template", "value": { "success": false, "error": "trackAs only applies to sends with subject and body/html. Saved templates already track their own stats.", "code": "TRACK_AS_REQUIRES_DIRECT_CONTENT" } }, "track-as-invalid": { "summary": "trackAs is empty, too long or uses unsupported characters", "value": { "success": false, "error": "trackAs must be 1-255 characters of ASCII letters, digits, spaces or . _ - : / and include a letter or digit", "code": "INVALID_TRACK_AS" } }, "track-as-dashboard-slug": { "summary": "trackAs matches a dashboard template", "value": { "success": false, "error": "trackAs \"welcome-email\" matches a transactional email managed in the dashboard. Send it with slug, or choose a different trackAs.", "code": "TRACK_AS_MANAGED_IN_DASHBOARD" } }, "tracked-email-disabled": { "summary": "Code-managed email is disabled", "value": { "success": false, "error": "Transactional email \"weekly-report\" is disabled", "code": "TRACKED_EMAIL_DISABLED" } }, "code-managed-limit": { "summary": "Company already has 100 code-managed emails", "value": { "success": false, "error": "This workspace already tracks 100 code-managed emails. Reuse an existing trackAs value or delete unused ones; trackAs should name an email type, not include per-recipient values.", "code": "CODE_MANAGED_LIMIT_REACHED" } }, "code-managed-slug-send": { "summary": "Code-managed email sent by slug", "value": { "success": false, "error": "Transactional email \"weekly-report\" is managed in code. Send subject and body with trackAs \"weekly-report\" instead of slug." } }, "no-sender": { "summary": "No sender profile configured", "value": { "success": false, "error": "No sender profile configured. Please create a sender profile first." } }, "too-many-recipients": { "summary": "Too many recipients", "value": { "success": false, "error": "Too many recipients. Maximum 50 recipients allowed." } }, "attachments-too-large": { "summary": "Attachments exceed size limit", "value": { "success": false, "error": "Total attachment size exceeds 15MB limit." } }, "invalid-attachment": { "summary": "Invalid attachment format", "value": { "success": false, "error": "Attachment must have either 'content' or 'path', not both." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Transactional email with slug \"unknown-template\" not found" } } } }, "409": { "description": "Idempotency-Key was already used with different request content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Idempotency-Key was already used with a different request", "code": "IDEMPOTENCY_KEY_REUSED" } } } }, "429": { "description": "API key rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the request can be retried." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-minute request limit." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current minute policy." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the minute budget resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Send was reserved but queue infrastructure is temporarily unavailable; retry with the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Email send is reserved but could not be queued; retry with the same Idempotency-Key", "code": "TRANSACTIONAL_ENQUEUE_UNAVAILABLE", "retryable": true } } } } } } }, "/submissions/{sourceType}/{sourceId}": { "get": { "summary": "List capture submissions", "operationId": "listCaptureSubmissions", "description": "Read immutable accepted answers for a form, popup or landing page. Requires subscribers:read plus widgets:read for forms/popups or landing_pages:read for landing pages. History is forward-only; deleting a subscriber, source or company removes associated records. Reads can be retried safely.", "tags": [ "Widgets" ], "parameters": [ { "name": "sourceType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "form", "popup", "landing_page" ] } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "nextCursor from the previous page, keeping the same filters.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "field", "in": "query", "description": "Exact custom attribute key; requires value. Omit both to clear filtering.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "value", "in": "query", "description": "Exact scalar answer or string array member; requires field. Empty string is allowed.", "schema": { "type": "string", "maxLength": 5000 } }, { "name": "format", "in": "query", "description": "csv adds a CSV string for this page; the response remains JSON.", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "Newest-first page of accepted submissions", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "source", "submissions", "nextCursor" ], "properties": { "success": { "type": "boolean" }, "source": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "form", "popup", "landing_page" ] } } }, "submissions": { "type": "array", "items": { "type": "object", "required": [ "id", "companyId", "formId", "subscriberId", "payload", "fieldLabels", "createdAt" ], "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "form", "popup", "landing_page" ] }, "sourceId": { "type": "string" }, "formId": { "type": [ "string", "null" ] }, "popupId": { "type": [ "string", "null" ] }, "landingPageId": { "type": [ "string", "null" ] }, "subscriberId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "fieldLabels": { "type": "object", "additionalProperties": { "type": "string" } }, "payload": { "type": "object", "required": [ "email", "customAttributes" ], "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phone": { "type": "string" }, "customAttributes": { "type": "object", "additionalProperties": true }, "recovery": { "type": "object", "description": "Present only for reconstructed historical records. The source is inferred and createdAt is an evidence event time, not a verified submission timestamp.", "required": [ "evidenceType", "evidenceId", "recoveredAt", "sourceAttribution", "timestampMeaning" ], "properties": { "evidenceType": { "type": "string", "enum": [ "contact.added", "subscriber.updated" ] }, "evidenceId": { "type": "string" }, "recoveredAt": { "type": "string", "format": "date-time" }, "sourceAttribution": { "type": "string", "enum": [ "inferred" ] }, "timestampMeaning": { "type": "string", "enum": [ "event_time" ] } } } } } } } }, "nextCursor": { "type": [ "string", "null" ] }, "csv": { "type": "string", "description": "Present only for format=csv." } } } } } }, "400": { "description": "Invalid cursor, format, limit, or incomplete filter pair" }, "401": { "description": "Missing or invalid authentication" }, "403": { "description": "Missing read scopes or workspace access" }, "404": { "description": "Source not found in the authorized workspace" }, "500": { "description": "Database failure; safe to retry this read" } } } }, "/forms/{companyIdOrFormId}/submissions": { "get": { "summary": "List form submissions (alias)", "operationId": "listFormSubmissions", "description": "Form-only alias for GET /submissions/form/{formId}. Requires widgets:read and subscribers:read. Returns immutable accepted answers recorded since tracking began. Reads can be retried safely.", "tags": [ "Widgets" ], "parameters": [ { "name": "companyIdOrFormId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "description": "nextCursor from the previous page, keeping the same filters.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "field", "in": "query", "description": "Exact custom attribute key; requires value. Omit both to clear filtering.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "value", "in": "query", "description": "Exact scalar answer or string array member; requires field. Empty string is allowed.", "schema": { "type": "string", "maxLength": 5000 } }, { "name": "format", "in": "query", "description": "csv adds a CSV string for this page; the response remains JSON.", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "Newest-first page of accepted submissions", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "source", "submissions", "nextCursor" ], "properties": { "success": { "type": "boolean" }, "source": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "form", "popup", "landing_page" ] } } }, "submissions": { "type": "array", "items": { "type": "object", "required": [ "id", "companyId", "formId", "subscriberId", "payload", "fieldLabels", "createdAt" ], "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "form", "popup", "landing_page" ] }, "sourceId": { "type": "string" }, "formId": { "type": [ "string", "null" ] }, "popupId": { "type": [ "string", "null" ] }, "landingPageId": { "type": [ "string", "null" ] }, "subscriberId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "fieldLabels": { "type": "object", "additionalProperties": { "type": "string" } }, "payload": { "type": "object", "required": [ "email", "customAttributes" ], "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phone": { "type": "string" }, "customAttributes": { "type": "object", "additionalProperties": true }, "recovery": { "type": "object", "description": "Present only for reconstructed historical records. The source is inferred and createdAt is an evidence event time, not a verified submission timestamp.", "required": [ "evidenceType", "evidenceId", "recoveredAt", "sourceAttribution", "timestampMeaning" ], "properties": { "evidenceType": { "type": "string", "enum": [ "contact.added", "subscriber.updated" ] }, "evidenceId": { "type": "string" }, "recoveredAt": { "type": "string", "format": "date-time" }, "sourceAttribution": { "type": "string", "enum": [ "inferred" ] }, "timestampMeaning": { "type": "string", "enum": [ "event_time" ] } } } } } } } }, "nextCursor": { "type": [ "string", "null" ] }, "csv": { "type": "string", "description": "Present only for format=csv." } } } } } }, "400": { "description": "Invalid cursor, format, limit, or incomplete filter pair" }, "401": { "description": "Missing or invalid authentication" }, "403": { "description": "Missing read scopes or workspace access" }, "404": { "description": "Source not found in the authorized workspace" }, "500": { "description": "Database failure; safe to retry this read" } } } }, "/forms": { "get": { "summary": "List saved forms", "description": "Lists saved signup forms for the authenticated workspace, including their server-managed audience settings and public action URLs.", "operationId": "listSavedForms", "tags": [ "Widgets" ], "responses": { "200": { "description": "Saved forms returned successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "companyId", "forms" ], "properties": { "success": { "type": "boolean", "example": true }, "companyId": { "type": "string" }, "forms": { "type": "array", "items": { "$ref": "#/components/schemas/SavedForm" } }, "url": { "type": "string", "format": "uri", "description": "Forms dashboard URL." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "summary": "Create saved form", "description": "Creates and publishes a saved signup form. Its opaque form ID becomes a client-safe public capability while audience and success settings remain server-side.", "operationId": "createSavedForm", "tags": [ "Widgets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "listIds" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "listIds": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string" } }, "tagIds": { "type": "array", "maxItems": 200, "items": { "type": "string" } }, "duplicateStrategy": { "type": "string", "enum": [ "skip", "merge", "overwrite" ], "default": "skip" }, "resubscribeBehavior": { "type": "string", "enum": [ "reactivate", "double_opt_in" ], "default": "reactivate", "description": "What happens when a contact who unsubscribed from all email submits this form again. `reactivate` resubscribes them and restores the form's lists. `double_opt_in` sends the workspace confirmation email first and resubscribes them when they confirm. Turning it on requires a double opt-in confirmation email and a sender profile, otherwise the request returns 400; if either is removed later, returning unsubscribed contacts stay unsubscribed. Workspace double opt-in always requires confirmation. `duplicateStrategy` never changes subscription status." }, "buttonText": { "type": "string" }, "headline": { "type": "string" }, "description": { "type": "string" }, "successMessage": { "type": "string" }, "redirectUrl": { "type": "string", "format": "uri" }, "showFirstName": { "type": "boolean" }, "showLastName": { "type": "boolean" }, "theme": { "type": "object", "description": "Optional visual theme overrides (accentColor, backgroundColor, textColor, mutedTextColor, cardColor, borderColor as \"#rrggbb\", borderRadius 0-32, headingFontFamily, bodyFontFamily, density).", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Form created and published", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "form": { "$ref": "#/components/schemas/SavedForm" }, "embed": { "$ref": "#/components/schemas/SavedFormEmbed" } } } } } }, "400": { "description": "Invalid audience, duplicate strategy, resubscribe behavior, or redirect URL, or `resubscribeBehavior` is `double_opt_in` before the workspace has a double opt-in confirmation email and default sender", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to create form", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forms/embed/{formId}": { "get": { "summary": "Get saved form embed recipes", "description": "Returns a published saved form's public action URL, hosted JavaScript, minimal native form, fetch enhancement, and supported static-site platforms.", "operationId": "getSavedFormEmbed", "tags": [ "Widgets" ], "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Embed recipes returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "form": { "$ref": "#/components/schemas/SavedForm" }, "embed": { "$ref": "#/components/schemas/SavedFormEmbed" } } } } } }, "400": { "description": "Form is not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/popups": { "get": { "summary": "List saved popups", "description": "Lists saved on-site signup popups for the authenticated workspace, including their trigger, targeting, audience settings, and view and conversion counts.", "operationId": "listSavedPopups", "tags": [ "Widgets" ], "parameters": [ { "name": "includeContent", "in": "query", "required": false, "description": "Set to `true` to include every popup's full content blocks. Omitted by default because each popup adds roughly 1.8k characters; read one popup with `GET /popups/{popupId}` instead.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Saved popups returned successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "companyId", "popups" ], "properties": { "success": { "type": "boolean", "example": true }, "companyId": { "type": "string" }, "popups": { "type": "array", "items": { "$ref": "#/components/schemas/SavedPopup" } }, "note": { "type": "string", "description": "Present when content blocks were omitted, explaining how to fetch them." }, "url": { "type": "string", "format": "uri" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "summary": "Create saved popup", "description": "Creates a saved on-site signup popup and returns the one-line script tag that deploys it. The popup is published by default, so the script is live as soon as it is added to the site. Trigger, targeting, audience, and duplicate handling stay server-side, so the deployed script carries no API key.\n\nOmit `listIds` to capture into every list, matching the dashboard default.\n", "operationId": "createSavedPopup", "tags": [ "Widgets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "template": { "type": "string", "enum": [ "newsletter-modal", "discount-offer", "countdown-launch", "minimal-slide-in", "exit-lead-magnet", "live-demo", "launch-modal", "paper-digest", "stark-takeover", "top-bar", "announcement-bar", "fullscreen-welcome" ], "default": "newsletter-modal", "description": "Starting design for the popup's blocks and theme." }, "status": { "type": "string", "enum": [ "draft", "published" ], "default": "published" }, "listIds": { "type": "array", "maxItems": 200, "items": { "type": "string" }, "description": "Lists every signup is added to. Omit or pass an empty array to capture into every list." }, "tagIds": { "type": "array", "maxItems": 200, "items": { "type": "string" } }, "duplicateStrategy": { "type": "string", "enum": [ "skip", "merge", "overwrite" ], "default": "skip" }, "resubscribeBehavior": { "type": "string", "enum": [ "reactivate", "double_opt_in" ], "default": "reactivate", "description": "What happens when a contact who unsubscribed from all email submits this popup again. `reactivate` resubscribes them and restores the popup's lists. `double_opt_in` sends the workspace confirmation email first and resubscribes them when they confirm. Turning it on requires a double opt-in confirmation email and a sender profile, otherwise the request returns 400; if either is removed later, returning unsubscribed contacts stay unsubscribed. Workspace double opt-in always requires confirmation. `duplicateStrategy` never changes subscription status." }, "headline": { "type": "string" }, "description": { "type": "string" }, "buttonText": { "type": "string" }, "successMessage": { "type": "string" }, "redirectUrl": { "type": "string", "format": "uri" }, "presentation": { "type": "string", "enum": [ "modal", "slide-in", "floating-bar", "fullscreen" ] }, "placement": { "type": "string", "enum": [ "center", "left", "right", "top", "bottom" ] }, "trigger": { "$ref": "#/components/schemas/SavedPopupTrigger" }, "targeting": { "$ref": "#/components/schemas/SavedPopupTargeting" }, "schedule": { "$ref": "#/components/schemas/SavedPopupSchedule" }, "frequency": { "$ref": "#/components/schemas/SavedPopupFrequency" }, "visual": { "$ref": "#/components/schemas/SavedPopupVisual" }, "theme": { "type": "object", "description": "Optional visual theme overrides (accentColor, backgroundColor, textColor, mutedTextColor, cardColor, borderColor as \"#rrggbb\", borderRadius 0-32, headingFontFamily, bodyFontFamily, density).", "additionalProperties": true }, "blocks": { "type": "array", "maxItems": 200, "description": "Complete replacement for the popup's content blocks. The popup must keep exactly one required email field and one submit button.", "items": { "type": "object", "additionalProperties": true } } } } } } }, "responses": { "200": { "description": "Popup created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "popup": { "$ref": "#/components/schemas/SavedPopup" }, "embed": { "$ref": "#/components/schemas/SavedPopupEmbed" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid template, status, audience, redirect URL, or popup content, including `resubscribeBehavior` set to `double_opt_in` before the workspace has a double opt-in confirmation email and default sender", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to create popup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/popups/embed/{popupId}": { "get": { "summary": "Get saved popup embed recipes", "description": "Returns a published popup's script URL plus ready-to-paste snippets for plain HTML, React and Next.js, WordPress, and Shopify. The snippets carry no API key.", "operationId": "getSavedPopupEmbed", "tags": [ "Widgets" ], "parameters": [ { "name": "popupId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Embed recipes returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "popup": { "$ref": "#/components/schemas/SavedPopup" }, "embed": { "$ref": "#/components/schemas/SavedPopupEmbed" } } } } } }, "400": { "description": "Popup is not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Popup not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/popups/{popupId}/duplicate": { "post": { "summary": "Duplicate saved popup", "description": "Copies a saved popup into a new draft with its own view and conversion counts. The original keeps its status and stats, so a live popup carries on showing while the copy is edited.", "operationId": "duplicateSavedPopup", "tags": [ "Widgets" ], "parameters": [ { "name": "popupId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Name for the copy. Defaults to the original name with \" (copy)\" appended." } } } } } }, "responses": { "200": { "description": "Popup duplicated as a draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "popup": { "$ref": "#/components/schemas/SavedPopup" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Popup not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to duplicate popup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/popups/{popupId}": { "get": { "summary": "Get saved popup", "description": "Returns one saved popup with its complete content blocks, trigger, targeting, schedule, frequency, and theme. Read this before replacing blocks so the replacement array stays complete.", "operationId": "getSavedPopup", "tags": [ "Widgets" ], "parameters": [ { "name": "popupId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Popup returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "popup": { "$ref": "#/components/schemas/SavedPopup" }, "embed": { "$ref": "#/components/schemas/SavedPopupEmbed" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Popup not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "summary": "Update saved popup", "description": "Updates a saved popup. Only the fields you send change.\n\nSet `status` to `published` to make the popup live, or `draft` to stop it showing while keeping the popup, its stats, and its embed script. `trigger`, `targeting`, `schedule`, `frequency`, and `visual` are merged key by key, so patching one key keeps the rest.\n", "operationId": "updateSavedPopup", "tags": [ "Widgets" ], "parameters": [ { "name": "popupId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "listIds": { "type": "array", "maxItems": 200, "items": { "type": "string" }, "description": "Replacement list targeting. Pass an empty array to capture into every list." }, "tagIds": { "type": "array", "maxItems": 200, "items": { "type": "string" }, "description": "Replacement tag IDs. Pass an empty array to clear tags." }, "duplicateStrategy": { "type": "string", "enum": [ "skip", "merge", "overwrite" ] }, "resubscribeBehavior": { "type": "string", "enum": [ "reactivate", "double_opt_in" ], "description": "What happens when a contact who unsubscribed from all email submits this popup again. `reactivate` resubscribes them and restores the popup's lists. `double_opt_in` sends the workspace confirmation email first and resubscribes them when they confirm. Turning it on requires a double opt-in confirmation email and a sender profile, otherwise the request returns 400; if either is removed later, returning unsubscribed contacts stay unsubscribed. Workspace double opt-in always requires confirmation. `duplicateStrategy` never changes subscription status." }, "headline": { "type": "string", "description": "New text for the popup's first heading block. Fails when the popup has no heading block." }, "description": { "type": "string", "description": "New text for the popup's first paragraph block. Fails when the popup has no paragraph block." }, "buttonText": { "type": "string" }, "successMessage": { "type": "string" }, "redirectUrl": { "type": "string", "description": "HTTP or HTTPS URL for successful signups. Pass an empty string to switch back to the confirmation message." }, "presentation": { "type": "string", "enum": [ "modal", "slide-in", "floating-bar", "fullscreen" ] }, "placement": { "type": "string", "enum": [ "center", "left", "right", "top", "bottom" ] }, "trigger": { "$ref": "#/components/schemas/SavedPopupTrigger" }, "targeting": { "$ref": "#/components/schemas/SavedPopupTargeting" }, "schedule": { "$ref": "#/components/schemas/SavedPopupSchedule" }, "frequency": { "$ref": "#/components/schemas/SavedPopupFrequency" }, "visual": { "$ref": "#/components/schemas/SavedPopupVisual" }, "theme": { "type": "object", "description": "Visual theme overrides merged into the current theme.", "additionalProperties": true }, "blocks": { "type": "array", "maxItems": 200, "description": "Complete replacement for the popup's content blocks. The popup must keep exactly one required email field and one submit button.", "items": { "type": "object", "additionalProperties": true } } } } } } }, "responses": { "200": { "description": "Popup updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "popup": { "$ref": "#/components/schemas/SavedPopup" }, "embed": { "$ref": "#/components/schemas/SavedPopupEmbed" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid status, audience, redirect URL, or popup content, including `resubscribeBehavior` set to `double_opt_in` before the workspace has a double opt-in confirmation email and default sender", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Popup not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to update popup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete saved popup", "description": "Permanently deletes a saved popup along with its view and conversion counts. Subscribers it already captured are not affected. To stop a popup from showing while keeping its stats, set its status to draft instead.", "operationId": "deleteSavedPopup", "tags": [ "Widgets" ], "parameters": [ { "name": "popupId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Popup deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "popupId": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Popup not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/forms/{companyIdOrFormId}": { "patch": { "summary": "Update saved form", "description": "Update a saved form's name, audience targeting, copy, visual theme, or content blocks. Every field is optional - send only what should change.\n\nThe `headline`, `description`, `buttonText`, and `successMessage` fields edit the matching content block and fail with 400 when the form has no such block; replace `blocks` for structural changes. The `blocks` array fully replaces the form's content blocks and must keep exactly one required email field and one submit button. An empty `redirectUrl` switches the form back to its confirmation message.\n\nBlocks render in array order and each needs a unique `id` and a `kind`. Input blocks use `kind: \"form-field\"` with `fieldType` (text, email, phone, number, textarea, select, radio, checkbox, consent, hidden), `name` (the custom attribute key), `label`, `placeholder`, `required`, `defaultValue`, `showLabel`, `width` (full or half), `mapsTo` (email, firstName, lastName, phone, customAttribute; defaults to customAttribute), and `options` for choice fields (`[{ value, label, id }]`, where label and id default to value). A hidden field with a `defaultValue` stores that server-owned value and ignores submitted values; a hidden field without one stores the value the page submits. Validation errors name the offending property, for example `blocks[3].options[0].value`.\n", "operationId": "updateSavedForm", "tags": [ "Widgets" ], "parameters": [ { "name": "companyIdOrFormId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The saved form ID to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "listIds": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string" } }, "tagIds": { "type": "array", "maxItems": 200, "items": { "type": "string" }, "description": "Replacement tag IDs. An empty array clears tags." }, "duplicateStrategy": { "type": "string", "enum": [ "skip", "merge", "overwrite" ] }, "resubscribeBehavior": { "type": "string", "enum": [ "reactivate", "double_opt_in" ], "description": "What happens when a contact who unsubscribed from all email submits this form again. `reactivate` resubscribes them and restores the form's lists. `double_opt_in` sends the workspace confirmation email first and resubscribes them when they confirm. Turning it on requires a double opt-in confirmation email and a sender profile, otherwise the request returns 400; if either is removed later, returning unsubscribed contacts stay unsubscribed. Workspace double opt-in always requires confirmation. `duplicateStrategy` never changes subscription status." }, "headline": { "type": "string" }, "description": { "type": "string" }, "buttonText": { "type": "string" }, "successMessage": { "type": "string" }, "redirectUrl": { "type": "string", "description": "HTTP or HTTPS success redirect. An empty string switches back to the confirmation message." }, "theme": { "type": "object", "description": "Visual theme overrides merged into the current theme (accentColor, backgroundColor, textColor, mutedTextColor, cardColor, borderColor as \"#rrggbb\", borderRadius 0-32, headingFontFamily, bodyFontFamily, density).", "additionalProperties": true }, "blocks": { "type": "array", "maxItems": 200, "items": { "type": "object", "additionalProperties": true }, "description": "Full replacement for the form's content blocks." } } } } } }, "responses": { "200": { "description": "Form updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "form": { "$ref": "#/components/schemas/SavedForm" }, "embed": { "allOf": [ { "$ref": "#/components/schemas/SavedFormEmbed" } ], "description": "Included only when the updated form is published." }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid audience, resubscribe behavior, theme, copy target, or content blocks, or `resubscribeBehavior` is `double_opt_in` before the workspace has a double opt-in confirmation email and default sender", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing widgets:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to update form", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Submit signup form", "description": "Submit a public signup form. No API key is required.\n\nWhen the path value is a saved form ID, the form's stored settings are used for audience targeting and success behavior. When the path value is a company ID, this endpoint uses the legacy company-level form behavior.\n\nOmit `lists` to use the workspace default lists setting, provide `lists=` to add the subscriber to no lists, or provide comma-separated list IDs for specific lists. Provide stable `tags` IDs to apply existing tags to the subscriber.\n\nSubmitting again is a fresh opt-in. A contact who unsubscribed from all email is resubscribed and their target list memberships are restored, whatever the `duplicateStrategy`. When the saved form's `resubscribeBehavior` is `double_opt_in`, or workspace double opt-in is on, they receive a confirmation email instead and are resubscribed when they confirm. Contacts whose address bounced or who marked your email as spam are not resubscribed. The response is the same in every case, so it does not reveal whether an address was subscribed.\n", "operationId": "submitSignupForm", "tags": [ "Widgets" ], "security": [], "parameters": [ { "name": "companyIdOrFormId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A saved form ID, or a company ID for legacy generated forms" }, { "name": "lists", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list IDs. Omit for workspace default lists, or provide an empty value for no lists.", "example": "list_abc123,list_def456" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated tag IDs to apply to the subscriber.", "example": "tag_abc123,tag_def456" }, { "name": "duplicateStrategy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "skip", "merge", "overwrite" ], "default": "skip" }, "description": "How to handle profile fields of an existing contact with the submitted email. Use skip to preserve fields, merge to fill missing fields, or overwrite to replace submitted fields. Merge and overwrite require duplicateStrategyToken from the form builder. Does not affect whether an unsubscribed contact is resubscribed.", "example": "merge" }, { "name": "duplicateStrategyToken", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Signed token generated by the form builder for the selected duplicateStrategy. Required for merge or overwrite." } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Subscriber email address" }, "firstName": { "type": "string", "description": "Subscriber first name" }, "lastName": { "type": "string", "description": "Subscriber last name" }, "phone": { "type": "string", "description": "Subscriber phone number in E.164 or US national format. Stored on the base subscriber profile and does not grant SMS consent." }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Subscriber custom attributes. HTML forms can submit individual attributes with bracketed field names such as customAttributes[nickname]." }, "listIds[]": { "x-fern-property-name": "listIdsBracketed", "type": "array", "items": { "type": "string" }, "description": "Existing deployed embed format for repeated list IDs" }, "tagIds[]": { "x-fern-property-name": "tagIdsBracketed", "type": "array", "items": { "type": "string" }, "description": "Existing deployed embed format for repeated tag IDs" }, "duplicateStrategy": { "x-fern-property-name": "bodyDuplicateStrategy", "type": "string", "enum": [ "skip", "merge", "overwrite" ], "default": "skip", "description": "Body alternative to the duplicateStrategy query parameter. Query parameter takes precedence. Merge and overwrite require duplicateStrategyToken." }, "duplicateStrategyToken": { "x-fern-property-name": "bodyDuplicateStrategyToken", "type": "string", "description": "Body alternative to the duplicateStrategyToken query parameter." }, "redirectUrl": { "type": "string", "description": "Http(s) URL or bare domain to redirect to after successful submission", "example": "https://example.com/thank-you" }, "website": { "type": "string", "description": "Honeypot field. Leave empty." } } }, "encoding": { "listIds[]": { "style": "form", "explode": true }, "tagIds[]": { "style": "form", "explode": true } } }, "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Subscriber email address", "example": "user@example.com" }, "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "phone": { "type": "string", "description": "Subscriber phone number in E.164 or US national format. Stored on the base subscriber profile and does not grant SMS consent.", "example": "+12133734253" }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Subscriber custom attributes", "example": { "nickname": "Ace", "zipcode": "19104" } }, "listIds": { "type": "array", "items": { "type": "string" }, "example": [ "list_abc123" ] }, "tagIds": { "type": "array", "items": { "type": "string" }, "description": "Existing tag IDs to apply to the subscriber", "example": [ "tag_abc123", "tag_def456" ] }, "duplicateStrategy": { "type": "string", "enum": [ "skip", "merge", "overwrite" ], "default": "skip", "description": "Body alternative to the duplicateStrategy query parameter. Query parameter takes precedence. Merge and overwrite require duplicateStrategyToken." }, "duplicateStrategyToken": { "type": "string", "description": "Body alternative to the duplicateStrategyToken query parameter." }, "redirectUrl": { "type": "string", "description": "Http(s) URL or bare domain to redirect to after successful submission", "example": "https://example.com/thank-you" }, "website": { "type": "string", "description": "Honeypot field. Leave empty." } } } } } }, "responses": { "200": { "description": "Form submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "303": { "description": "Redirect after successful form submission", "headers": { "Location": { "description": "Configured redirect URL", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Invalid email, invalid redirect URL, or blocked address", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Please enter a valid email address" } } } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid form configuration" } } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests. Please try again later." } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred. Please try again." } } } } } } } } }, "/forms/{companyIdOrFormId}/embed.js": { "get": { "summary": "Get saved signup form embed script", "description": "Load a saved signup form with one line of JavaScript. No API key is required.\n\nThe script renders the current saved form settings when the page loads, so dashboard edits apply to deployed JavaScript embeds without copying new HTML.\n", "operationId": "getSavedSignupFormEmbedScript", "tags": [ "Widgets" ], "security": [], "parameters": [ { "name": "companyIdOrFormId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The saved form ID" } ], "responses": { "200": { "description": "JavaScript embed runtime for the saved form", "content": { "application/javascript": { "schema": { "type": "string" }, "example": "(function () {\n var currentScript = document.currentScript;\n})();\n" } } }, "404": { "description": "Form or company not found", "content": { "application/javascript": { "schema": { "type": "string" }, "example": "console.warn('Invalid Sequenzy form configuration.');" } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/forms/{companyIdOrFormId}/{formId}/embed.js": { "get": { "summary": "Get saved signup form embed script by company", "description": "Compatibility path for saved signup form embed scripts. New embeds should use `/forms/{formId}/embed.js`.\n\nThe script renders the current saved form settings when the page loads, so dashboard edits apply to deployed JavaScript embeds without copying new HTML.\n", "operationId": "getCompanyScopedSavedSignupFormEmbedScript", "tags": [ "Widgets" ], "security": [], "parameters": [ { "name": "companyIdOrFormId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company ID the form belongs to" }, { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The saved form ID" } ], "responses": { "200": { "description": "JavaScript embed runtime for the saved form", "content": { "application/javascript": { "schema": { "type": "string" }, "example": "(function () {\n var currentScript = document.currentScript;\n})();\n" } } }, "404": { "description": "Form or company not found", "content": { "application/javascript": { "schema": { "type": "string" }, "example": "console.warn('Invalid Sequenzy form configuration.');" } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/forms/{companyIdOrFormId}/{formId}": { "post": { "summary": "Submit saved signup form by company", "description": "Compatibility path for saved signup form submissions. New embeds should use `/forms/{formId}`.\n\nThe form's stored settings are the source of truth for audience targeting (lists, tags) and success behavior (success message or redirect URL), so dashboard edits apply to deployed embeds without re-embedding. List, tag, and redirect values in the request are ignored.\n", "operationId": "submitCompanyScopedSavedSignupForm", "tags": [ "Widgets" ], "security": [], "parameters": [ { "name": "companyIdOrFormId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The company ID the form belongs to" }, { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The saved form ID" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Subscriber email address" }, "firstName": { "type": "string", "description": "Subscriber first name" }, "lastName": { "type": "string", "description": "Subscriber last name" }, "phone": { "type": "string", "description": "Subscriber phone number in E.164 or US national format, when configured on the saved form. Stored on the base subscriber profile and does not grant SMS consent." }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Subscriber custom attributes for custom fields configured on the saved form. HTML forms can submit individual attributes with bracketed field names such as customAttributes[nickname]." }, "listIds[]": { "x-fern-property-name": "listIdsBracketed", "type": "array", "items": { "type": "string" }, "description": "Ignored for saved forms. Stored form settings are used." }, "tagIds[]": { "x-fern-property-name": "tagIdsBracketed", "type": "array", "items": { "type": "string" }, "description": "Ignored for saved forms. Stored form settings are used." }, "duplicateStrategy": { "type": "string", "enum": [ "skip", "merge", "overwrite" ], "description": "Ignored for saved forms. Stored form settings are used." }, "duplicateStrategyToken": { "type": "string", "description": "Ignored for saved forms. Stored form settings are used." }, "redirectUrl": { "type": "string", "description": "Ignored for saved forms. Stored form settings are used." }, "website": { "type": "string", "description": "Honeypot field. Leave empty." } } }, "encoding": { "listIds[]": { "style": "form", "explode": true }, "tagIds[]": { "style": "form", "explode": true } } }, "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Subscriber email address", "example": "user@example.com" }, "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "phone": { "type": "string", "description": "Subscriber phone number in E.164 or US national format, when configured on the saved form. Stored on the base subscriber profile and does not grant SMS consent.", "example": "+12133734253" }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Subscriber custom attributes for custom fields configured on the saved form", "example": { "nickname": "Ace", "favorite_fruit": "Mango" } }, "listIds": { "type": "array", "items": { "type": "string" }, "description": "Ignored for saved forms. Stored form settings are used." }, "listIds[]": { "x-fern-property-name": "listIdsBracketed", "type": "array", "items": { "type": "string" }, "description": "Ignored for saved forms. Stored form settings are used." }, "tagIds": { "type": "array", "items": { "type": "string" }, "description": "Ignored for saved forms. Stored form settings are used." }, "tagIds[]": { "x-fern-property-name": "tagIdsBracketed", "type": "array", "items": { "type": "string" }, "description": "Ignored for saved forms. Stored form settings are used." }, "duplicateStrategy": { "type": "string", "enum": [ "skip", "merge", "overwrite" ], "description": "Ignored for saved forms. Stored form settings are used." }, "duplicateStrategyToken": { "type": "string", "description": "Ignored for saved forms. Stored form settings are used." }, "redirectUrl": { "type": "string", "description": "Ignored for saved forms. Stored form settings are used." }, "website": { "type": "string", "description": "Honeypot field. Leave empty." } } } } } }, "responses": { "200": { "description": "Form submitted successfully. Native HTML form posts that accept `text/html` receive a hosted confirmation page showing the form's success message instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } }, "text/html": { "schema": { "type": "string", "description": "Hosted confirmation page for native HTML form posts" } } } }, "303": { "description": "Redirect after successful form submission, using the redirect URL stored in the form's settings", "headers": { "Location": { "description": "Configured redirect URL", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Invalid email or blocked address", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Please enter a valid email address" } } } } } }, "404": { "description": "Form not found for this company", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid form configuration" } } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests. Please try again later." } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred. Please try again." } } } } } } } } }, "/forms/popups/{popupId}": { "post": { "summary": "Submit saved popup", "description": "Submit a saved popup without an API key. The popup's stored content is the source of truth for audience targeting, duplicate handling, resubscribe behavior, custom fields, and success behavior.\n\nA contact who unsubscribed from all email is resubscribed and their target list memberships are restored. When the popup's `resubscribeBehavior` is `double_opt_in`, or workspace double opt-in is on, they receive a confirmation email instead. The response does not reveal which case applied.\n", "operationId": "submitSavedPopup", "tags": [ "Widgets" ], "security": [], "parameters": [ { "name": "popupId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The saved popup ID" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Subscriber email address" }, "firstName": { "type": "string", "description": "Subscriber first name, when configured on the popup" }, "lastName": { "type": "string", "description": "Subscriber last name, when configured on the popup" }, "phone": { "type": "string", "description": "Subscriber phone number in E.164 or US national format, when configured on the popup. Stored on the base subscriber profile and does not grant SMS consent." }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Subscriber custom attributes for custom fields configured on the popup. HTML forms can submit individual attributes with bracketed field names such as customAttributes[company_size]." }, "website": { "type": "string", "description": "Honeypot field. Leave empty." } } } }, "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Subscriber email address", "example": "user@example.com" }, "firstName": { "type": "string", "example": "Jane" }, "lastName": { "type": "string", "example": "Doe" }, "phone": { "type": "string", "description": "Subscriber phone number in E.164 or US national format, when configured on the popup. Stored on the base subscriber profile and does not grant SMS consent.", "example": "+12133734253" }, "customAttributes": { "type": "object", "additionalProperties": true, "description": "Subscriber custom attributes for custom fields configured on the popup", "example": { "company_size": "42" } }, "website": { "type": "string", "description": "Honeypot field. Leave empty." } } } } } }, "responses": { "200": { "description": "Popup submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "redirectUrl": { "type": "string", "format": "uri", "description": "Present when the popup is configured to redirect after submission" } } } } } }, "400": { "description": "Invalid email, required field missing, or blocked address", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Please enter a valid email address" } } } } } }, "404": { "description": "Popup not found or not published", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid popup configuration" } } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests. Please try again later." } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred. Please try again." } } } } } } } } }, "/widgets/popup.js": { "get": { "summary": "Get popup widget runtime", "description": "Load the hosted JavaScript runtime for popup signup widgets. No API key is required.", "operationId": "getPopupWidgetRuntime", "tags": [ "Widgets" ], "security": [], "responses": { "200": { "description": "JavaScript runtime", "content": { "application/javascript": { "schema": { "type": "string" }, "example": "(function () {\n \"use strict\";\n})();\n" } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/widgets/preferences/token": { "post": { "summary": "Get preferences widget token", "description": "Generate a signed token to embed the subscription preferences widget for a subscriber.\nThis token allows users to manage their email subscription preferences directly from your website.\n\n**Important:** Call this endpoint from your backend only. Never expose your API key to the frontend.\n", "operationId": "getPreferencesToken", "tags": [ "Widgets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "The subscriber's email address", "example": "user@example.com" } } } } } }, "responses": { "200": { "description": "Token generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "token": { "type": "string", "description": "Signed JWT token (valid for 1 hour)", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } } } }, "400": { "description": "Invalid email format", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "Invalid email format" } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Invalid API key" } } } } } } } }, "404": { "description": "Subscriber not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "NOT_FOUND" }, "message": { "type": "string", "example": "Subscriber not found" } } } } } } } }, "500": { "description": "Server configuration error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/subscribers/attributes": { "get": { "summary": "List subscriber attributes", "description": "Lists the custom attribute names in use across the account, so you can reuse existing names and value types when creating or updating subscribers. Value types and examples come from up to 100 recent contacts with custom attributes. Names that only older contacts carry come from the account-wide attribute index, which returns up to the 500 most widely used names, and are included with sampledContacts 0 and the type of their indexed example (a boolean is reported for an example of \"true\" or \"false\"). Reserved profile fields (email, first and last name) and internal attributes are not listed. Requires subscribers:read.", "operationId": "listSubscriberAttributes", "tags": [ "Subscribers" ], "parameters": [ { "name": "includeNested", "in": "query", "required": false, "description": "Also list nested paths such as profile.tier. Must be true or false. Defaults to false.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Attributes in use across the account", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "attributes", "sampledContacts" ], "properties": { "success": { "type": "boolean", "example": true }, "attributes": { "type": "array", "description": "Attributes seen on the sampled contacts, most common first, followed by names only older contacts carry.", "items": { "type": "object", "required": [ "key", "valueType", "isArray", "mixedTypes", "sampleValue", "sampledContacts" ], "properties": { "key": { "type": "string", "description": "Attribute name, or a dot path for nested attributes.", "example": "zip" }, "valueType": { "type": "string", "enum": [ "string", "number", "boolean" ], "description": "JSON type of the example value. For a list attribute, the type of its items. string when mixedTypes is true.", "example": "string" }, "isArray": { "type": "boolean", "description": "Whether the attribute holds a list of values on the sampled contacts. Always false for names that only older contacts carry, because the attribute index does not record list shape.", "example": false }, "mixedTypes": { "type": "boolean", "description": "True when sampled contacts hold different types for this attribute, for example zip codes stored as numbers on some contacts and strings on others. valueType is then string, the only type that keeps every value intact.", "example": false }, "sampleValue": { "type": [ "string", "null" ], "description": "An example value as text, truncated to 50 characters. List examples from sampled contacts show up to three items. Null when no example is available.", "example": "02134" }, "sampledContacts": { "type": "integer", "description": "How many of the sampled contacts carry the attribute. 0 when only older contacts carry it.", "example": 42 } } } }, "sampledContacts": { "type": "integer", "description": "Recent contacts with custom attributes that were sampled.", "example": 100 } } } } } }, "400": { "description": "includeNested is not true or false", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks subscribers:read or the company role does not allow it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The attributes could not be read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/subscribers/me": { "get": { "summary": "Get account info", "description": "Returns account information for the authenticated API key. Useful for connection labels in integrations.", "operationId": "getAccountInfo", "tags": [ "Subscribers" ], "responses": { "200": { "description": "Account info retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "account": { "type": "object", "properties": { "companyId": { "type": "string", "example": "company_abc123" }, "companyName": { "type": "string", "example": "Acme Inc" }, "apiKeyType": { "type": [ "string", "null" ], "enum": [ "company", "personal", null ], "description": "API key ownership type. Workspace-bound integrations should require company so requests cannot silently select another workspace." } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/account": { "get": { "operationId": "getAccount", "summary": "Get account", "description": "Returns the companies available to the authenticated API key, the currently selected company, and a read-only summary of the key's own permissions.", "tags": [ "Account" ], "responses": { "200": { "description": "Account context returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "user": { "type": "object", "properties": { "id": { "type": "string", "example": "user_abc123" } } }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "description": "Account-key access role. Viewer access remains read-only regardless of key scopes; marketer access is limited to marketing scopes (no transactional, settings, integration, webhook, team, or API-key scopes).", "enum": [ "owner", "admin", "marketer", "viewer" ] } } } }, "currentCompanyId": { "type": [ "string", "null" ] }, "apiKeyPermissions": { "type": "object", "description": "Read-only identity and permission metadata for the authenticated key, including a recovery URL. This does not bypass resource scopes.", "properties": { "activeKey": { "type": "object", "description": "Non-secret identity of the bearer key that authenticated this request. Use it to verify that a restarted client loaded the intended replacement key.", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": [ "string", "null" ], "description": "Stored non-secret key prefix, such as seq_live_A or seq_user_B. Pair it with the key name and ID when verifying a replacement credential." }, "type": { "type": [ "string", "null" ], "enum": [ "company", "personal", null ] } } }, "preset": { "type": "string", "enum": [ "full_access", "read_only", "agent_safe", "ai_drafting", "data_ingest_safe", "data_ingest_automations", "transactional_sender", "marketing_sender", "custom" ] }, "fullAccess": { "type": "boolean" }, "selectedScopeCount": { "type": "integer", "description": "Number of currently defined scopes enabled for the key. For full-access keys this equals currentScopeCount, while fullAccess still indicates future-scope access." }, "currentScopeCount": { "type": "integer", "description": "Total number of permission scopes defined when the response was generated." }, "description": { "type": "string", "description": "Human-readable explanation of the effective permission selection." }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "canDiscoverMarketingWork": { "type": "boolean", "description": "Whether the key can read campaigns, sequences, and landing pages." }, "missingMarketingReadScopes": { "type": "array", "items": { "type": "string" } }, "canSendLive": { "type": "boolean", "description": "Whether the key holds any scope that delivers to a real person. False for drafting-only keys, which can create and update content but cannot send it." }, "missingLiveDeliveryScopes": { "type": "array", "description": "Live-delivery scopes the key does not hold, such as transactional:send for one-to-one sends or campaigns:send for campaigns. Drafting permission such as transactional:write does not imply delivery.", "items": { "type": "string" } }, "liveDeliveryBlockedByRole": { "type": "boolean", "description": "Whether the authenticated user's role in the selected workspace blocks every kind of sending regardless of key scopes. Personal keys held by a viewer are read-only, so widening the key's permissions does not enable delivery; the role has to change. A marketer is not blocked here because they can still send campaigns; their transactional restriction is listed in roleRestrictedScopes." }, "roleRestrictedScopes": { "type": "array", "description": "Scopes the authenticated user's workspace role cannot use through a personal key, such as transactional:send or team:manage for a marketer. Empty for owners, admins, and company keys.", "items": { "type": "string" } }, "manageUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Direct management URL for the authenticated key. Personal keys open Account API Keys; company keys open the selected workspace's API Keys settings." } } }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "description": "Lists company-scoped API keys as non-secret metadata. The caller must have the `api_keys:manage` permission. Account-scoped keys select the company with the x-company-id header. Plain key values and stored hashes are never returned.", "tags": [ "Account" ], "responses": { "200": { "description": "API key metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "apiKeys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyMetadata" } } }, "required": [ "success", "apiKeys" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required API key management permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "operationId": "createApiKey", "summary": "Create API key", "description": "Creates a company-scoped API key. The caller must have the `api_keys:manage` permission. Account-scoped keys select the target company with the x-company-id header; companyId in the JSON body is not a supported selector. The plain key is returned only once.", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Human-readable key name." }, "preset": { "type": "string", "description": "Permission preset to apply when scopes is omitted. Defaults to full_access. Full-access keys are stored with scopes set to null, meaning all current and future permissions.", "enum": [ "full_access", "read_only", "agent_safe", "ai_drafting", "data_ingest_safe", "data_ingest_automations", "transactional_sender", "marketing_sender" ] }, "scopes": { "type": "array", "description": "Explicit permission scopes for the new key. Overrides preset when provided.", "minItems": 1, "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "API key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "apiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key": { "type": "string", "description": "Plain API key. This is shown only on creation." }, "prefix": { "type": "string" }, "scopes": { "type": [ "array", "null" ], "description": "Explicit permission scopes, or null for full access.", "items": { "type": "string" } }, "permissions": { "type": "object", "description": "Effective permission receipt for the newly created key. Only scopes set to null grant current and future full access.", "properties": { "preset": { "type": "string", "description": "Effective preset derived from the stored scopes. An explicit all-current-scopes array is custom, not full_access." }, "fullAccess": { "type": "boolean" }, "selectedScopeCount": { "type": "integer" }, "currentScopeCount": { "type": "integer" }, "description": { "type": "string" } } }, "createdAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" }, "instructions": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Invalid permission preset or scope list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required API key management permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "API key could not be created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api-key-handoff": { "post": { "operationId": "requestApiKeyHandoff", "summary": "Request API key handoff", "description": "Builds a dashboard link that opens the create-key form prefilled with a suggested name and permissions. Requires only `account:read`, because it creates nothing, changes nothing, and returns no secret - the new key is issued in the owner's authenticated browser session. Use it when key management is blocked because the calling key lacks `api_keys:manage`, which cannot be granted through the API by the key that is missing it. Pass replaceApiKeyId to rotate; the dashboard then offers to revoke the predecessor once the replacement exists.", "tags": [ "Account" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Suggested name for the new key. Trimmed to 80 characters in the link." }, "preset": { "type": "string", "description": "Suggested permission preset.", "enum": [ "full_access", "read_only", "agent_safe", "ai_drafting", "data_ingest_safe", "data_ingest_automations", "transactional_sender", "marketing_sender" ] }, "scopes": { "type": "array", "description": "Suggested explicit permission scopes. Overrides preset when provided.", "minItems": 1, "items": { "type": "string" } }, "replaceApiKeyId": { "type": "string", "description": "ID of the key the new one replaces. Pass the literal string \"current\" for the key making the request." } } } } } }, "responses": { "200": { "description": "Handoff link prepared", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "handoff": { "type": "object", "properties": { "url": { "type": "string", "description": "Dashboard URL that opens the create-key form prefilled with the request." }, "manageUrl": { "type": "string", "description": "The plain API Keys settings URL, without the prefill." }, "keyType": { "type": "string", "description": "Whether the link targets workspace or account API key settings.", "enum": [ "company", "personal" ] }, "name": { "type": [ "string", "null" ] }, "preset": { "type": [ "string", "null" ] }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "permissions": { "type": [ "object", "null" ], "description": "Permission receipt for the suggested selection. Null when the request suggested no preset and no scopes, because the form then opens on the dashboard default.", "additionalProperties": true }, "replaces": { "type": [ "object", "null" ], "description": "The key being replaced. name and prefix are populated only when it is the key making the request.", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": [ "string", "null" ] }, "isCurrentKey": { "type": "boolean" } } }, "canSelfServe": { "type": "boolean", "description": "True when the calling key already holds api_keys:manage and could create the replacement directly." }, "deliversKeyToCaller": { "type": "boolean", "description": "Always false. The new key is shown in the browser and never returned through this endpoint." } } }, "message": { "type": "string" }, "nextSteps": { "type": "array", "items": { "type": "string" } } }, "required": [ "success", "handoff" ] } } } }, "400": { "description": "Invalid permission preset, scope list, or replaceApiKeyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required account read permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api-keys/{apiKeyId}": { "patch": { "operationId": "updateApiKey", "summary": "Update API key", "description": "Renames a company-scoped API key and/or replaces its permissions in place. The caller must have the `api_keys:manage` permission. The key value is unchanged. Added permissions apply on the next retry; removed permissions may remain usable for up to five minutes while API caches expire. `preset` and `scopes` replace the whole selection rather than merging into it. The response contains non-secret metadata only.", "tags": [ "Account" ], "parameters": [ { "name": "apiKeyId", "in": "path", "required": true, "description": "Exact API key ID returned by the list API keys endpoint.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Provide at least one of name, preset, or scopes.", "properties": { "name": { "type": "string", "description": "New human-readable key name." }, "preset": { "type": "string", "description": "Replacement permission preset. Full-access keys are stored with scopes set to null, meaning all current and future permissions.", "enum": [ "full_access", "read_only", "agent_safe", "ai_drafting", "data_ingest_safe", "data_ingest_automations", "transactional_sender", "marketing_sender" ] }, "scopes": { "type": "array", "description": "Replacement explicit permission scopes. Overrides preset when provided.", "minItems": 1, "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "API key updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "apiKey": { "$ref": "#/components/schemas/ApiKeyMetadata" }, "message": { "type": "string", "example": "API key permissions updated. Added permissions apply on the next retry; removed permissions may take up to five minutes to expire across API instances." } }, "required": [ "success", "apiKey", "message" ] } } } }, "400": { "description": "Nothing to update, or an invalid permission preset or scope list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required API key management permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "API key not found for the selected company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "revokeApiKey", "summary": "Revoke API key", "description": "Permanently revokes a company-scoped API key. The caller must have the `api_keys:manage` permission. The response contains non-secret metadata only.", "tags": [ "Account" ], "parameters": [ { "name": "apiKeyId", "in": "path", "required": true, "description": "Exact API key ID returned by the list API keys endpoint.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "apiKey": { "$ref": "#/components/schemas/ApiKeyMetadata" }, "message": { "type": "string", "example": "API key revoked successfully." } }, "required": [ "success", "apiKey", "message" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required API key management permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "API key not found for the selected company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/integration-guide": { "post": { "operationId": "getIntegrationGuide", "summary": "Get integration guide", "description": "Returns a framework-specific code example and implementation tip for common integration use cases.", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "framework": { "type": "string", "example": "nextjs" }, "use_case": { "type": "string", "example": "transactional" } } } } } }, "responses": { "200": { "description": "Integration guide returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "framework": { "type": "string" }, "use_case": { "type": "string" }, "code": { "type": "string" }, "tip": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/feedback": { "post": { "operationId": "submitFeedback", "summary": "Submit feedback", "description": "Submits product feedback about Sequenzy itself to the Sequenzy team - for example, when a workflow you or your user needed is not exposed via the API, CLI, or MCP server.", "tags": [ "Feedback" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "The feedback itself. Be specific about what was needed and what was missing or wrong.", "example": "There is no endpoint to bulk-delete campaigns by label." }, "category": { "type": "string", "enum": [ "missing_capability", "bug", "docs", "ux", "praise", "other" ], "description": "Feedback category. Use missing_capability when a needed workflow is not supported. Defaults to other." }, "source": { "type": "string", "enum": [ "api", "cli", "mcp" ], "description": "Where the feedback was submitted from. Defaults to api." }, "context": { "type": "string", "maxLength": 10000, "description": "Optional description of what you were trying to accomplish when you hit the gap." }, "userIntent": { "type": "string", "maxLength": 5000, "description": "For bug or wrong-outcome reports - the user's request, verbatim or closely paraphrased. Omit personal data not needed to reproduce the problem.", "example": "Move the promo send to 9am Tuesday" }, "toolCalls": { "type": "array", "maxItems": 25, "description": "For bug or wrong-outcome reports - the ordered API calls, CLI commands, or MCP tool calls that led to the problem. Summarize arguments; do not include raw subscriber data.", "items": { "type": "object", "additionalProperties": false, "required": [ "tool" ], "properties": { "tool": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Tool, command, or endpoint name.", "example": "update_campaign" }, "args": { "type": "string", "maxLength": 2000, "description": "Short summary of the arguments used." }, "error": { "type": "string", "maxLength": 2000, "description": "Error returned by this call, if any." } } } }, "expected": { "type": "string", "maxLength": 5000, "description": "What you expected to happen." }, "actual": { "type": "string", "maxLength": 5000, "description": "What actually happened instead." }, "resourceIds": { "type": "array", "maxItems": 50, "description": "IDs of the affected resources so the team can correlate the report with server logs.", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "example": [ "cmp_123" ] } } } } } }, "responses": { "200": { "description": "Feedback received", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Feedback received. The Sequenzy team reviews every submission." } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No company selected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Feedback could not be delivered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/companies": { "get": { "operationId": "listCompanies", "summary": "List companies", "description": "Lists companies available to the authenticated API key.", "tags": [ "Companies" ], "responses": { "200": { "description": "Companies returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "currentCompanyId": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "operationId": "createCompany", "summary": "Create company", "description": "Creates a company workspace, optionally without a website, and can queue the onboarding welcome sequence. Requires a personal account key (seq_user_...). Company-scoped keys (seq_live_... and legacy ek_... keys) are bound to a single company and are rejected with 403, because they could never access the workspace they created.", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Company display name. If omitted, Sequenzy derives it from the domain." }, "domain": { "type": "string", "description": "Company website domain or URL. Required unless noWebsite is true. When both are sent, the domain is used." }, "noWebsite": { "type": "boolean", "description": "Create a ready workspace without a website. Requires name when no domain is sent. Ignored when a non-blank domain is sent." }, "description": { "type": "string", "maxLength": 500, "description": "Optional business description used as context for welcome-sequence generation. Without a website, a non-null value that is not a string of up to 500 characters returns 400; with a domain it is ignored, and website processing may replace the stored description." }, "withWelcomeSequence": { "type": "boolean", "description": "Set true to create a draft four-email welcome sequence and queue its generation. Defaults to false; any other value is treated as false." } } } } } }, "responses": { "200": { "description": "Company created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "websiteUrl": { "type": [ "string", "null" ] } } }, "welcomeAutomationId": { "type": [ "string", "null" ] }, "welcomeEnrichmentJobId": { "type": [ "string", "null" ] }, "message": { "type": "string" } } } } } }, "400": { "description": "Missing domain without noWebsite, or a no-website request without a name or with a description that is not a string of up to 500 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key is scoped to a single company and cannot create another one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "This API key is scoped to a single company, so it cannot create another one. Retry with a personal account key (seq_user_...) from Account -> API Keys, or create the company in the dashboard.", "code": "COMPANY_CREATE_REQUIRES_PERSONAL_KEY" } } } }, "422": { "description": "domain or name is not a string", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestValidationError" } } } }, "500": { "description": "Company could not be created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/companies/{companyId}": { "get": { "operationId": "getCompany", "summary": "Get company", "description": "Returns one company workspace that the authenticated key can access.", "tags": [ "Companies" ], "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ID" } ], "responses": { "200": { "description": "Company returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "company": { "$ref": "#/components/schemas/Company" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "operationId": "updateCompany", "summary": "Update company", "description": "Updates product info, brand context, the default email theme, reply-tracking settings, the workspace default lists, and account-wide From/Reply-To defaults. New profiles are created as needed; From addresses require a verified sending domain. Requires the company_profile:manage scope; the sending-identity, reply-tracking, and defaultSubscriberListIds fields additionally require companies:manage.", "tags": [ "Companies" ], "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "renameMatchingFooters": { "type": "boolean", "default": false, "description": "With name and previousCompanyName, atomically rename exact matching footer company names in editable emails and saved components. Preserves custom names, body copy, sent or sending campaigns and active A/B tests. Null is not accepted. This option additionally requires emails:write, templates:write, campaigns:write, sequences:write, transactional:write and ab_tests:write; personal keys require owner/admin access." }, "previousCompanyName": { "type": "string", "description": "Required when renameMatchingFooters is true. Current company name from GET company. A stale name returns 409; retrying a completed rename does not repeat footer changes." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "founderName": { "type": [ "string", "null" ] }, "primaryColor": { "type": "string", "description": "6-digit hex color, for example" }, "brandColors": { "type": [ "object", "null" ], "additionalProperties": true }, "valueProps": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "testimonials": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": true } }, "toneVoice": { "type": [ "string", "null" ] }, "companyContext": { "type": [ "string", "null" ] }, "emailDesignPrompt": { "type": [ "string", "null" ], "description": "Art direction for AI-designed emails: layout, density, which sections belong in an email, imagery, and CTA prominence. `toneVoice` steers copy; this steers design. When empty, the next email generation prefills it with the direction derived from the brand; null clears it so the next generation writes a fresh one." }, "emailLengthPreference": { "type": "string", "enum": [ "concise", "balanced", "detailed" ], "description": "How long AI-written email copy should be. New workspaces default to `concise`." }, "socialLinks": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "privacyPolicyUrl": { "type": [ "string", "null" ] }, "termsUrl": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "pricing": { "type": [ "object", "null" ], "additionalProperties": true }, "fontFamily": { "type": [ "string", "null" ] }, "emailTheme": { "type": [ "object", "null" ], "description": "Default email theme. Partial update - omitted fields keep their current value (or the preset default) and numeric values are clamped to supported ranges. Pass null to reset to the platform default theme.", "additionalProperties": false, "properties": { "presetId": { "type": "string", "enum": [ "default", "soft", "editorial", "bold" ] }, "buttonStyle": { "type": "string", "enum": [ "solid", "outline" ], "description": "How primary buttons are filled. \"outline\" renders them as a transparent box with a brand-color border; \"solid\" (default) is the classic filled button." }, "colors": { "type": "object", "description": "6-digit hex values.", "additionalProperties": false, "properties": { "primary": { "type": "string" }, "background": { "type": "string", "description": "Outer canvas behind the email." }, "content": { "type": "string", "description": "Inner content card. Omit to preserve its current effective color." }, "surface": { "type": "string", "description": "Nested cards and tinted tiles." }, "text": { "type": "string" }, "mutedText": { "type": "string" }, "heading": { "type": "string" }, "border": { "type": "string" }, "link": { "type": "string" }, "buttonText": { "type": "string", "description": "Label color for solid buttons. Omit to auto-derive a readable color from the button background." } } }, "typography": { "type": "object", "description": "Numeric type settings.", "additionalProperties": false, "properties": { "baseFontSize": { "type": "number" }, "leadFontSize": { "type": "number" }, "baseLineHeight": { "type": "number" }, "heading1Size": { "type": "number" }, "heading2Size": { "type": "number" }, "heading3Size": { "type": "number" }, "buttonFontSize": { "type": "number" }, "buttonFontWeight": { "type": "number", "description": "CTA label weight, clamped to 400-800." }, "headingFontWeight": { "type": "number", "description": "Heading weight applied to all heading levels, clamped to 300-900. Omit for the per-level defaults." }, "headingFontFamily": { "type": "string", "description": "Font stack for headings when it differs from the email body font. Omit so headings inherit the email font." }, "headingLetterSpacing": { "type": "number", "description": "Heading letter spacing in pixels (negative = tighter), clamped to -2..4. Omit for natural tracking." } } }, "layout": { "type": "object", "description": "Numeric layout settings.", "additionalProperties": false, "properties": { "contentWidth": { "type": "number" }, "containerPaddingX": { "type": "number" }, "containerPaddingY": { "type": "number" }, "blockSpacing": { "type": "number" }, "baseRadius": { "type": "number" }, "sectionPadding": { "type": "number" }, "buttonPaddingX": { "type": "number" }, "buttonPaddingY": { "type": "number" }, "borderedBlockPadding": { "type": "number" } } } } }, "emailDirection": { "type": "string", "enum": [ "ltr", "rtl" ] }, "senderProfileId": { "type": "string", "description": "Existing sender profile to make the account-wide default, and the profile fromName renames. List IDs with GET /v1/sender-profiles. Mutually exclusive with fromEmail." }, "fromEmail": { "type": "string", "format": "email", "description": "Account-wide default From address. The domain must be configured and verified." }, "fromName": { "type": "string", "description": "Display name of the default From profile. Sent on its own it renames the current default profile; with senderProfileId it renames that profile; with fromEmail it names the profile for that address. If the address already carries several display names, the request is rejected - pass senderProfileId to say which one to rename." }, "replyProfileId": { "type": "string", "description": "Existing reply profile to make the account-wide default, and the profile replyToName renames. Mutually exclusive with replyTo." }, "replyTo": { "type": "string", "format": "email", "description": "Account-wide default Reply-To address. A reply profile is created when needed." }, "replyToName": { "type": "string", "description": "Display name of the default Reply-To profile. Sent on its own it renames the current default profile; with replyProfileId it renames that profile; with replyTo it names the profile for that address." }, "replyTrackingEnabled": { "type": "boolean", "description": "Enable or disable inbound reply capture." }, "replyTrackingDomainMode": { "type": "string", "enum": [ "sequenzy", "custom" ], "description": "Use Sequenzy's managed inbound domain or a configured custom domain." }, "forwardReplies": { "type": "boolean", "description": "Enable or disable forwarding captured replies to the configured mailbox." }, "defaultSubscriberListIds": { "type": [ "array", "null" ], "maxItems": 100, "items": { "type": "string" }, "description": "Which lists new contacts join when something creates a subscriber without explicit list targeting - forms, API writes, events, tag actions, imports, and any integration without its own list targeting. null means every current and future list, [] means no list at all, and an array means exactly those lists. Unknown or foreign list IDs are rejected rather than skipped. Applies only to later writes; nobody is moved or removed retroactively. Requires the companies:manage scope." } } } } } }, "responses": { "200": { "description": "Company updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "company": { "$ref": "#/components/schemas/Company" } } } } } }, "400": { "description": "Invalid update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Sending-identity fields were sent without the companies:manage scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Company name changed since the footer rename was confirmed. Refresh company details and confirm again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shopify/automation-settings": { "get": { "operationId": "getShopifyAutomationSettings", "summary": "Get Shopify automation settings", "description": "Returns the connected Shopify store's browse-abandonment, cart-abandonment, and price-drop automation settings, with platform defaults applied where the store hasn't overridden them.", "tags": [ "Shopify" ], "responses": { "200": { "description": "Automation settings returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "integrationId": { "type": "string" }, "shopDomain": { "type": "string" }, "browseAbandonment": { "$ref": "#/components/schemas/ShopifyBrowseAbandonmentSettings" }, "cartAbandonment": { "$ref": "#/components/schemas/ShopifyCartAbandonmentSettings" }, "priceDrop": { "$ref": "#/components/schemas/ShopifyPriceDropSettings" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No active Shopify integration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "put": { "operationId": "updateShopifyAutomationSettings", "summary": "Update Shopify automation settings", "description": "Partial update of the store's browse-abandonment, cart-abandonment, and/or price-drop settings: omitted sections are untouched, omitted fields keep their current value, and null resets a section to the platform defaults.", "tags": [ "Shopify" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "browseAbandonment": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ShopifyBrowseAbandonmentSettings" } ] }, { "type": "null" } ] }, "cartAbandonment": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ShopifyCartAbandonmentSettings" } ] }, { "type": "null" } ] }, "priceDrop": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ShopifyPriceDropSettings" } ] }, { "type": "null" } ] } } }, "examples": { "raise-price-drop-threshold": { "summary": "Alert only on 10%+ drops", "value": { "priceDrop": { "minPercent": 10 } } }, "disable-browse-abandonment": { "summary": "Turn off browse abandonment", "value": { "browseAbandonment": { "enabled": false } } }, "lengthen-cart-inactivity": { "summary": "Wait 2h of cart inactivity", "value": { "cartAbandonment": { "delayHours": 2 } } }, "reset-price-drop": { "summary": "Reset price drop to defaults", "value": { "priceDrop": null } } } } } }, "responses": { "200": { "description": "Automation settings updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "integrationId": { "type": "string" }, "shopDomain": { "type": "string" }, "browseAbandonment": { "$ref": "#/components/schemas/ShopifyBrowseAbandonmentSettings" }, "cartAbandonment": { "$ref": "#/components/schemas/ShopifyCartAbandonmentSettings" }, "priceDrop": { "$ref": "#/components/schemas/ShopifyPriceDropSettings" } } } } } }, "400": { "description": "No settings provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No active Shopify integration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request body failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "validation" }, "on": { "type": "string", "example": "body" }, "property": { "type": "string", "example": "/cartAbandonment/delayHours" }, "message": { "type": "string", "example": "Expected number to be less or equal to 168" }, "summary": { "type": "string", "example": "Property 'delayHours' should be less or equal to 168" }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/sync-rules": { "get": { "operationId": "getSyncRules", "summary": "Get sync rules", "description": "Returns the company's effective sync rules - the automatic tag changes applied when events fire. New companies start with an empty rule set; legacy companies may inherit the optional SaaS/ecommerce platform preset. isDefault reports whether that preset is active.", "tags": [ "Sync Rules" ], "responses": { "200": { "description": "Sync rules returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "syncRules": { "type": "array", "items": { "$ref": "#/components/schemas/SyncRule" } }, "isDefault": { "type": "boolean", "description": "True while the company still uses the platform default rules." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "put": { "operationId": "updateSyncRules", "summary": "Update sync rules", "description": "Replaces the company's full sync rule set. Send an empty array to disable rules, or null to opt into the inherited SaaS/ecommerce platform preset. This is not a partial update - fetch the current rules, edit them, and send the whole set back.", "tags": [ "Sync Rules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "syncRules" ], "properties": { "syncRules": { "type": [ "array", "null" ], "description": "Full replacement rule set. An empty array disables rules; null opts into the inherited SaaS/ecommerce platform preset.", "items": { "$ref": "#/components/schemas/SyncRule" } } } }, "examples": { "tag-buyers-by-product": { "summary": "Tag buyers of a product tag", "value": { "syncRules": [ { "triggerEvent": "ecommerce.order_placed", "actions": { "addTags": [ "vinyl-collector" ], "removeTags": [] }, "conditions": { "purchasedProduct": { "tags": [ "Vinyl" ] } } } ] } }, "use-platform-preset": { "summary": "Opt into the SaaS/ecommerce platform preset", "value": { "syncRules": null } } } } } }, "responses": { "200": { "description": "Sync rules updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Saved 1 sync rule." }, "syncRules": { "type": "array", "items": { "$ref": "#/components/schemas/SyncRule" } }, "isDefault": { "type": "boolean" } } } } } }, "400": { "description": "Invalid rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/email-ai-style": { "get": { "operationId": "getEmailAiStyle", "summary": "Get saved AI email style", "description": "Requires emails:read. Returns the saved appearance and its revision. Read and review this state before replacing or clearing it.", "tags": [ "Email AI Style" ], "responses": { "200": { "description": "Current saved-style state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAiStyleState" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required scope or workspace role cannot perform this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company or accessible source email not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "put": { "operationId": "saveEmailAiStyle", "summary": "Save AI email style", "description": "Requires emails:write and access to the source email. Snapshots the stored email appearance, using email then company theme and font defaults, or the optional unsaved canvas, plus detected layout habits such as dotted dividers around every button. Existing emails and company theme remain unchanged. Marketers cannot capture transactional sources. Replaces only the expected revision; explicit generation style requests and plain-text choices still take precedence.", "tags": [ "Email AI Style" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emailId", "expectedStyleId" ], "properties": { "emailId": { "type": "string", "minLength": 1, "description": "Source email ID in this company, including campaign, sequence and transactional email rows. Use the underlying email ID, not a campaign ID or transactional slug." }, "expectedStyleId": { "type": [ "string", "null" ], "minLength": 1, "description": "revisionId returned by GET. Use null only when no style is stored." }, "canvas": { "$ref": "#/components/schemas/EmailAiStyleCanvas" }, "layoutRuleIds": { "type": "array", "maxItems": 20, "description": "IDs of detected layout habits to keep. Omit to keep every habit detected in the source; pass an empty array to keep none. Unknown IDs are ignored. Review style.layout.rules in the response.", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "notes": { "type": "string", "maxLength": 500, "description": "Optional design notes for future generations, for example \"always open with a short video\". Treated as design guidance, never as email content." } } } } } }, "responses": { "200": { "description": "Current saved-style state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAiStyleState" } } } }, "400": { "description": "Invalid or oversized canvas, or no substantive email content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required scope or workspace role cannot perform this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company or accessible source email not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AI_STYLE_CONFLICT. Get the current style, review it and retry with its revisionId. Do not automatically retry a conflicting write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing or malformed required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "delete": { "operationId": "clearEmailAiStyle", "summary": "Clear saved AI email style", "description": "Requires emails:write. Clears only the reviewed revision. Future generations use normal brand defaults; existing emails stay unchanged. Replayed or stale clears return 409.", "tags": [ "Email AI Style" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expectedStyleId" ], "properties": { "expectedStyleId": { "type": "string", "minLength": 1, "description": "Nonempty revisionId returned by GET, including unsupported-version revisions." } } } } } }, "responses": { "200": { "description": "Current saved-style state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAiStyleState" } } } }, "400": { "description": "Invalid or oversized canvas, or no substantive email content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required scope or workspace role cannot perform this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company or accessible source email not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "AI_STYLE_CONFLICT. Get the current style, review it and retry with its revisionId. Do not automatically retry a conflicting write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing or malformed required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/email-design-system": { "get": { "operationId": "getEmailDesignSystem", "summary": "Get email design system", "description": "Returns the company's effective email design system - the visual identity every AI-generated email (campaigns and sequence steps) renders inside. The identity is stored as the company's emailDesignPrompt direction text; tokens are parsed from that text, with unstated tokens derived deterministically from brand context. isDefault is true while the identity is purely derived.", "tags": [ "Email Design System" ], "responses": { "200": { "description": "Email design system returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "designSystem": { "$ref": "#/components/schemas/EmailDesignSystem" }, "directionText": { "type": [ "string", "null" ], "description": "The raw design direction text the tokens were parsed from; null when the company has none yet." }, "isDefault": { "type": "boolean", "description": "True while the identity is purely derived from brand context." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "operationId": "updateEmailDesignSystem", "summary": "Update email design system", "description": "Adjusts the company's email design system. This is a partial update - only the passed fields change - and it affects every future AI email generation and sequence enrichment. The adjustment is written into the company's emailDesignPrompt direction text (the single source of truth) - the new identity's sentences are prepended and custom prose the text carried is preserved below them. Pass reset true to clear the direction text and return to the brand-derived defaults.", "tags": [ "Email Design System" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "designCode": { "type": "object", "additionalProperties": false, "description": "Partial visual-grammar adjustment; omitted tokens keep their current value.", "properties": { "kickerStyle": { "type": "string", "enum": [ "chip", "letterspaced", "none" ], "description": "How eyebrows above titles render." }, "titleAlignment": { "type": "string", "enum": [ "left", "center" ] }, "buttonShape": { "type": "string", "enum": [ "rounded", "pill" ] }, "dividerStyle": { "type": "string", "enum": [ "line", "space" ] }, "density": { "type": "string", "enum": [ "airy", "compact" ] }, "openerTreatments": { "type": "array", "description": "The opener treatments this company's emails may use, primary first.", "items": { "type": "string", "enum": [ "hero-image", "hero-color", "header-hero", "editorial-masthead", "title-led" ] } } } }, "compositionSpine": { "type": "string", "enum": [ "hero-led", "editorial", "product-spec" ], "description": "Which worked-example skeleton anchors generation." }, "reset": { "type": "boolean", "description": "true clears the direction text and returns to brand-derived defaults. Cannot be combined with designCode or compositionSpine." } } }, "examples": { "editorial-identity": { "summary": "Switch to a typography-first editorial identity", "value": { "compositionSpine": "editorial", "designCode": { "kickerStyle": "letterspaced", "openerTreatments": [ "editorial-masthead", "title-led" ] } } }, "reset": { "summary": "Return to the brand-derived identity", "value": { "reset": true } } } } } }, "responses": { "200": { "description": "Email design system updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Updated the email design system and rewrote the design direction text to match." }, "designSystem": { "$ref": "#/components/schemas/EmailDesignSystem" }, "directionText": { "type": [ "string", "null" ], "description": "The rewritten direction text now stored on the company; null after a reset." }, "isDefault": { "type": "boolean" } } } } } }, "400": { "description": "Invalid design system value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The design system was modified concurrently by another request; retry the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/integrations": { "get": { "operationId": "listIntegrations", "summary": "List integrations", "description": "Lists connected integrations with connection state, sync health, last sync error, and any records the last sync could not import normally. Credentials, access tokens, and webhook secrets are never returned.", "tags": [ "Integrations" ], "parameters": [ { "name": "includeInactive", "in": "query", "required": false, "description": "Include disconnected integrations. Defaults to false.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Integrations returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationSummary" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/events/sample": { "get": { "operationId": "getEventSample", "summary": "Get latest received event sample", "description": "Requires subscribers:read and company access. Reads the latest retained exact-name event across workspace subscribers, including older history. Trims surrounding whitespace; does not resolve aliases. No additional recent-only cutoff. Equal timestamps have no guaranteed tie order. Copy sample.properties into a sequence test run customVariables object; the test recipient is unchanged. This read has no side effects and can be retried safely.", "tags": [ "Events" ], "parameters": [ { "name": "eventName", "in": "query", "required": true, "description": "Exact recorded event name, including custom names. Must not be blank.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Latest retained event, or sample null when none exists", "content": { "application/json": { "schema": { "type": "object", "required": [ "eventName", "sample" ], "properties": { "eventName": { "type": "string" }, "sample": { "type": [ "object", "null" ], "required": [ "eventTime", "subscriberId", "properties" ], "properties": { "eventTime": { "type": "string", "description": "UTC event timestamp" }, "subscriberId": { "type": "string", "description": "Source subscriber ID; may differ from your test recipient" }, "properties": { "type": "object", "additionalProperties": true, "description": "Recorded payload, preserving nested JSON; may be empty" } } } } } } } }, "400": { "description": "Missing or blank eventName, or missing company selection" }, "401": { "description": "Missing or invalid authentication" }, "403": { "description": "Missing subscribers:read scope or company access" }, "500": { "description": "Analytics lookup failed; safe to retry this read" } } } }, "/events/schemas": { "get": { "operationId": "getEventSchemas", "summary": "Get event schemas", "description": "Returns the published payload of a built-in event - a real example payload per provider, plus every property path with its type, the merge tag that resolves it, and a description wherever the example alone is ambiguous (a null sample, an empty list, a unit that is not obvious, or a type that differs per provider). Omit eventName to list every documented event. Static reference data describing the shape of an event, not what the account has received. An event with no published payload returns documented false; it is still valid to trigger and to build a sequence on, because custom events carry exactly the properties you send.", "tags": [ "Events" ], "parameters": [ { "name": "eventName", "in": "query", "required": false, "description": "Event to describe, such as ecommerce.order_placed. Legacy aliases like order.completed resolve to their current name. Omit to list every documented event.", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": false, "description": "Return only this provider's payload: shopify, woocommerce, manual, api, or stripe.", "schema": { "type": "string", "enum": [ "shopify", "woocommerce", "manual", "api", "stripe" ] } } ], "responses": { "200": { "description": "Event schemas returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "eventName": { "type": [ "string", "null" ], "description": "Normalized name of the event described, or null when listing every documented event.", "example": "ecommerce.order_placed" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventSchema" } }, "note": { "type": "string", "description": "Present in listing mode only." } } } } } }, "400": { "description": "Unknown provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/integrations/catalog": { "get": { "operationId": "listIntegrationCapabilities", "summary": "List integration capabilities", "description": "Describes what each integration provider syncs, which events it emits and when, the subscriber attributes it writes, and which actions it supports. Works whether or not the provider is connected, so it can be used to compare providers before connecting one.", "tags": [ "Integrations" ], "parameters": [ { "name": "provider", "in": "query", "required": false, "description": "Return only this provider, for example stripe.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Filter by category: payments, ecommerce, auth, analytics, ads, affiliate, cms, crm, or developer.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Provider capabilities returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationProviderCapability" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/integrations/connect": { "post": { "operationId": "connectIntegration", "summary": "Connect integration", "description": "Connects an API-key / webhook-secret integration: polar, paddle, dodo, lemon_squeezy, whop, creem, chargebee, clerk, posthog, segment, affonso, or attio. Credentials are validated, stored encrypted, and never returned. Lemon Squeezy creates a managed signed webhook when webhookSecret is omitted, or uses a caller-managed secret as fallback. Payment providers queue their initial revenue backfill; Affonso queues its affiliate backfill; PostHog and Segment can optionally import event history. Attio is outbound-only. Reconnecting replaces stored credentials. OAuth and app-install providers require the dashboard. Requires the integrations:manage scope.", "tags": [ "Integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "polar", "paddle", "dodo", "lemon_squeezy", "whop", "creem", "chargebee", "clerk", "posthog", "segment", "affonso", "attio" ], "description": "Provider to connect." }, "webhookSecret": { "type": "string", "description": "Signing secret of the provider webhook. Optional for lemon_squeezy managed provisioning and outbound-only attio; required for other providers. Lemon Squeezy manual secrets use 16-40 characters. For Chargebee, pass username:password. For Segment, use 16-153 UTF-8 bytes." }, "apiKey": { "type": "string", "description": "Provider API key. Required for polar, paddle, dodo, lemon_squeezy, whop, creem, chargebee, affonso, and attio. Attio uses the workspace access token." }, "providerAccountId": { "type": "string", "description": "Provider account id: Paddle seller ID, Dodo business ID, Lemon Squeezy numeric store ID, Whop company ID, Creem store ID, or Chargebee site name. Polar resolves it from the API key." }, "settings": { "type": "object", "description": "PostHog and Segment: event delivery scope. Attio: listMap (Sequenzy list id to Attio list id or slug) and syncCompanyFromDomain.", "properties": { "syncAllEvents": { "type": "boolean" }, "eventAllowlist": { "type": "array", "items": { "type": "string" } }, "listMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Attio only. Sequenzy list id to Attio list UUID or slug." }, "syncCompanyFromDomain": { "type": "boolean", "description": "Attio only. Upsert a company from the person's non-free-mail email domain." } } }, "historyImport": { "type": "object", "description": "PostHog and Segment only. Imports event history after connecting: PostHog reads the project archive (projectId + personalApiKey); Segment walks your existing contacts' Unify profiles (spaceId + profileApiToken) and covers at most the last 14 days the Profile API serves, because Segment has no bulk event export.", "required": [ "region" ], "properties": { "region": { "type": "string", "enum": [ "us", "eu" ] }, "projectId": { "type": "string", "description": "PostHog only. Numeric PostHog project ID." }, "personalApiKey": { "type": "string", "description": "PostHog only. Personal API key with query read access." }, "spaceId": { "type": "string", "description": "Segment only. Unify space ID (spa_...)." }, "profileApiToken": { "type": "string", "description": "Segment only. Profile API access token for the space." } } } } } } } }, "responses": { "200": { "description": "Integration connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "integration": { "$ref": "#/components/schemas/IntegrationSummary" }, "webhookUrl": { "type": "string", "description": "Provider webhook URL. Lemon Squeezy managed mode installs it automatically; manual mode uses the supplied secret. Empty for Attio." }, "webhookProvisioning": { "type": "string", "enum": [ "managed", "manual" ], "description": "Lemon Squeezy only. Whether Sequenzy manages the provider webhook." }, "testMode": { "type": "boolean", "description": "Lemon Squeezy only. Whether the connected store uses test mode." }, "revenueSyncQueued": { "type": "boolean", "description": "Payment providers only. Whether the initial revenue backfill was queued." }, "backfillQueued": { "type": "boolean", "description": "Affonso only. Whether the affiliate backfill was queued." }, "history": { "type": "object", "description": "PostHog and Segment only. Outcome of the optional history import request.", "properties": { "requested": { "type": "boolean" }, "queued": { "type": "boolean" }, "error": { "type": [ "string", "null" ] } } } } } } } }, "400": { "description": "Missing or invalid fields, or a provider that requires the dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The Sequenzy API key is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The Sequenzy API key lacks integrations:manage or company access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The provider account is already connected to another workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations/activity": { "get": { "operationId": "listIntegrationActivity", "summary": "List integration activity", "description": "Recent integration webhook and sync activity, newest first. Retained for 24 hours. Payloads are sanitized when written, so no credentials or signatures appear. Requires the account:read and subscribers:read scopes.", "tags": [ "Integrations" ], "parameters": [ { "name": "integrationId", "in": "query", "required": false, "description": "Only show activity for this integration.", "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": false, "description": "Only show activity for this provider.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by activity status.", "schema": { "type": "string", "enum": [ "received", "queued", "processed", "skipped", "failed" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Rows to return, 1-100. Defaults to 25.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Activity returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "windowHours": { "type": "integer", "example": 24 }, "note": { "type": "string" }, "activity": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationActivityEntry" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required API key scope (account:read and subscribers:read are required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/integrations/{id}": { "get": { "operationId": "getIntegration", "summary": "Get integration", "description": "Inspects one connected integration - what the provider syncs, every event it emits, the tags each event applies through the company's sync rules, the sequences that trigger on those events, recent activity, the ingestion block naming which lists its contacts join, and prioritized recommendations. Credentials are never returned. Requires the account:read, subscribers:read, sequences:read, and lists:read scopes.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Integration detail returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationDetail" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required API key scope (account:read, subscribers:read, sequences:read, and lists:read are required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "operationId": "updateIntegrationSync", "summary": "Update integration bulk sync and list targeting", "description": "Controls what a connected integration does to the contact list. Two independent settings - `syncEnabled` turns bulk imports and backfills on or off, and `listIds` chooses which lists the contacts the provider's live webhook creates join. Neither stops that webhook: disabling bulk sync only pauses full imports, and list targeting changes membership only. Contacts are still created, their attributes still sync, sync-rule tags still apply, and default any_contact sequences still enroll them. Explicit any_list and specific-list sequences require a matching membership and do not enroll a list-less contact. `listIds` takes effect on future provider writes: nothing is applied retroactively and nobody is ever removed from a list. Wix or Webflow submissions, Shopify customer updates, and Supabase resubscriptions can add an existing contact to the new targets; Stripe applies targeting only when its webhook creates a subscriber. Provider support is declared in the catalog's `actions` as set_list_targeting. At least one field is required, an in-flight sync must finish before bulk sync can be disabled, and setting the current state succeeds with `changed: false`. Requires the integrations:manage scope.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "At least one field is required.", "properties": { "syncEnabled": { "type": "boolean", "description": "True to enable bulk imports and backfills, false to pause them. This does not stop the provider's live webhook creating contacts." }, "listIds": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Lists that contacts created by this integration join, applied from the provider's next write onward. `null` clears the choice so they follow the workspace default lists; `[]` means they join no list; a populated array means exactly those lists. Every ID must belong to this company." } } } } } }, "responses": { "200": { "description": "Ingestion controls updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "integrationId": { "type": "string" }, "provider": { "type": "string" }, "syncEnabled": { "type": "boolean", "description": "Bulk import and backfill state after the update." }, "listTargeting": { "type": [ "string", "null" ], "enum": [ "company_default", "none", "specific", null ], "description": "Where contacts created by this integration land. Null for providers that ignore per-integration list targeting." }, "listIds": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Configured target lists. Null means new contacts follow the workspace default lists." }, "changed": { "type": "boolean", "description": "False when the integration was already in the requested state." }, "changedFields": { "type": "array", "items": { "type": "string" }, "description": "Which controls actually moved." }, "message": { "type": "string" } } } } } }, "400": { "description": "Integration is disconnected, no field was provided, the provider does not expose the requested control, or a list ID is invalid or belongs to another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A sync is already in progress; wait for it to finish before disabling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations/{id}/disconnect": { "post": { "operationId": "disconnectIntegration", "summary": "Disconnect integration", "description": "Disconnects Lemon Squeezy locally before removing its managed webhook. Manual webhooks remain under your control. Requires integrations:manage; personal keys require owner or admin access. A cleanupWarning means ingestion is stopped but provider cleanup failed; repeat this request to retry cleanup, including when the integration is already inactive. Other providers require the dashboard. Existing subscribers and history are retained. No request body is required.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Lemon Squeezy integration ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disconnected locally; inspect cleanupWarning for provider cleanup recovery.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "integrationId", "provider", "cleanupWarning", "message" ], "properties": { "success": { "type": "boolean", "const": true }, "integrationId": { "type": "string" }, "provider": { "type": "string", "const": "lemon_squeezy" }, "cleanupWarning": { "type": [ "string", "null" ], "description": "Null when cleanup succeeded or no managed webhook exists. Otherwise repeat disconnect to retry provider cleanup." }, "message": { "type": "string" } } } } } }, "400": { "description": "Provider is not Lemon Squeezy; use the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing integrations:manage scope or insufficient company role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration does not exist in the selected company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Integration changed stores while disconnecting; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Local disconnection could not be committed; retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations/{id}/sync": { "post": { "operationId": "syncIntegration", "summary": "Sync integration", "description": "Queues a manual re-sync for a connected integration - customers and revenue for a payment provider (Stripe, Polar, Paddle, Dodo, Lemon Squeezy, Creem, Chargebee, Whop), the user backfill for Supabase, or the event-history import for PostHog and Segment. The Supabase sync reads the project, schema, and table already configured for the integration and returns 400 when none is configured. PostHog and Segment re-run their event-history imports with credentials stored at connect time and are the supported retry path for failed imports; each restarts from the beginning, already-imported events dedupe, and returns 409 while queued or syncing. Segment requires a saved Unify space ID and Profile API token and covers the most recent 14 days served by the Profile API. Terminal BullMQ failures release imports for retry. Returns immediately; poll the integration to watch syncStatus. Other providers re-sync from the dashboard. Requires the integrations:manage scope.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Integration ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "integrationId": { "type": "string" }, "provider": { "type": "string" }, "jobId": { "type": [ "string", "null" ] }, "syncStatus": { "type": "string", "example": "queued" }, "syncTarget": { "type": [ "object", "null" ], "description": "Supabase only - the source the backfill reads. Absent for providers whose sync has no configurable source.", "properties": { "projectRef": { "type": "string" }, "schema": { "type": "string" }, "table": { "type": "string" } } }, "message": { "type": "string" } } } } } }, "400": { "description": "Provider does not support an API-triggered sync, the Supabase sync has no configured table, or the integration is disconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A sync is already in progress or bulk sync is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations/{id}/pixel": { "get": { "operationId": "getIntegrationPixel", "summary": "Get storefront pixel state", "description": "Reads the live state of a Shopify store's storefront tracking pixel. Nothing about the pixel is stored locally, so this queries the store on every call. A confirmed missing or stale pixel prevents on-site events (product views, cart activity, browse abandonment) from arriving; a Shopify read error reports the state as unknown instead. Shopify only. Requires the account:read scope.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Shopify integration ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pixel state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationPixelState" } } } }, "400": { "description": "Provider has no storefront pixel, or the integration is disconnected or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "operationId": "activateIntegrationPixel", "summary": "Activate storefront pixel", "description": "Installs the Shopify storefront tracking pixel, or repoints an existing one at this account. Idempotent - an already-live pixel returns changed false without writing to the store. Events start arriving on the next storefront visit; nothing is backfilled. Fails with a 400 naming the reconnect step when the store granted an older permission set. Shopify only. Requires the integrations:manage scope.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Shopify integration ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pixel installed, repointed, or already live", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/IntegrationPixelState" }, { "type": "object", "properties": { "changed": { "type": "boolean", "description": "False when the pixel was already installed and current." }, "created": { "type": "boolean", "description": "True when a new pixel was installed." }, "updated": { "type": "boolean", "description": "True when an existing pixel was repointed." } } } ] } } } }, "400": { "description": "Provider has no storefront pixel, the integration is disconnected, or Shopify refused the install", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations/{id}/attio": { "get": { "operationId": "getAttioMapping", "summary": "Get Attio list mapping", "description": "Reads a connected Attio integration's saved Sequenzy-to-Attio list map, this company's Sequenzy lists, and live Attio people-lists using the stored access token. Call this before updating mappings so you have Attio list ids or slugs. Attio only. Requires the account:read and lists:read scopes.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Attio integration ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attio mapping state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationAttioMapping" } } } }, "400": { "description": "Provider is not Attio, or the integration is disconnected or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "operationId": "updateAttioSettings", "summary": "Update Attio list mapping", "description": "Saves Sequenzy-to-Attio list mappings and/or company-matching on an already-connected Attio integration using the stored access token. Does not require the secret again. listMap is a full replacement when provided; an empty object clears every mapping. Provide at least one of listMap or syncCompanyFromDomain. Idempotent. Attio only. Requires the integrations:manage scope.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Attio integration ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listMap": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Complete Sequenzy list id to Attio list UUID or api slug map. Replaces the saved map. Pass {} to clear every mapping." }, "syncCompanyFromDomain": { "type": "boolean", "description": "When true, upsert a company from the person's non-free-mail email domain." } } } } } }, "responses": { "200": { "description": "Attio settings saved, or already in this state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationAttioMapping" } } } }, "400": { "description": "Provider is not Attio, unknown list ids, or neither field was provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Integration not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/sender-profiles": { "get": { "operationId": "listSenderProfiles", "summary": "List sender and reply-to profiles", "description": "Lists sender (From) and reply-to profiles, which are the account defaults, and whether each sender address sits on a verified sending domain. SMTP submission sends into Sequenzy; outbound delivery remains Sequenzy-managed through SES or Sequenzy's MTA, so customer-managed SMTP relays are not supported.", "tags": [ "Sender Profiles" ], "responses": { "200": { "description": "Sending identities returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "senderProfiles": { "type": "array", "items": { "$ref": "#/components/schemas/SenderProfileSummary" } }, "replyProfiles": { "type": "array", "items": { "$ref": "#/components/schemas/ReplyProfileSummary" } }, "defaultSenderProfileId": { "type": [ "string", "null" ] }, "defaultReplyProfileId": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/sender-profiles/{id}": { "patch": { "operationId": "updateSenderProfile", "summary": "Rename a sender profile", "description": "Renames one sender (From) profile in place. Only the display name changes - the address, its sending domain, and the account-wide default From selection are left untouched, so a display name can be standardized across the several identities one mailbox may carry. To change which profile is the account default instead, use PATCH /v1/companies/{companyId} with senderProfileId. Requires companies:manage.", "tags": [ "Sender Profiles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sender profile ID, from GET /v1/sender-profiles." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New display name. Trimmed before saving.", "example": "SnapCount" } } } } } }, "responses": { "200": { "description": "Sender profile renamed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "senderProfile": { "$ref": "#/components/schemas/SenderProfileSummary" }, "renamed": { "type": "boolean", "description": "False when the profile already carried that name, so nothing changed." } } } } } }, "400": { "description": "Name is empty or longer than 255 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender profile not found in this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Another sender identity for the same address already uses that name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteSenderProfile", "summary": "Delete a sender profile", "description": "Permanently deletes one sender (From) profile. Refuses to delete the company's last sender or a profile used by a live campaign, active sequence (including step-level overrides), or transactional email. Eligible draft and rejected campaigns plus the account default are reassigned to the best remaining sender when needed. Requires companies:manage.", "tags": [ "Sender Profiles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sender profile ID, from GET /v1/sender-profiles." } ], "responses": { "200": { "description": "Sender profile deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "deletedSenderProfileId", "fallbackSenderProfileId", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "deletedSenderProfileId": { "type": "string", "description": "ID of the profile that was deleted." }, "fallbackSenderProfileId": { "type": [ "string", "null" ], "description": "Remaining profile selected for defaults and eligible drafts when reassignment was needed." }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing companies:manage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sender profile not found in this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "This is the last sender profile or a live sending surface still uses it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reply-profiles/{id}": { "patch": { "operationId": "updateReplyProfile", "summary": "Rename a reply-to profile", "description": "Renames one reply-to profile in place. Only the display name changes - the address and the account-wide default Reply-To selection are left untouched. Requires companies:manage.", "tags": [ "Sender Profiles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Reply-to profile ID, from GET /v1/sender-profiles." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New display name. Trimmed before saving.", "example": "SnapCount" } } } } } }, "responses": { "200": { "description": "Reply-to profile renamed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "replyProfile": { "$ref": "#/components/schemas/ReplyProfileSummary" }, "renamed": { "type": "boolean", "description": "False when the profile already carried that name, so nothing changed." } } } } } }, "400": { "description": "Name is empty or longer than 255 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Reply-to profile not found in this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notification-preferences": { "get": { "operationId": "getNotificationPreferences", "summary": "Get account notification preferences", "description": "Returns the account notification settings for the API key's own user in the active company, along with the modes each event supports and the platform defaults. Every event available to the requesting client is present; an event the user has never configured reports its default. Default Node and Undici clients must send x-sequenzy-client to receive weekly_report. There is no way to read another member's preferences through this API. Requires account:read.", "tags": [ "Notification Preferences" ], "parameters": [ { "name": "x-sequenzy-client", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Identifies a client that supports the complete notification event list, including weekly_report. Any non-empty value opts a default Node or Undici client into the full response." } ], "responses": { "200": { "description": "Notification preferences returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "operationId": "updateNotificationPreferences", "summary": "Update account notification preferences", "description": "Changes which account notifications Sequenzy emails the API key's own user for the active company. Events not listed keep their current value. Useful before a bulk import or migration, though imports never trigger new-subscriber notifications in the first place. Requires companies:manage; account:read alone cannot mutate these settings.", "tags": [ "Notification Preferences" ], "parameters": [ { "name": "x-sequenzy-client", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Identifies a client that supports the complete notification event list, including weekly_report. Any non-empty value opts a default Node or Undici client into the full response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "notificationPreferences" ], "properties": { "notificationPreferences": { "type": "array", "minItems": 1, "description": "Preferences to set. Events not listed are left unchanged.", "items": { "$ref": "#/components/schemas/NotificationPreference" } } } } } } }, "responses": { "200": { "description": "Notification preferences updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "400": { "description": "Unsupported event or mode. \"daily\" is not valid for form_submitted or campaign_completed; \"weekly\" is only valid for weekly_report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tracking-settings": { "get": { "operationId": "getTrackingSettings", "summary": "Get tracking settings", "description": "Returns account-wide and Transactional API open/click tracking flags, unsubscribe tracking, attribution, UTM tagging, tracking domain, inbound reply settings and signup consent settings.", "tags": [ "Tracking Settings" ], "responses": { "200": { "description": "Tracking configuration returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingSettings" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "patch": { "operationId": "updateTrackingSettings", "summary": "Update tracking settings", "description": "Updates the account-wide and Transactional API tracking defaults - open, click, and unsubscribe tracking, strict bot filtering, the default attribution window, and automatic UTM tagging - plus the double opt-in requirement for new contacts. Applies to emails sent afterwards; already-sent emails keep the links they were rendered with. Reply tracking is updated through the company endpoint.", "tags": [ "Tracking Settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "openTrackingEnabled": { "type": "boolean", "description": "Whether to embed the open-tracking pixel." }, "clickTrackingEnabled": { "type": "boolean", "description": "Whether to rewrite links through the click-tracking redirect." }, "strictBotFilteringEnabled": { "type": "boolean", "description": "Opt-in aggressive bot detection (strict user-agent patterns, datacenter and Microsoft Azure IPs, fast campaign and sequence clicks from IPs clicking other recipients' emails, cross-send IP sweeps). Off by default; enabling it can lower reported open and click rates." }, "unsubscribeTrackingEnabled": { "type": "boolean", "description": "Whether to track unsubscribe link clicks. When false, Sequenzy unsubscribe links go directly to https://sequenzy.com, even with a custom tracking domain. Actual unsubscribes and their email attribution are still recorded." }, "defaultAttributionWindowHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "Default revenue attribution window in hours." }, "doubleOptInEnabled": { "type": "boolean", "description": "Whether new contacts must confirm by email before they become subscribed. This is the account-wide default that the per-request optInMode on subscriber creation overrides. Enabling it requires a sender profile and provisions the confirmation email automatically; it does not change contacts that are already active." }, "doubleOptInRedirectUrl": { "type": [ "string", "null" ], "maxLength": 500, "description": "Where the hosted confirmation page sends subscribers after they confirm. Must be an http(s) URL of at most 500 characters after normalization; a bare domain is normalized to https. Null (or an empty string) clears it, keeping subscribers on the confirmation page branded with the company's name, logo, and colors." }, "autoUtmEnabled": { "type": "boolean", "description": "Whether UTM parameters are appended to outbound links automatically. Enabling this with no stored parameters seeds the platform defaults." }, "autoUtmSettings": { "type": [ "object", "null" ], "description": "UTM templates merged over the stored ones. Null resets every parameter to the platform defaults; a null field stops that parameter being emitted.", "properties": { "source": { "type": [ "string", "null" ] }, "medium": { "type": [ "string", "null" ] }, "campaign": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "term": { "type": [ "string", "null" ] } } }, "transactionalOpenTrackingEnabled": { "type": "boolean", "description": "Open tracking default for sends through the Send Email API. Account-wide open tracking must also be enabled; per-send trackingSettings can only opt out." }, "transactionalClickTrackingEnabled": { "type": "boolean", "description": "Click tracking default for sends through the Send Email API. Account-wide click tracking must also be enabled; per-send trackingSettings can only opt out." } } } } } }, "responses": { "200": { "description": "Tracking configuration updated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TrackingSettings" }, { "type": "object", "properties": { "message": { "type": "string" } } } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tracking-domain": { "get": { "operationId": "getTrackingDomain", "summary": "Get tracking domain", "description": "Returns the company tracking domain every sending domain uses for tracked links and opens, or null when links use the shared Sequenzy tracking domain. Requires the account:read scope.", "tags": [ "Tracking Domain" ], "responses": { "200": { "description": "Tracking domain returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "trackingDomain": { "oneOf": [ { "$ref": "#/components/schemas/TrackingDomain" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the account:read scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "put": { "operationId": "setTrackingDomain", "summary": "Set tracking domain", "description": "Sets or changes the company tracking domain. Any subdomain the caller controls works, including one on a root other than the sending domains; a bare registrable domain is rejected because it cannot hold a CNAME. Publish the returned cnameRecord. Sending never waits for it; new emails use the shared Sequenzy tracking domain until it verifies. Saving the current hostname again only rechecks it. Changing the hostname keeps the previous one serving links in emails already sent while its old CNAME stays. Requires the companies:manage scope plus owner or admin access.", "tags": [ "Tracking Domain" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Tracking hostname, a subdomain such as links.example.com. A leading https:// and trailing path are ignored." } } } } } }, "responses": { "200": { "description": "Tracking domain saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "description": "The next step, usually the CNAME to add." }, "trackingDomain": { "$ref": "#/components/schemas/TrackingDomain" } } } } } }, "400": { "description": "Invalid hostname or a bare root domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing the companies:manage scope, or view-only access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The hostname is already connected to another company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request body is missing domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The tracking provider could not register the hostname. Nothing was saved; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "removeTrackingDomain", "summary": "Remove tracking domain", "description": "Removes the company tracking domain. New emails use the shared Sequenzy tracking domain, and links in emails already sent through the removed domain stop working. Removing when none is set succeeds with removed false. Requires the companies:manage scope plus owner or admin access.", "tags": [ "Tracking Domain" ], "responses": { "200": { "description": "Tracking domain removed, or none was set", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "removed": { "type": "boolean", "description": "False when no tracking domain was set." }, "trackingDomain": { "type": "null" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing the companies:manage scope, or view-only access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The tracking provider could not release the hostname. The tracking domain was kept; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tracking-domain/verify": { "post": { "operationId": "verifyTrackingDomain", "summary": "Verify tracking domain", "description": "Checks the company tracking domain's CNAME and HTTPS certificate now instead of waiting for the automatic checks. Requires the companies:manage scope plus owner or admin access.", "tags": [ "Tracking Domain" ], "responses": { "200": { "description": "Check completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "verified": { "type": "boolean", "description": "Whether the CNAME and HTTPS certificate work." }, "message": { "type": "string", "description": "The result or the next step." }, "trackingDomain": { "$ref": "#/components/schemas/TrackingDomain" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing the companies:manage scope, or view-only access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No tracking domain is set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The tracking provider could not be reached; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sending-status": { "get": { "operationId": "getSendingStatus", "summary": "Get sending status", "description": "Returns whether company-level sending is active, paused, or suspended, the pause reason, the sender-health counts and thresholds behind it, the automated review state, whether sending can be restored without support, and ordered remediation steps. Call this whenever a send or test send fails for a reason that is not a validation error. Enforcement uses all-time totals from a reset watermark rather than a rolling window, so metricsWindow.expiresAt is always null and waiting does not restore sending. Requires the account:read scope.", "tags": [ "Sending Status" ], "responses": { "200": { "description": "Sending status returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingStatus" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key is missing the account:read scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } } }, "/sending-status/resume": { "post": { "operationId": "resumeSending", "summary": "Resume paused sending", "description": "Restores company-level sending paused by a high permanent-bounce rate, after the cause has been fixed. This is not a bypass - it enforces the same gates as the dashboard and never removes suppressions. For a paused workspace, sending is restored only when selfResume.canSelfResume is true on GET /sending-status, which requires a high_hard_bounce_rate pause, a cleared automated sender-health review, and no admin block. An already-active workspace succeeds as an idempotent no-op with resumed false. On restoration the bounce watermark moves to now and the service attempts to requeue paused campaigns plus due sequence steps. A partial queue handoff still returns the committed active state with recovery guidance in message. Requires the companies:manage scope plus owner or admin access.", "tags": [ "Sending Status" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "listSanitizationConfirmed" ], "properties": { "listSanitizationConfirmed": { "type": "boolean", "description": "Must be true. Confirms the source of the invalid addresses is fixed and permanent bounces remain suppressed. Recorded on the account audit trail." } } } } } }, "responses": { "200": { "description": "Sending resumed, or already active", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendingStatus" }, { "type": "object", "properties": { "resumed": { "type": "boolean", "description": "False when sending was already active." }, "message": { "type": "string", "description": "Confirms the outcome, or explains that sending resumed while some parked work still needs support." } } } ] } } } }, "400": { "description": "Confirmation missing, or the pause reason is not self-resumable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Blocked by the automated review, an admin block, or view-only access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/websites": { "get": { "operationId": "listWebsites", "summary": "List websites", "description": "Lists sending domains configured for the authenticated company.", "tags": [ "Websites" ], "responses": { "200": { "description": "Websites returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "websites": { "type": "array", "items": { "$ref": "#/components/schemas/Website" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/TransientDatabaseUnavailable" } } }, "post": { "operationId": "addWebsite", "summary": "Add sending domain", "description": "Adds a sending domain to the authenticated company and returns the SPF, DKIM, MAIL FROM, DMARC, and tracking DNS records required for setup. Tracked links use the company tracking domain, shared by every sending domain: the first domain creates it on its root (links.) and returns its CNAME as dnsRecords.trackingRecord. It is optional and never gates verification or sending. A domain belongs to exactly one company, so confirm the target company before adding it.", "tags": [ "Websites" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "domain": { "type": "string", "description": "Domain to add." }, "mailFromPrefix": { "type": "string", "description": "Bounce (MAIL FROM) subdomain label. Defaults to send. One DNS label of 1 to 63 letters, numbers or hyphens; inbound is reserved. Applies only when the domain is created; re-adding an existing domain returns its stored records.", "example": "send" }, "trackingPrefix": { "type": "string", "description": "Label of the company tracking domain created on the domain's root (