{ "openapi": "3.1.0", "info": { "title": "Mailrith API", "version": "v1", "description": "Mailrith's public API for subscriber sync, workspace discovery, product control-plane operations, and async subscriber import/export jobs." }, "servers": [ { "url": "https://api.mailrith.com", "description": "Production" }, { "url": "https://api-stage.mailrith.com", "description": "Stage" }, { "url": "http://localhost:8787", "description": "Local development" } ], "tags": [ { "name": "Platform", "description": "Version metadata, discovery URLs, capability discovery, and the machine-readable OpenAPI document." }, { "name": "Workspace", "description": "Read the current authenticated workspace profile and execution context." }, { "name": "Subscribers", "description": "Create or upsert subscribers and list subscriber records in a workspace." }, { "name": "Tags", "description": "Read and create subscriber tags used for targeting, automation, and imports." }, { "name": "Custom Fields", "description": "Read and manage the typed custom-field schema available to the authenticated workspace." }, { "name": "Email Templates", "description": "Create and manage reusable email templates for the authenticated workspace." }, { "name": "Forms", "description": "Read and manage embeddable form definitions and presentation settings." }, { "name": "Landing Pages", "description": "Read and manage hosted landing pages, page definitions, and public URLs." }, { "name": "Sequences", "description": "Create and manage email sequences, sequence status, and delivery configuration." }, { "name": "Automations", "description": "Create and manage automation definitions and lifecycle state." }, { "name": "Magic Links", "description": "Create and manage magic links used in broadcasts, sequences, and automations." }, { "name": "Broadcasts", "description": "Create, schedule, test, send, and inspect one-off broadcasts." }, { "name": "Segments", "description": "Read saved segments and preview dynamic segment definitions." }, { "name": "Jobs", "description": "Create and inspect asynchronous subscriber import and export jobs." }, { "name": "Webhooks", "description": "Create and manage outbound webhook subscriptions for Mailrith events and signed event delivery." } ], "components": { "securitySchemes": { "WorkspaceApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Bearer Credential", "description": "Workspace-scoped bearer credential. Mailrith accepts either a workspace API key or an OAuth access token issued to an approved client." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request", "authentication_error", "permission_error", "not_found", "conflict", "api_error" ] }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Pagination": { "type": "object", "required": [ "has_more", "next_cursor" ], "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "ApiMetadata": { "type": "object", "required": [ "version", "documentation_url", "reference_url", "agents_url", "sdk_docs_url", "typescript_sdk_url", "python_sdk_url", "mcp_docs_url", "mcp_url", "llms_url", "llms_full_url", "openapi_url", "capabilities_url", "webhook_subscriptions_url", "oauth_authorization_server_url" ], "properties": { "version": { "type": "string" }, "documentation_url": { "type": "string" }, "reference_url": { "type": "string" }, "agents_url": { "type": "string" }, "sdk_docs_url": { "type": "string" }, "typescript_sdk_url": { "type": "string" }, "python_sdk_url": { "type": "string" }, "mcp_docs_url": { "type": "string" }, "mcp_url": { "type": "string" }, "llms_url": { "type": "string" }, "llms_full_url": { "type": "string" }, "openapi_url": { "type": "string" }, "capabilities_url": { "type": "string" }, "webhook_subscriptions_url": { "type": "string" }, "oauth_authorization_server_url": { "type": "string" } } }, "CapabilityOperation": { "type": "object", "required": [ "method", "path", "operation_id", "summary", "required_scopes" ], "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "operation_id": { "type": "string" }, "summary": { "type": "string" }, "required_scopes": { "type": "array", "items": { "type": "string" } }, "event_pattern_scope_requirements": { "$ref": "#/components/schemas/WebhookEventPatternScopeRequirements" } } }, "CapabilityResource": { "type": "object", "required": [ "key", "name", "description", "operations" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityOperation" } } } }, "Capabilities": { "type": "object", "required": [ "version", "workspace", "authentication", "credential", "discovery", "sdks", "mcp", "conventions", "events", "resources" ], "properties": { "version": { "type": "string" }, "workspace": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "authentication": { "type": "object", "required": [ "type", "header_name", "header_value_prefix", "workspace_scoped", "scopes_supported", "supported_credential_types" ], "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "header_name": { "type": "string" }, "header_value_prefix": { "type": "string" }, "workspace_scoped": { "type": "boolean" }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "supported_credential_types": { "type": "array", "items": { "type": "string", "enum": [ "workspace_api_key", "oauth_access_token" ] } } } }, "credential": { "oneOf": [ { "type": "object", "required": [ "type", "id", "name", "status", "scopes", "key_preview", "created_at", "updated_at" ], "properties": { "type": { "type": "string", "enum": [ "workspace_api_key" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked", "rotated" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "key_preview": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "required": [ "type", "id", "status", "scopes", "token_preview", "client", "created_by_user_id", "last_authorized_by_user_id", "expires_at", "created_at", "updated_at" ], "properties": { "type": { "type": "string", "enum": [ "oauth_access_token" ] }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "active" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "token_preview": { "type": "string" }, "client": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "created_by_user_id": { "type": "string", "nullable": true }, "last_authorized_by_user_id": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "discovery": { "type": "object", "required": [ "documentation_url", "reference_url", "agents_url", "sdk_docs_url", "typescript_sdk_url", "python_sdk_url", "mcp_docs_url", "mcp_url", "llms_url", "llms_full_url", "openapi_url", "webhook_subscriptions_url", "oauth_authorization_server_url" ], "properties": { "documentation_url": { "type": "string" }, "reference_url": { "type": "string" }, "agents_url": { "type": "string" }, "sdk_docs_url": { "type": "string" }, "typescript_sdk_url": { "type": "string" }, "python_sdk_url": { "type": "string" }, "mcp_docs_url": { "type": "string" }, "mcp_url": { "type": "string" }, "llms_url": { "type": "string" }, "llms_full_url": { "type": "string" }, "openapi_url": { "type": "string" }, "webhook_subscriptions_url": { "type": "string" }, "oauth_authorization_server_url": { "type": "string" } } }, "sdks": { "$ref": "#/components/schemas/PublicApiSdks" }, "mcp": { "$ref": "#/components/schemas/PublicApiMcp" }, "conventions": { "type": "object", "required": [ "pagination_type", "pagination_limit_param", "pagination_cursor_param", "idempotency_header" ], "properties": { "pagination_type": { "type": "string", "enum": [ "cursor" ] }, "pagination_limit_param": { "type": "string" }, "pagination_cursor_param": { "type": "string" }, "idempotency_header": { "type": "string" } } }, "events": { "$ref": "#/components/schemas/WebhookEventSupport" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityResource" } } } }, "PublicApiSdks": { "type": "object", "required": [ "typescript", "python" ], "properties": { "typescript": { "type": "object", "required": [ "package_name", "docs_url", "language" ], "properties": { "package_name": { "type": "string" }, "docs_url": { "type": "string" }, "language": { "type": "string", "enum": [ "typescript" ] } } }, "python": { "type": "object", "required": [ "package_name", "docs_url", "language" ], "properties": { "package_name": { "type": "string" }, "docs_url": { "type": "string" }, "language": { "type": "string", "enum": [ "python" ] } } } } }, "PublicApiMcp": { "type": "object", "required": [ "package_name", "docs_url", "server_url", "recommended_transport", "supported_transports" ], "properties": { "package_name": { "type": "string" }, "docs_url": { "type": "string" }, "server_url": { "type": "string" }, "recommended_transport": { "type": "string", "enum": [ "streamable_http" ] }, "supported_transports": { "type": "array", "items": { "type": "string", "enum": [ "streamable_http", "stdio" ] } } } }, "WebhookSigning": { "type": "object", "required": [ "algorithm", "id_header", "timestamp_header", "signature_header", "signature_prefix" ], "properties": { "algorithm": { "type": "string", "enum": [ "hmac-sha256" ] }, "id_header": { "type": "string" }, "timestamp_header": { "type": "string" }, "signature_header": { "type": "string" }, "signature_prefix": { "type": "string" } } }, "WebhookEventSupport": { "type": "object", "required": [ "subscriptions_url", "supported_events", "supported_event_patterns", "required_scopes_by_event_pattern", "signing" ], "properties": { "subscriptions_url": { "type": "string" }, "supported_events": { "type": "array", "items": { "type": "string" } }, "supported_event_patterns": { "type": "array", "items": { "type": "string" } }, "required_scopes_by_event_pattern": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "signing": { "$ref": "#/components/schemas/WebhookSigning" } } }, "WebhookEventPatternScopeRequirements": { "type": "object", "required": [ "request_field", "description", "required_scopes_by_event_pattern" ], "properties": { "request_field": { "type": "string", "enum": [ "event_patterns" ] }, "description": { "type": "string" }, "required_scopes_by_event_pattern": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "WebhookSubscription": { "type": "object", "required": [ "id", "name", "url", "status", "event_patterns", "signing_secret_preview", "delivery_attempts", "last_delivery_status", "last_delivery_error", "last_delivered_at", "last_failed_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "event_patterns": { "type": "array", "description": "Events or wildcard patterns to deliver. The caller also needs read access for each selected event family; events that include subscriber details require `subscribers:read`.", "items": { "type": "string" } }, "signing_secret_preview": { "type": "string" }, "delivery_attempts": { "type": "integer", "minimum": 0 }, "last_delivery_status": { "type": "string", "nullable": true, "enum": [ "delivered", "failed", null ] }, "last_delivery_error": { "type": "string", "nullable": true }, "last_delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "last_failed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookSubscriptionCreateRequest": { "type": "object", "required": [ "name", "url", "event_patterns" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "description": "Public HTTPS destination URL for signed event delivery. Localhost, private network, link-local, and reserved destinations are not accepted." }, "event_patterns": { "type": "array", "description": "Events or wildcard patterns to deliver. Updating this field, or changing a subscription that already has event patterns, requires read access for the selected event families.", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } }, "WebhookSubscriptionUpdateRequest": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "description": "Public HTTPS destination URL for signed event delivery. Localhost, private network, link-local, and reserved destinations are not accepted." }, "event_patterns": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } }, "WebhookSubscriptionCreateResult": { "type": "object", "required": [ "subscription", "signing_secret" ], "properties": { "subscription": { "$ref": "#/components/schemas/WebhookSubscription" }, "signing_secret": { "type": "string" } } }, "WorkspaceReference": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "Workspace": { "type": "object", "required": [ "id", "name", "logo", "address", "city", "state", "postal_code", "country", "time_zone", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "logo": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true, "description": "State, province, or region for the workspace address." }, "postal_code": { "type": "string", "nullable": true, "description": "Postal or ZIP code for the workspace address." }, "country": { "type": "string", "nullable": true, "description": "Country for the workspace address." }, "time_zone": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TagSummary": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "Subscriber": { "type": "object", "required": [ "id", "email", "name", "status", "country", "subscribed_at", "tags", "sequence_ids", "custom_fields", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked" ] }, "country": { "type": "string", "nullable": true, "description": "Two-letter country code or country name. Mailrith stores Subscriber country as a two-letter country code." }, "subscribed_at": { "type": "string", "format": "date-time" }, "last_opened_at": { "type": "string", "format": "date-time", "nullable": true }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagSummary" } }, "sequence_ids": { "type": "array", "items": { "type": "string" } }, "custom_fields": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SubscriberUpsertRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked" ] }, "country": { "type": "string", "nullable": true, "description": "Two-letter country code or country name. Mailrith stores Subscriber country as a two-letter country code." }, "subscribed_on": { "type": "string", "example": "2026-04-11", "description": "Subscriber-local subscription date in YYYY-MM-DD format." }, "form_id": { "type": "string", "description": "Optional form ID to record this upsert as a form subscription and apply the form's tags." }, "create_only": { "type": "boolean", "description": "When true, Mailrith returns a 409 conflict instead of updating an existing subscriber with the same email." }, "existing_tag_ids": { "type": "array", "items": { "type": "string" } }, "new_tags": { "type": "array", "items": { "type": "string" } }, "sequence_ids": { "type": "array", "items": { "type": "string" } }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by custom field ID. For Multi Select fields, send an array of option names or a comma-separated string. Blank optional values leave saved values unchanged when updating an existing subscriber, and filled-in invalid values are rejected." } }, "example": { "email": "ada@example.com", "name": "Ada Lovelace", "status": "Active", "country": "DE", "existing_tag_ids": [ "tag_existing" ], "new_tags": [ "Website Signup" ], "sequence_ids": [ "sequence_welcome" ], "custom_fields": { "cf_company": "Analytical Engines" } } }, "SubscriberUpdateRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked" ] }, "country": { "type": "string", "nullable": true, "description": "Two-letter country code or country name. Mailrith stores Subscriber country as a two-letter country code." }, "subscribed_on": { "type": "string", "example": "2026-04-11", "description": "Subscriber-local subscription date in YYYY-MM-DD format." }, "existing_tag_ids": { "type": "array", "items": { "type": "string" } }, "new_tags": { "type": "array", "items": { "type": "string" } }, "sequence_ids": { "type": "array", "items": { "type": "string" } }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by custom field ID. For Multi Select fields, send an array of option names or a comma-separated string. Blank optional values leave saved values unchanged, and filled-in invalid values are rejected." } }, "example": { "name": "Ada Lovelace", "status": "Active", "country": "DE", "existing_tag_ids": [ "tag_existing" ], "sequence_ids": [ "sequence_welcome" ], "custom_fields": { "cf_company": "Analytical Engines" } } }, "Tag": { "type": "object", "required": [ "id", "name", "description", "gdpr_consent_purpose", "subscriber_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "gdpr_consent_purpose": { "type": "string", "nullable": true, "enum": [ "email_marketing", "ads_personalization" ], "description": "Read-only GDPR consent purpose for Mailrith consent tags. Null for ordinary tags." }, "subscriber_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TagCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Tag name to create. You can also create the GDPR consent tag names when you need to apply consent collected outside Mailrith." }, "description": { "type": "string", "nullable": true } } }, "CustomField": { "type": "object", "required": [ "id", "label", "type", "settings", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "settings": { "type": "object", "required": [ "options" ], "properties": { "options": { "type": "array", "items": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CustomFieldUpsertRequest": { "type": "object", "required": [ "label", "type" ], "properties": { "label": { "type": "string" }, "type": { "type": "string", "enum": [ "Text", "Number", "Date", "Select (Dropdown)", "Single Select", "Multi Select", "Text Area", "Checkbox" ] }, "settings": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } } }, "Form": { "type": "object", "required": [ "id", "name", "definition", "public_token", "subscribers_90d", "views_90d", "conversion_rate_90d", "submit_url", "embed_url", "hosted_url", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "definition": { "type": "object", "description": "Builder-backed form definition. Field and style data live under the builder payload.", "required": [ "builder" ], "properties": { "display": { "type": "object", "additionalProperties": true }, "builder": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "public_token": { "type": "string" }, "subscribers_90d": { "type": "integer" }, "views_90d": { "type": "integer" }, "conversion_rate_90d": { "type": "number" }, "submit_url": { "type": "string" }, "embed_url": { "type": "string" }, "hosted_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FormUpsertRequest": { "type": "object", "required": [ "name", "definition" ], "properties": { "name": { "type": "string" }, "definition": { "type": "object", "description": "Builder-backed form definition. Include display and builder data only; field and style data must live inside the builder payload.", "required": [ "builder" ], "properties": { "display": { "type": "object", "additionalProperties": true }, "builder": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } }, "additionalProperties": false }, "FormSubmission": { "type": "object", "required": [ "id", "form_id", "form_name", "subscriber", "submitted_at" ], "properties": { "id": { "type": "string" }, "form_id": { "type": "string" }, "form_name": { "type": "string" }, "subscriber": { "$ref": "#/components/schemas/Subscriber" }, "submitted_at": { "type": "string", "format": "date-time" } } }, "LandingPage": { "type": "object", "required": [ "id", "name", "slug", "custom_path", "customPath", "definition", "styles", "settings", "public_token", "public_url", "subscribers_90d", "views_90d", "conversion_rate_90d", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "custom_path": { "type": "string", "nullable": true, "description": "Optional Pro custom slug for the workspace's verified landing page subdomain." }, "customPath": { "type": "string", "nullable": true, "description": "Camel-case alias for custom_path. Optional Pro custom slug for the workspace's verified landing page subdomain." }, "definition": { "type": "object", "additionalProperties": true }, "styles": { "type": "object", "additionalProperties": true }, "settings": { "type": "object", "additionalProperties": true }, "public_token": { "type": "string" }, "public_url": { "type": "string" }, "subscribers_90d": { "type": "integer" }, "views_90d": { "type": "integer" }, "conversion_rate_90d": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "LandingPageSubmission": { "type": "object", "required": [ "id", "landing_page_id", "landing_page_name", "landing_page_slug", "landing_page_public_url", "form_block_id", "subscriber", "submitted_at" ], "properties": { "id": { "type": "string" }, "landing_page_id": { "type": "string" }, "landing_page_name": { "type": "string" }, "landing_page_slug": { "type": "string" }, "landing_page_public_url": { "type": "string" }, "form_block_id": { "type": "string" }, "subscriber": { "$ref": "#/components/schemas/Subscriber" }, "submitted_at": { "type": "string", "format": "date-time" } } }, "LandingPageUpsertRequest": { "type": "object", "required": [ "name", "slug", "definition" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "custom_path": { "type": "string", "nullable": true, "description": "Optional Pro custom slug. Omit this field to keep the existing custom slug when updating a landing page." }, "customPath": { "type": "string", "nullable": true, "description": "Camel-case alias for custom_path. Omit this field to keep the existing custom slug when updating a landing page." }, "definition": { "type": "object", "additionalProperties": true }, "styles": { "type": "object", "additionalProperties": true }, "settings": { "type": "object", "additionalProperties": true } } }, "EmailTemplate": { "type": "object", "required": [ "id", "name", "body", "body_document", "enabled", "workspaces", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "maxLength": 160 }, "body": { "type": "string" }, "body_document": { "type": "object", "description": "Structured email editor content. The serialized document must be 512000 bytes or less.", "additionalProperties": true }, "enabled": { "type": "boolean" }, "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceReference" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "EmailTemplateUpsertRequest": { "type": "object", "required": [ "name", "body_document" ], "properties": { "name": { "type": "string", "maxLength": 160 }, "body_document": { "type": "object", "description": "Structured email editor content. The serialized document must be 512000 bytes or less.", "additionalProperties": true }, "enabled": { "type": "boolean" } } }, "Sequence": { "type": "object", "required": [ "id", "name", "status", "connection_id", "from_name", "from_email", "reply_to_email", "track_opens", "track_clicks", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "definition", "subscriber_count", "open_rate", "click_rate", "unsubscribed_count", "bounced_count", "complained_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "paused" ] }, "connection_id": { "type": "string", "nullable": true }, "from_name": { "type": "string", "nullable": true }, "from_email": { "type": "string", "nullable": true }, "reply_to_email": { "type": "string", "nullable": true }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true }, "definition": { "type": "object", "additionalProperties": true }, "subscriber_count": { "type": "integer" }, "open_rate": { "type": "integer" }, "click_rate": { "type": "integer" }, "unsubscribed_count": { "type": "integer" }, "bounced_count": { "type": "integer" }, "complained_count": { "type": "integer" }, "send_progress": { "allOf": [ { "$ref": "#/components/schemas/BroadcastSendProgress" } ], "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BroadcastSendProgress": { "type": "object", "required": [ "run_id", "phase", "materialized", "accepted", "skipped", "retrying", "permanent_failed", "unknown", "canceled", "percent_complete", "effective_rate", "provider_limited_rate", "estimated_completion", "last_progress_at", "pause_reason", "next_retry_at", "terminal" ], "properties": { "run_id": { "type": "string" }, "phase": { "type": "string", "enum": [ "preparing", "sending", "paused", "canceling", "sent", "sent_with_errors", "canceled", "failed" ] }, "materialized": { "type": "integer" }, "accepted": { "type": "integer" }, "skipped": { "type": "integer" }, "retrying": { "type": "integer" }, "permanent_failed": { "type": "integer" }, "unknown": { "type": "integer" }, "canceled": { "type": "integer" }, "percent_complete": { "type": "number" }, "effective_rate": { "type": "number" }, "provider_limited_rate": { "type": "number", "nullable": true }, "estimated_completion": { "type": "string", "format": "date-time", "nullable": true }, "last_progress_at": { "type": "string", "format": "date-time", "nullable": true }, "pause_reason": { "type": "string", "nullable": true }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true }, "terminal": { "type": "boolean" } } }, "BroadcastSendPreflight": { "type": "object", "description": "Current Subscriber estimate, provider capacity, sender and event setup health, duration estimate, confirmation requirement, and blocking issues.", "required": [ "workspace_id", "broadcast_id", "subject", "recipient_estimate", "connection", "provider_production_status", "remaining_daily_quota", "safe_send_rate", "estimated_duration_seconds", "sender_authentication_status", "event_webhook_health", "confirmation_required", "confirmation_threshold", "blocking_issues", "checked_at" ], "properties": { "workspace_id": { "type": "string" }, "broadcast_id": { "type": "string" }, "subject": { "type": "string" }, "recipient_estimate": { "type": "integer", "minimum": 0 }, "connection": { "type": "object", "required": [ "id", "name", "provider" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } } }, "provider_production_status": { "type": "string", "enum": [ "production", "restricted", "unknown" ] }, "remaining_daily_quota": { "type": "integer", "minimum": 0, "nullable": true }, "safe_send_rate": { "type": "number", "exclusiveMinimum": 0, "nullable": true }, "estimated_duration_seconds": { "type": "integer", "minimum": 0, "nullable": true }, "sender_authentication_status": { "type": "string", "enum": [ "verified", "unverified", "unknown" ] }, "event_webhook_health": { "type": "string", "enum": [ "healthy", "missing", "unknown" ] }, "confirmation_required": { "type": "boolean" }, "confirmation_threshold": { "type": "integer", "minimum": 1 }, "blocking_issues": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "resolution" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "resolution": { "type": "string" } } } }, "checked_at": { "type": "string", "format": "date-time" } } }, "BroadcastDeliveryError": { "type": "object", "required": [ "id", "subscriber_id", "outcome", "attempt_count", "error_code", "updated_at" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "subscriber_id": { "type": "string" }, "outcome": { "type": "string", "enum": [ "failed", "unknown" ] }, "attempt_count": { "type": "integer", "minimum": 0 }, "error_code": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } } }, "SequenceUpsertRequest": { "type": "object", "required": [ "name", "definition" ], "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "paused" ] }, "connection_id": { "type": "string", "nullable": true }, "reply_to_email": { "type": "string", "nullable": true }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true }, "definition": { "type": "object", "additionalProperties": true } } }, "Automation": { "type": "object", "required": [ "id", "name", "status", "definition", "subscriber_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "running", "paused" ] }, "definition": { "type": "object", "additionalProperties": true }, "subscriber_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AutomationUpsertRequest": { "type": "object", "required": [ "name", "definition" ], "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "running", "paused" ] }, "definition": { "type": "object", "additionalProperties": true } } }, "MagicLink": { "type": "object", "required": [ "id", "name", "target_type", "redirect_url", "success_message", "add_tag_ids", "remove_tag_ids", "add_sequence_ids", "remove_sequence_ids", "click_count", "public_url", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "target_type": { "type": "string", "enum": [ "redirect", "message" ] }, "redirect_url": { "type": "string" }, "success_message": { "type": "string" }, "add_tag_ids": { "type": "array", "items": { "type": "string" } }, "remove_tag_ids": { "type": "array", "items": { "type": "string" } }, "add_sequence_ids": { "type": "array", "items": { "type": "string" } }, "remove_sequence_ids": { "type": "array", "items": { "type": "string" } }, "click_count": { "type": "integer" }, "public_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MagicLinkUpsertRequest": { "type": "object", "required": [ "name", "target_type" ], "properties": { "name": { "type": "string" }, "target_type": { "type": "string", "enum": [ "redirect", "message" ] }, "redirect_url": { "type": "string", "nullable": true }, "success_message": { "type": "string", "nullable": true }, "add_tag_ids": { "type": "array", "items": { "type": "string" } }, "remove_tag_ids": { "type": "array", "items": { "type": "string" } }, "add_sequence_ids": { "type": "array", "items": { "type": "string" } }, "remove_sequence_ids": { "type": "array", "items": { "type": "string" } } } }, "Broadcast": { "type": "object", "required": [ "id", "subject", "preview_text", "body", "body_document", "status", "scheduled_at", "completed_at", "connection_id", "from_name", "from_email", "reply_to_email", "audience_definition", "track_opens", "track_clicks", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "recipient_count", "opened_count", "clicked_count", "unsubscribed_count", "bounced_count", "complained_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "subject": { "type": "string" }, "preview_text": { "type": "string", "nullable": true }, "body": { "type": "string" }, "body_document": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "draft", "scheduled", "running", "completed", "failed" ] }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "connection_id": { "type": "string", "nullable": true }, "from_name": { "type": "string", "nullable": true }, "from_email": { "type": "string", "nullable": true }, "reply_to_email": { "type": "string", "nullable": true }, "audience_definition": { "type": "object", "nullable": true, "additionalProperties": true }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true }, "recipient_count": { "type": "integer" }, "opened_count": { "type": "integer" }, "clicked_count": { "type": "integer" }, "unsubscribed_count": { "type": "integer" }, "bounced_count": { "type": "integer" }, "complained_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BroadcastUpsertRequest": { "type": "object", "required": [ "subject", "body_document" ], "properties": { "subject": { "type": "string" }, "preview_text": { "type": "string", "nullable": true }, "body_document": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "draft", "scheduled" ] }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "connection_id": { "type": "string", "nullable": true }, "reply_to_email": { "type": "string", "nullable": true }, "audience_definition": { "type": "object", "nullable": true, "additionalProperties": true }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true } } }, "BroadcastTestRequest": { "type": "object", "required": [ "recipient" ], "properties": { "recipient": { "type": "string", "format": "email" } } }, "ActionResult": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "completed" ] } } }, "Segment": { "type": "object", "required": [ "id", "name", "description", "definition", "confirmed_subscriber_count", "total_subscriber_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "definition": { "type": "object", "additionalProperties": true }, "confirmed_subscriber_count": { "type": "integer" }, "total_subscriber_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SegmentUpsertRequest": { "type": "object", "required": [ "name", "definition" ], "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "definition": { "type": "object", "description": "The segment filters. Include at least one filter group.", "additionalProperties": true } } }, "SegmentPreviewRequest": { "type": "object", "required": [ "definition" ], "properties": { "definition": { "type": "object", "description": "The segment filters to preview. Include at least one filter group.", "additionalProperties": true }, "current_segment_id": { "type": "string", "nullable": true, "description": "When previewing an edit to an existing segment, include that segment id so Mailrith can catch circular segment references before saving." } } }, "SegmentPreview": { "type": "object", "required": [ "confirmed_subscriber_count", "total_subscriber_count" ], "properties": { "confirmed_subscriber_count": { "type": "integer" }, "total_subscriber_count": { "type": "integer" } } }, "SubscriberImportJob": { "type": "object", "required": [ "id", "status", "imported_count", "error_message", "started_at", "completed_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "Queued", "Processing", "Completed", "Failed" ] }, "imported_count": { "type": "integer", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SubscriberImportJobCreateRequest": { "type": "object", "required": [ "csv_text", "mappings" ], "properties": { "csv_text": { "type": "string" }, "mappings": { "type": "array", "description": "Map each CSV column and each Mailrith field only once. Every csv_column value must exactly match a header in csv_text.", "items": { "type": "object", "required": [ "csv_column", "field" ], "properties": { "csv_column": { "type": "string" }, "field": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "email", "name", "custom-field", "country", "subscriber-status" ] }, "custom_field_id": { "type": "string", "nullable": true } } } } } }, "new_tag_name": { "type": "string", "nullable": true }, "existing_tag_ids": { "type": "array", "items": { "type": "string" } }, "sequence_ids": { "type": "array", "items": { "type": "string" } } } }, "SubscriberExportJob": { "type": "object", "required": [ "id", "status", "selection", "exported_count", "file_name", "download_url", "expires_at", "error_message", "started_at", "completed_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "Queued", "Processing", "Completed", "Failed" ] }, "selection": { "type": "object", "required": [ "query", "status", "cold_only" ], "properties": { "query": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked", null ] }, "cold_only": { "type": "boolean" } } }, "exported_count": { "type": "integer", "nullable": true }, "file_name": { "type": "string", "nullable": true }, "download_url": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SubscriberExportJobCreateRequest": { "type": "object", "properties": { "query": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked", null ] }, "cold_only": { "type": "boolean" } } } } }, "paths": { "/v1": { "get": { "method": "GET", "path": "/v1", "summary": "Get API metadata", "description": "Returns the current public API version and discovery links for docs, llms files, the OpenAPI contract, webhook subscriptions, and the authenticated capability endpoint.", "tags": [ "Platform" ], "operationId": "getPublicApiMeta", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMetadata" } } } } } } }, "/v1/capabilities": { "get": { "method": "GET", "path": "/v1/capabilities", "summary": "Get authenticated API capabilities", "description": "Returns the current workspace context, discovery URLs, shared request conventions, supported webhook events, and public resource operations available to the authenticated bearer credential.", "tags": [ "Platform" ], "operationId": "getPublicApiCapabilities", "security": [ { "WorkspaceApiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Capabilities" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/openapi.json": { "get": { "method": "GET", "path": "/v1/openapi.json", "summary": "Get the OpenAPI document", "description": "Returns the machine-readable OpenAPI 3.1 contract for the current public API.", "tags": [ "Platform" ], "operationId": "getPublicApiOpenApiDocument", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/workspace": { "get": { "method": "GET", "path": "/v1/workspace", "summary": "Get the current workspace", "description": "Returns the authenticated workspace profile and mailing context used by broadcasts, sequences, automations, forms, and magic links.", "tags": [ "Workspace" ], "operationId": "getWorkspace", "security": [ { "WorkspaceApiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-subscriptions": { "get": { "method": "GET", "path": "/v1/webhook-subscriptions", "summary": "List webhook subscriptions", "description": "Returns the outbound webhook subscriptions configured for the authenticated workspace.", "tags": [ "Webhooks" ], "operationId": "listWebhookSubscriptions", "security": [ { "WorkspaceApiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/webhook-subscriptions", "summary": "Create a webhook subscription", "description": "Creates a signed outbound webhook subscription and returns the signing secret once. The caller must also have read scopes for the selected event families.", "tags": [ "Webhooks" ], "operationId": "createWebhookSubscription", "security": [ { "WorkspaceApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateRequest" } } } }, "responses": { "201": { "description": "Webhook subscription created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscriptionCreateResult" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-subscriptions/{webhook_subscription_id}": { "get": { "method": "GET", "path": "/v1/webhook-subscriptions/{webhook_subscription_id}", "summary": "Get a webhook subscription", "description": "Returns one outbound webhook subscription configured for the authenticated workspace.", "tags": [ "Webhooks" ], "operationId": "getWebhookSubscription", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "webhook_subscription_id", "in": "path", "required": true, "description": "The webhook subscription identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/webhook-subscriptions/{webhook_subscription_id}", "summary": "Update a webhook subscription", "description": "Updates the destination URL, status, or event pattern set for an existing webhook subscription. The caller must also have read scopes for the subscription's event families.", "tags": [ "Webhooks" ], "operationId": "updateWebhookSubscription", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "webhook_subscription_id", "in": "path", "required": true, "description": "The webhook subscription identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/webhook-subscriptions/{webhook_subscription_id}", "summary": "Delete a webhook subscription", "description": "Deletes an existing outbound webhook subscription from the authenticated workspace.", "tags": [ "Webhooks" ], "operationId": "deleteWebhookSubscription", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "webhook_subscription_id", "in": "path", "required": true, "description": "The webhook subscription identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscription deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/email-templates": { "get": { "method": "GET", "path": "/v1/email-templates", "summary": "List email templates", "description": "Returns reusable email templates linked to the authenticated workspace.", "tags": [ "Email Templates" ], "operationId": "listEmailTemplates", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplate" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/email-templates", "summary": "Create an email template", "description": "Creates a reusable email template scoped to the authenticated workspace.", "tags": [ "Email Templates" ], "operationId": "createEmailTemplate", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateUpsertRequest" } } } }, "responses": { "201": { "description": "Email template created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/email-templates/{template_id}": { "get": { "method": "GET", "path": "/v1/email-templates/{template_id}", "summary": "Get an email template", "description": "Returns a reusable email template linked to the authenticated workspace.", "tags": [ "Email Templates" ], "operationId": "getEmailTemplate", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "The email template identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/email-templates/{template_id}", "summary": "Update an email template", "description": "Updates the content or enabled state of an existing email template.", "tags": [ "Email Templates" ], "operationId": "updateEmailTemplate", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "The email template identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current email template state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/email-templates/{template_id}", "summary": "Delete an email template", "description": "Deletes an existing email template linked to the authenticated workspace.", "tags": [ "Email Templates" ], "operationId": "deleteEmailTemplate", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "The email template identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Email template deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current email template state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts": { "get": { "method": "GET", "path": "/v1/broadcasts", "summary": "List broadcasts", "description": "Returns broadcast drafts, scheduled sends, active sends, and completed sends.", "tags": [ "Broadcasts" ], "operationId": "listBroadcasts", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/broadcasts", "summary": "Create a broadcast", "description": "Creates a broadcast draft or scheduled broadcast in the authenticated workspace.", "tags": [ "Broadcasts" ], "operationId": "createBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastUpsertRequest" } } } }, "responses": { "201": { "description": "Broadcast created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts/{broadcast_id}": { "get": { "method": "GET", "path": "/v1/broadcasts/{broadcast_id}", "summary": "Get a broadcast", "description": "Returns a broadcast draft, scheduled send, active send, or completed send.", "tags": [ "Broadcasts" ], "operationId": "getBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/broadcasts/{broadcast_id}", "summary": "Update a broadcast", "description": "Updates a broadcast draft or scheduled send in place.", "tags": [ "Broadcasts" ], "operationId": "updateBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/broadcasts/{broadcast_id}", "summary": "Delete a broadcast", "description": "Deletes a draft, scheduled, or failed broadcast from the authenticated workspace. Broadcasts cannot be deleted after they start sending.", "tags": [ "Broadcasts" ], "operationId": "deleteBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Broadcast deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Broadcast cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts/{broadcast_id}/preflight": { "get": { "method": "GET", "path": "/v1/broadcasts/{broadcast_id}/preflight", "summary": "Check a broadcast before sending", "description": "Checks the current Subscriber estimate, provider capacity, sender setup, event tracking, and high-volume confirmation requirement.", "tags": [ "Broadcasts" ], "operationId": "preflightBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Broadcast preflight", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BroadcastSendPreflight" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts/{broadcast_id}/progress": { "get": { "method": "GET", "path": "/v1/broadcasts/{broadcast_id}/progress", "summary": "Get broadcast send progress", "description": "Returns bounded delivery progress, current rates, timing, outcome counts, and pause state. Poll until terminal is true; use 5 to 10 second intervals while progress changes and back off to 30 seconds when unchanged.", "tags": [ "Broadcasts" ], "operationId": "getBroadcastSendProgress", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Broadcast send progress", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BroadcastSendProgress" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts/{broadcast_id}/delivery-errors": { "get": { "method": "GET", "path": "/v1/broadcasts/{broadcast_id}/delivery-errors", "summary": "List broadcast delivery errors", "description": "Returns a cursor-paginated page of permanent failures and unknown delivery results.", "tags": [ "Broadcasts" ], "operationId": "listBroadcastDeliveryErrors", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "The last delivery ID returned by the previous page.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "The number of errors to return, from 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Delivery error page", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BroadcastDeliveryError" } }, "next_cursor": { "type": "integer", "nullable": true } } } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts/{broadcast_id}/send": { "post": { "method": "POST", "path": "/v1/broadcasts/{broadcast_id}/send", "summary": "Send a broadcast now", "description": "Accepts asynchronous delivery for a broadcast draft or scheduled send. A 202 response means the durable send was accepted, not that provider delivery is complete. Reuse the same idempotency key if the response is lost.", "tags": [ "Broadcasts" ], "operationId": "sendBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to make retries safe.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "object", "nullable": true, "description": "Required for high-volume sends. Repeat the exact workspace ID, Broadcast subject, Subscriber estimate, connection ID, and estimated duration returned by preflight.", "required": [ "workspace_id", "subject", "recipient_estimate", "connection_id", "estimated_duration_seconds" ], "properties": { "workspace_id": { "type": "string" }, "subject": { "type": "string" }, "recipient_estimate": { "type": "integer", "minimum": 0 }, "connection_id": { "type": "string" }, "estimated_duration_seconds": { "type": "integer", "minimum": 0, "nullable": true } } } } } } } }, "responses": { "202": { "description": "Broadcast send started", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "run_id", "resource" ], "properties": { "status": { "type": "string", "enum": [ "running" ] }, "run_id": { "type": "string" }, "resource": { "$ref": "#/components/schemas/Broadcast" } } } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflicts with the current resource state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts/{broadcast_id}/cancel": { "post": { "method": "POST", "path": "/v1/broadcasts/{broadcast_id}/cancel", "summary": "Cancel a broadcast send", "description": "Requests cancellation for delivery work that has not reached the provider. Provider-accepted emails cannot be recalled. Repeat the same request with the same idempotency key when the response is lost.", "tags": [ "Broadcasts" ], "operationId": "cancelBroadcastSend", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to make retries safe.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Broadcast cancellation accepted or already complete", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "run_id", "changed", "recovery_pending", "message" ], "properties": { "status": { "type": "string", "enum": [ "canceling", "canceled" ], "description": "canceling while remaining work is stopping, or canceled when cancellation already finished." }, "run_id": { "type": "string" }, "changed": { "type": "boolean" }, "recovery_pending": { "type": "boolean" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Broadcast send not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Broadcast send can no longer be canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts/{broadcast_id}/test": { "post": { "method": "POST", "path": "/v1/broadcasts/{broadcast_id}/test", "summary": "Send a broadcast test email", "description": "Sends a test message from an existing broadcast to one recipient.", "tags": [ "Broadcasts" ], "operationId": "testBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to make retries safe.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastTestRequest" } } } }, "responses": { "200": { "description": "Test email sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ActionResult" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sequences": { "get": { "method": "GET", "path": "/v1/sequences", "summary": "List sequences", "description": "Returns sequences in the authenticated workspace.", "tags": [ "Sequences" ], "operationId": "listSequences", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "description": "Filter sequences by ID, name, or status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of sequences to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Use the opaque cursor from the previous page to request the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sequence" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/sequences", "summary": "Create a sequence", "description": "Creates a sequence in the authenticated workspace.", "tags": [ "Sequences" ], "operationId": "createSequence", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to make retries safe.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceUpsertRequest" } } } }, "responses": { "201": { "description": "Sequence created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Sequence" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sequences/{sequence_id}": { "get": { "method": "GET", "path": "/v1/sequences/{sequence_id}", "summary": "Get a sequence", "description": "Returns one sequence from the authenticated workspace.", "tags": [ "Sequences" ], "operationId": "getSequence", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "sequence_id", "in": "path", "required": true, "description": "The sequence identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Sequence" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/sequences/{sequence_id}", "summary": "Update a sequence", "description": "Updates an existing sequence.", "tags": [ "Sequences" ], "operationId": "updateSequence", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "sequence_id", "in": "path", "required": true, "description": "The sequence identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Sequence" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/sequences/{sequence_id}", "summary": "Delete a sequence", "description": "Deletes an existing sequence from the authenticated workspace.", "tags": [ "Sequences" ], "operationId": "deleteSequence", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "sequence_id", "in": "path", "required": true, "description": "The sequence identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Sequence was deleted" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/automations": { "get": { "method": "GET", "path": "/v1/automations", "summary": "List automations", "description": "Returns automations in the authenticated workspace.", "tags": [ "Automations" ], "operationId": "listAutomations", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of automations to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Use the opaque cursor from the previous page to request the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/automations", "summary": "Create an automation", "description": "Creates an automation in the authenticated workspace.", "tags": [ "Automations" ], "operationId": "createAutomation", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to make retries safe.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationUpsertRequest" } } } }, "responses": { "201": { "description": "Automation created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Automation" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/automations/{automation_id}": { "get": { "method": "GET", "path": "/v1/automations/{automation_id}", "summary": "Get an automation", "description": "Returns one automation from the authenticated workspace.", "tags": [ "Automations" ], "operationId": "getAutomation", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "automation_id", "in": "path", "required": true, "description": "The automation identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Automation" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/automations/{automation_id}", "summary": "Update an automation", "description": "Updates an existing automation.", "tags": [ "Automations" ], "operationId": "updateAutomation", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "automation_id", "in": "path", "required": true, "description": "The automation identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Automation" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/automations/{automation_id}", "summary": "Delete an automation", "description": "Deletes an automation from the authenticated workspace.", "tags": [ "Automations" ], "operationId": "deleteAutomation", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "automation_id", "in": "path", "required": true, "description": "The automation identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Automation was deleted" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/magic-links": { "get": { "method": "GET", "path": "/v1/magic-links", "summary": "List magic links", "description": "Returns magic links in the authenticated workspace.", "tags": [ "Magic Links" ], "operationId": "listMagicLinks", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of magic links to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Use the opaque cursor from the previous page to request the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MagicLink" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/magic-links", "summary": "Create a magic link", "description": "Creates a magic link in the authenticated workspace.", "tags": [ "Magic Links" ], "operationId": "createMagicLink", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to make retries safe.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLinkUpsertRequest" } } } }, "responses": { "201": { "description": "Magic link created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MagicLink" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflicts with an existing resource or current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/magic-links/{magic_link_id}": { "get": { "method": "GET", "path": "/v1/magic-links/{magic_link_id}", "summary": "Get a magic link", "description": "Returns one magic link from the authenticated workspace.", "tags": [ "Magic Links" ], "operationId": "getMagicLink", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "magic_link_id", "in": "path", "required": true, "description": "The magic link identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MagicLink" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/magic-links/{magic_link_id}", "summary": "Update a magic link", "description": "Updates an existing magic link.", "tags": [ "Magic Links" ], "operationId": "updateMagicLink", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "magic_link_id", "in": "path", "required": true, "description": "The magic link identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLinkUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MagicLink" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflicts with an existing resource or current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/magic-links/{magic_link_id}", "summary": "Delete a magic link", "description": "Deletes a magic link from the authenticated workspace.", "tags": [ "Magic Links" ], "operationId": "deleteMagicLink", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "magic_link_id", "in": "path", "required": true, "description": "The magic link identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Magic link was deleted" }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/subscribers": { "get": { "method": "GET", "path": "/v1/subscribers", "summary": "List subscribers", "description": "Returns subscribers in the authenticated workspace, sorted from newest to oldest.", "tags": [ "Subscribers" ], "operationId": "listSubscribers", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "description": "Filter subscribers by name, email, or status.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Filter subscribers by an exact subscriber email address.", "schema": { "type": "string", "format": "email" } }, { "name": "status", "in": "query", "description": "Filter subscribers by subscriber status.", "schema": { "type": "string", "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked" ] } }, { "name": "cold_only", "in": "query", "description": "When `true`, return only cold subscribers.", "schema": { "type": "boolean" } }, { "name": "tag_id", "in": "query", "description": "Return subscribers that currently have this tag ID. Repeat `tag_id` or use `tag_ids` to match any of several tags.", "schema": { "type": "string" } }, { "name": "tag_ids", "in": "query", "description": "Comma-separated tag IDs. By default, the API returns subscribers who have any listed tag.", "schema": { "type": "string" } }, { "name": "tag_operator", "in": "query", "description": "Controls how tag filters are applied. Defaults to `has_any_of`.", "schema": { "type": "string", "enum": [ "has_any_of", "has_none_of" ], "default": "has_any_of" } }, { "name": "sequence_id", "in": "query", "description": "Return subscribers that match this sequence ID. Repeat `sequence_id` or use `sequence_ids` to match any of several sequences.", "schema": { "type": "string" } }, { "name": "sequence_ids", "in": "query", "description": "Comma-separated sequence IDs. By default, the API returns only subscribers who are active in any listed sequence.", "schema": { "type": "string" } }, { "name": "sequence_operator", "in": "query", "description": "Controls how sequence filters are applied. Defaults to `is_active_in_any_of`.", "schema": { "type": "string", "enum": [ "is_active_in_any_of", "is_not_active_in_any_of", "has_completed_any_of", "has_not_completed_any_of", "has_ever_been_in_any_of", "has_never_been_in_any_of" ], "default": "is_active_in_any_of" } }, { "name": "limit", "in": "query", "description": "Maximum number of subscribers to return. Defaults to 25 and is capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Use the opaque cursor from the previous page to request the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscriber" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/subscribers", "summary": "Create or upsert a subscriber", "description": "Creates a new subscriber when the email does not exist in the workspace. If the email already exists, the API updates the existing subscriber unless create_only is true.", "tags": [ "Subscribers" ], "operationId": "upsertSubscriber", "security": [ { "WorkspaceApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberUpsertRequest" } } } }, "responses": { "200": { "description": "Existing subscriber was updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "201": { "description": "Subscriber was created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflicts with an existing resource or current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/subscribers/{subscriber_id}": { "patch": { "method": "PATCH", "path": "/v1/subscribers/{subscriber_id}", "summary": "Update a subscriber", "description": "Updates profile fields, status, custom fields, tags, or sequence assignments for one subscriber. Fields omitted from the request stay unchanged. Blank optional custom field values also leave saved values unchanged, and filled-in invalid values are rejected.", "tags": [ "Subscribers" ], "operationId": "updateSubscriber", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "subscriber_id", "in": "path", "required": true, "description": "The subscriber identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberUpdateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflicts with an existing resource or current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/subscribers/{subscriber_id}/tags/{tag_id}": { "delete": { "method": "DELETE", "path": "/v1/subscribers/{subscriber_id}/tags/{tag_id}", "summary": "Remove a tag from a subscriber", "description": "Removes the selected tag from a subscriber. If the subscriber does not have the tag, the API returns the subscriber unchanged.", "tags": [ "Subscribers" ], "operationId": "removeSubscriberTag", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "subscriber_id", "in": "path", "required": true, "description": "The subscriber identifier.", "schema": { "type": "string" } }, { "name": "tag_id", "in": "path", "required": true, "description": "The tag identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/subscribers/{subscriber_id}/sequences/{sequence_id}": { "put": { "method": "PUT", "path": "/v1/subscribers/{subscriber_id}/sequences/{sequence_id}", "summary": "Add a subscriber to a sequence", "description": "Adds the selected subscriber to the selected sequence. If the subscriber is already in the sequence, the API returns the subscriber unchanged.", "tags": [ "Subscribers" ], "operationId": "addSubscriberSequence", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "subscriber_id", "in": "path", "required": true, "description": "The subscriber identifier.", "schema": { "type": "string" } }, { "name": "sequence_id", "in": "path", "required": true, "description": "The sequence identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access is forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/subscribers/{subscriber_id}/sequences/{sequence_id}", "summary": "Remove a subscriber from a sequence", "description": "Removes the selected subscriber from the selected sequence. If the subscriber is not in the sequence, the API returns the subscriber unchanged.", "tags": [ "Subscribers" ], "operationId": "removeSubscriberSequence", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "subscriber_id", "in": "path", "required": true, "description": "The subscriber identifier.", "schema": { "type": "string" } }, { "name": "sequence_id", "in": "path", "required": true, "description": "The sequence identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tags": { "get": { "method": "GET", "path": "/v1/tags", "summary": "List tags", "description": "Returns tags in the authenticated workspace.", "tags": [ "Tags" ], "operationId": "listTags", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "description": "Filter tags by ID, name, or description.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of tags to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Use the opaque cursor from the previous page to request the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/tags", "summary": "Create a tag", "description": "Creates a new tag in the authenticated workspace. The GDPR consent tag names can be created and applied like other tags when you need to apply consent collected outside Mailrith. Tag-level double opt-in fields are no longer accepted; configure double opt-in on forms and landing pages instead.", "tags": [ "Tags" ], "operationId": "createTag", "security": [ { "WorkspaceApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCreateRequest" } } } }, "responses": { "201": { "description": "Tag was created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Tag" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflicts with an existing resource or current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/custom-fields": { "get": { "method": "GET", "path": "/v1/custom-fields", "summary": "List custom fields", "description": "Returns custom fields in the authenticated workspace.", "tags": [ "Custom Fields" ], "operationId": "listCustomFields", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of custom fields to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Use the opaque cursor from the previous page to request the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomField" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Authentication is required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/custom-fields", "summary": "Create a custom field", "description": "Creates a workspace-scoped custom-field definition.", "tags": [ "Custom Fields" ], "operationId": "createCustomField", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to make retries safe.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldUpsertRequest" } } } }, "responses": { "201": { "description": "Custom field created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomField" } } } } } }, "400": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/custom-fields/{custom_field_id}": { "get": { "method": "GET", "path": "/v1/custom-fields/{custom_field_id}", "summary": "Get a custom field", "description": "Returns one custom field from the authenticated workspace.", "tags": [ "Custom Fields" ], "operationId": "getCustomField", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "custom_field_id", "in": "path", "required": true, "description": "The custom field identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomField" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/custom-fields/{custom_field_id}", "summary": "Update a custom field", "description": "Updates a custom-field definition for the authenticated workspace.", "tags": [ "Custom Fields" ], "operationId": "updateCustomField", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "custom_field_id", "in": "path", "required": true, "description": "The identifier of the custom field to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomField" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The custom field was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current custom field state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/custom-fields/{custom_field_id}", "summary": "Delete a custom field", "description": "Deletes a custom-field definition from the authenticated workspace.", "tags": [ "Custom Fields" ], "operationId": "deleteCustomField", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "custom_field_id", "in": "path", "required": true, "description": "The identifier of the custom field to delete.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "The custom field was deleted." }, "404": { "description": "The custom field was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current custom field state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/forms": { "get": { "method": "GET", "path": "/v1/forms", "summary": "List forms", "description": "Returns forms from the authenticated workspace.", "tags": [ "Forms" ], "operationId": "listForms", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "description": "Filter forms by ID, name, or public URL token.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The maximum number of forms to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "The opaque cursor from the previous page of forms.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Form" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/forms", "summary": "Create a form", "description": "Creates a form in the authenticated workspace.", "tags": [ "Forms" ], "operationId": "createForm", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to retry the request safely.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormUpsertRequest" } } } }, "responses": { "201": { "description": "Form created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Form" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/forms/{form_id}": { "get": { "method": "GET", "path": "/v1/forms/{form_id}", "summary": "Get a form", "description": "Returns a form from the authenticated workspace.", "tags": [ "Forms" ], "operationId": "getForm", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "form_id", "in": "path", "required": true, "description": "The identifier of the form to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Form" } } } } } }, "404": { "description": "The form was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/forms/{form_id}", "summary": "Update a form", "description": "Updates an existing form without creating a new form.", "tags": [ "Forms" ], "operationId": "updateForm", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "form_id", "in": "path", "required": true, "description": "The identifier of the form to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Form" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The form was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/forms/{form_id}", "summary": "Delete a form", "description": "Deletes a form from the authenticated workspace.", "tags": [ "Forms" ], "operationId": "deleteForm", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "form_id", "in": "path", "required": true, "description": "The identifier of the form to delete.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "The form was deleted." }, "404": { "description": "The form was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/forms/{form_id}/submissions": { "get": { "method": "GET", "path": "/v1/forms/{form_id}/submissions", "summary": "List form submissions", "description": "Returns recent real submissions for one form, including the subscriber who submitted the form. Requires both `forms:read` and `subscribers:read`.", "tags": [ "Forms" ], "operationId": "listFormSubmissions", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "form_id", "in": "path", "required": true, "description": "The identifier of the form whose submissions you want to list.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The maximum number of submissions to return. Defaults to 25 and is capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "The opaque cursor from the previous page of form submissions.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormSubmission" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "404": { "description": "The form was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/landing-pages": { "get": { "method": "GET", "path": "/v1/landing-pages", "summary": "List landing pages", "description": "Returns landing pages from the authenticated workspace.", "tags": [ "Landing Pages" ], "operationId": "listLandingPages", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "description": "Filter landing pages by ID, name, slug, custom path, or public URL token.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The maximum number of landing pages to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "The opaque cursor from the previous page of landing pages.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPage" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/landing-pages", "summary": "Create a landing page", "description": "Creates a hosted landing page in the authenticated workspace.", "tags": [ "Landing Pages" ], "operationId": "createLandingPage", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to retry the request safely.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageUpsertRequest" } } } }, "responses": { "201": { "description": "Landing page created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LandingPage" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current landing page state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/landing-pages/{landing_page_id}": { "get": { "method": "GET", "path": "/v1/landing-pages/{landing_page_id}", "summary": "Get a landing page", "description": "Returns a landing page from the authenticated workspace.", "tags": [ "Landing Pages" ], "operationId": "getLandingPage", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "landing_page_id", "in": "path", "required": true, "description": "The identifier of the landing page to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LandingPage" } } } } } }, "404": { "description": "The landing page was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/landing-pages/{landing_page_id}", "summary": "Update a landing page", "description": "Updates an existing hosted landing page without creating a new landing page.", "tags": [ "Landing Pages" ], "operationId": "updateLandingPage", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "landing_page_id", "in": "path", "required": true, "description": "The identifier of the landing page to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingPageUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LandingPage" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The landing page was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current landing page state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/landing-pages/{landing_page_id}", "summary": "Delete a landing page", "description": "Deletes a landing page from the authenticated workspace.", "tags": [ "Landing Pages" ], "operationId": "deleteLandingPage", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "landing_page_id", "in": "path", "required": true, "description": "The identifier of the landing page to delete.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "The landing page was deleted." }, "404": { "description": "The landing page was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/landing-pages/{landing_page_id}/submissions": { "get": { "method": "GET", "path": "/v1/landing-pages/{landing_page_id}/submissions", "summary": "List landing page submissions", "description": "Returns recent real submissions for one landing page, including the subscriber who submitted the landing page. Requires both `landing_pages:read` and `subscribers:read`.", "tags": [ "Landing Pages" ], "operationId": "listLandingPageSubmissions", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "landing_page_id", "in": "path", "required": true, "description": "The identifier of the landing page whose submissions you want to list.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The maximum number of submissions to return. Defaults to 25 and is capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "The opaque cursor from the previous page of landing page submissions.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPageSubmission" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "404": { "description": "The landing page was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/segments": { "get": { "method": "GET", "path": "/v1/segments", "summary": "List segments", "description": "Returns saved segments from the authenticated workspace.", "tags": [ "Segments" ], "operationId": "listSegments", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "The maximum number of segments to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "The opaque cursor from the previous page of saved segments.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "The request is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/segments", "summary": "Create a segment", "description": "Creates a saved segment in the authenticated workspace.", "tags": [ "Segments" ], "operationId": "createSegment", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to retry the request safely.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentUpsertRequest" } } } }, "responses": { "201": { "description": "Segment created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Segment" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current segment state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/segments/{segment_id}": { "get": { "method": "GET", "path": "/v1/segments/{segment_id}", "summary": "Get a segment", "description": "Returns one saved segment from the authenticated workspace.", "tags": [ "Segments" ], "operationId": "getSegment", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "segment_id", "in": "path", "required": true, "description": "The identifier of the segment to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Segment" } } } } } }, "404": { "description": "The segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/segments/{segment_id}", "summary": "Update a segment", "description": "Updates a saved segment in the authenticated workspace.", "tags": [ "Segments" ], "operationId": "updateSegment", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "segment_id", "in": "path", "required": true, "description": "The identifier of the segment to update.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Segment" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current segment state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/segments/{segment_id}", "summary": "Delete a segment", "description": "Deletes a saved segment from the authenticated workspace.", "tags": [ "Segments" ], "operationId": "deleteSegment", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "segment_id", "in": "path", "required": true, "description": "The identifier of the segment to delete.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "The segment was deleted." }, "404": { "description": "The segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The request conflicts with the current segment state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/segments/preview": { "post": { "method": "POST", "path": "/v1/segments/preview", "summary": "Preview a segment definition", "description": "Returns subscriber counts for an unsaved segment definition. Include `current_segment_id` when previewing edits to an existing segment so circular segment references are rejected before saving.", "tags": [ "Segments" ], "operationId": "previewSegment", "security": [ { "WorkspaceApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentPreviewRequest" } } } }, "responses": { "200": { "description": "The preview counts were returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SegmentPreview" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/subscriber-imports": { "post": { "method": "POST", "path": "/v1/jobs/subscriber-imports", "summary": "Create a subscriber import job", "description": "Queues an asynchronous import job that creates or updates subscribers from CSV text.", "tags": [ "Jobs" ], "operationId": "createSubscriberImportJob", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to retry the request safely.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberImportJobCreateRequest" } } } }, "responses": { "202": { "description": "The import job was queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SubscriberImportJob" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/subscriber-imports/{job_id}": { "get": { "method": "GET", "path": "/v1/jobs/subscriber-imports/{job_id}", "summary": "Get a subscriber import job", "description": "Returns the current state of a previously created import job.", "tags": [ "Jobs" ], "operationId": "getSubscriberImportJob", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The identifier of the import job to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The import job was returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SubscriberImportJob" } } } } } }, "404": { "description": "The import job was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/subscriber-exports": { "post": { "method": "POST", "path": "/v1/jobs/subscriber-exports", "summary": "Create a subscriber export job", "description": "Queues an asynchronous subscriber export for the authenticated workspace. Requires `jobs:write` and `subscribers:read` because the finished file contains subscriber data.", "tags": [ "Jobs" ], "operationId": "createSubscriberExportJob", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to retry the request safely.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberExportJobCreateRequest" } } } }, "responses": { "202": { "description": "The export job was queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SubscriberExportJob" } } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/subscriber-exports/{job_id}": { "get": { "method": "GET", "path": "/v1/jobs/subscriber-exports/{job_id}", "summary": "Get a subscriber export job", "description": "Returns the current state of a previously created export job. Requires `jobs:read` and `subscribers:read` because completed jobs include a subscriber CSV download URL.", "tags": [ "Jobs" ], "operationId": "getSubscriberExportJob", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The identifier of the export job to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The export job was returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SubscriberExportJob" } } } } } }, "404": { "description": "The export job was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }