Reference

API Reference

OpenAPI reference for the Wraps Platform API. Browse endpoints, auth, and the interactive spec.

Interactive API Explorer

Try endpoints directly in your browser with the OpenAPI spec.

Open Swagger UI

Base URL

All API requests are made to:

Authentication

Authenticate using a Bearer token in the Authorization header. Two methods are supported:

API Key

Prefixed with wraps_. Best for server-to-server and SDK usage.

Create keys in the dashboard under Settings > API Keys.

Session Token

better-auth session token. Used by the dashboard and browser-based clients.

Endpoints

The API is organized into endpoint groups. See the interactive docs for full request/response schemas.

HealthPublic

Health check and API info

GET

Contacts

Create, update, delete, and list contacts

GETPOSTPATCHPUTDELETE

Batch

Batch email sending for broadcasts

POSTGETDELETE

Events

Custom event ingestion for triggering workflows

POST

Workflows

API-triggered workflow execution

POST

Connections

AWS account connection management

GETPOSTDELETE

WebhooksPublic

Receive SES delivery events

POST

UnsubscribePublic

RFC 8058 one-click unsubscribe

GETPOST

ToolsPublic

Free email deliverability tools

GETPOST

Workflows

Trigger, manage, and control workflow executions via the API. Workflows must have triggerType: "api" and be enabled.

Trigger Workflow

POST/v1/workflows/:workflowId/trigger

Triggers a workflow for a single contact. Identify the contact by ID or email. Arbitrary data can be passed through to the workflow.

Field	Type	Description
`contactId`	string	Contact UUID (provide this or contactEmail)
`contactEmail`	string	Contact email (alternative to contactId)
`data`	object	Arbitrary data passed to the workflow

Batch Trigger Workflow

POST/v1/workflows/:workflowId/trigger/batch

Trigger a workflow for multiple contacts in one request. Per-contact data is merged with common data. Duplicate contacts are automatically deduplicated.

Field	Type	Description
`contacts`	array	Array of `{ contactId?, contactEmail?, data? }`
`data`	object	Common data merged into every trigger

Retry Failed Execution

POST/v1/workflows/executions/:executionId/retry

Retries a failed workflow execution from the step where it failed. Previously completed steps are preserved. Only executions with status failed can be retried.

Cancel Execution

POST/v1/workflows/executions/:executionId/cancel

Cancels an active workflow execution. Cleans up any pending schedulers and adjusts workflow stats.

Batch Sending

The GET /v1/batch/:id endpoint returns the full batch status including progress tracking fields:

Field	Type	Description
`id`	string	Batch ID
`status`	string	queued, scheduled, processing, completed, failed, or cancelled
`channel`	string	email or sms
`name`	string \| null	Batch name
`totalRecipients`	number	Total targeted recipients
`processedRecipients`	number	Recipients processed so far
`sent`	number	Successfully sent count
`failed`	number	Failed send count
`startedAt`	string \| null	ISO 8601 timestamp when processing began
`completedAt`	string \| null	ISO 8601 timestamp when processing finished
`createdAt`	string	ISO 8601 creation timestamp

Use DELETE /v1/batch/:id to cancel a batch in scheduled, queued, or processing status.

Contact Topics: PATCH vs PUT

Topic subscriptions support two update strategies with different semantics:

PATCH /v1/contacts/:id

Adds topics to existing subscriptions. No topics are removed. Safe for incremental updates from multiple sources.

PUT /v1/contacts/:id/topics

Replaces all subscriptions. Topics not in the new list are unsubscribed. Triggers workflow events for both additions and removals.

Both endpoints accept topicIds (UUIDs) and topicSlugs (human-readable slugs). Topics with double opt-in enabled will send a confirmation email unless the contact was previously confirmed.