API Reference

The full API reference is generated from the same public contract used by the API worker and SDK tooling. Use the API reference to find exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.

8 min read

OpenAPI Contract

Download the exact schema document that powers this reference and the public worker.

Download OpenAPI JSON

Platform

Version metadata, discovery URLs, capability discovery, and the machine-readable OpenAPI document.

GET /v1

Get API metadata

Returns the current public API version and discovery links for docs, llms files, the OpenAPI contract, webhook subscriptions, and the authenticated capability endpoint.

getPublicApiMeta

Responses

200 Successful response

{
  "$ref": "#/components/schemas/ApiMetadata"
}

GET /v1/capabilities

Get authenticated API capabilities

Returns the current workspace context, discovery URLs, shared request conventions, supported webhook events, and public resource operations available to the authenticated bearer credential.

getPublicApiCapabilities

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Capabilities"
    }
  }
}

401 Unauthorized

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/openapi.json

Get the OpenAPI document

Returns the machine-readable OpenAPI 3.1 contract for the current public API.

getPublicApiOpenApiDocument

Responses

200 Successful response

{
  "type": "object"
}

Workspace

Read the current authenticated workspace profile and execution context.

GET /v1/workspace

Get the current workspace

Returns the authenticated workspace profile and mailing context used by broadcasts, sequences, automations, forms, and magic links.

getWorkspace

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Workspace"
    }
  }
}

401 Unauthorized

{
  "$ref": "#/components/schemas/Error"
}

Subscribers

Create or upsert subscribers and list subscriber records in a workspace.

GET /v1/subscribers

List subscribers

Returns subscribers in the authenticated workspace, sorted from newest to oldest.

listSubscribers

Parameters

search query

Filter subscribers by name, email, or status.

email query

Filter subscribers by an exact subscriber email address.

status query

Filter subscribers by subscriber status.

cold_only query

When `true`, return only cold subscribers.

tag_id query

Return subscribers that currently have this tag ID. Repeat `tag_id` or use `tag_ids` to match any of several tags.

tag_ids query

Comma-separated tag IDs. By default, the API returns subscribers who have any listed tag.

tag_operator query

Controls how tag filters are applied. Defaults to `has_any_of`.

sequence_id query

Return subscribers that match this sequence ID. Repeat `sequence_id` or use `sequence_ids` to match any of several sequences.

sequence_ids query

Comma-separated sequence IDs. By default, the API returns only subscribers who are active in any listed sequence.

sequence_operator query

Controls how sequence filters are applied. Defaults to `is_active_in_any_of`.

limit query

Maximum number of subscribers to return. Defaults to 25 and is capped at 100.

starting_after query

Use the opaque cursor from the previous page to request the next page.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Subscriber"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 Authentication is required or invalid

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/subscribers

Create or upsert a subscriber

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.

upsertSubscriber

Request Body

{
  "$ref": "#/components/schemas/SubscriberUpsertRequest"
}

Responses

200 Existing subscriber was updated

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Subscriber"
    }
  }
}

201 Subscriber was created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Subscriber"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

401 Authentication is required or invalid

{
  "$ref": "#/components/schemas/Error"
}

409 Request conflicts with an existing resource or current state

{
  "$ref": "#/components/schemas/Error"
}

PATCH /v1/subscribers/{subscriber_id}

Update a subscriber

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.

updateSubscriber

Parameters

subscriber_id path required

The subscriber identifier.

Request Body

{
  "$ref": "#/components/schemas/SubscriberUpdateRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Subscriber"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

401 Authentication is required or invalid

{
  "$ref": "#/components/schemas/Error"
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

409 Request conflicts with an existing resource or current state

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/subscribers/{subscriber_id}/sequences/{sequence_id}

Add a subscriber to a sequence

Adds the selected subscriber to the selected sequence. If the subscriber is already in the sequence, the API returns the subscriber unchanged.

addSubscriberSequence

Parameters

subscriber_id path required

The subscriber identifier.

sequence_id path required

The sequence identifier.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Subscriber"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

401 Authentication is required or invalid

{
  "$ref": "#/components/schemas/Error"
}

403 Access is forbidden

{
  "$ref": "#/components/schemas/Error"
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/subscribers/{subscriber_id}/sequences/{sequence_id}

Remove a subscriber from a sequence

Removes the selected subscriber from the selected sequence. If the subscriber is not in the sequence, the API returns the subscriber unchanged.

removeSubscriberSequence

Parameters

subscriber_id path required

The subscriber identifier.

sequence_id path required

The sequence identifier.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Subscriber"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

401 Authentication is required or invalid

{
  "$ref": "#/components/schemas/Error"
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/subscribers/{subscriber_id}/tags/{tag_id}

Remove a tag from a subscriber

Removes the selected tag from a subscriber. If the subscriber does not have the tag, the API returns the subscriber unchanged.

removeSubscriberTag

Parameters

subscriber_id path required

The subscriber identifier.

tag_id path required

The tag identifier.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Subscriber"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

401 Authentication is required or invalid

{
  "$ref": "#/components/schemas/Error"
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

Custom Fields

Read and manage the typed custom-field schema available to the authenticated workspace.

GET /v1/custom-fields

List custom fields

Returns custom fields in the authenticated workspace.

listCustomFields

Parameters

limit query

Maximum number of custom fields to return.

starting_after query

Use the opaque cursor from the previous page to request the next page.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CustomField"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 Authentication is required or invalid

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/custom-fields

Create a custom field

Creates a workspace-scoped custom-field definition.

createCustomField

Parameters

Idempotency-Key header

Optional idempotency key to make retries safe.

Request Body

{
  "$ref": "#/components/schemas/CustomFieldUpsertRequest"
}

Responses

201 Custom field created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/CustomField"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/custom-fields/{custom_field_id}

Get a custom field

Returns one custom field from the authenticated workspace.

getCustomField

Parameters

custom_field_id path required

The custom field identifier.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/CustomField"
    }
  }
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/custom-fields/{custom_field_id}

Update a custom field

Updates a custom-field definition for the authenticated workspace.

updateCustomField

Parameters

custom_field_id path required

The identifier of the custom field to update.

Request Body

{
  "$ref": "#/components/schemas/CustomFieldUpsertRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/CustomField"
    }
  }
}

400 The request is invalid.

{
  "$ref": "#/components/schemas/Error"
}

404 The custom field was not found.

{
  "$ref": "#/components/schemas/Error"
}

409 The request conflicts with the current custom field state.

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/custom-fields/{custom_field_id}

Delete a custom field

Deletes a custom-field definition from the authenticated workspace.

deleteCustomField

Parameters

custom_field_id path required

The identifier of the custom field to delete.

Responses

204 The custom field was deleted.

404 The custom field was not found.

{
  "$ref": "#/components/schemas/Error"
}

409 The request conflicts with the current custom field state.

{
  "$ref": "#/components/schemas/Error"
}

Email Templates

Create and manage reusable email templates for the authenticated workspace.

GET /v1/email-templates

List email templates

Returns reusable email templates linked to the authenticated workspace.

listEmailTemplates

Parameters

limit query

Maximum number of items to return.

starting_after query

Opaque cursor returned by the previous page.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/EmailTemplate"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 Unauthorized

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/email-templates

Create an email template

Creates a reusable email template scoped to the authenticated workspace.

createEmailTemplate

Parameters

Idempotency-Key header

Optional idempotency key for safe retries.

Request Body

{
  "$ref": "#/components/schemas/EmailTemplateUpsertRequest"
}

Responses

201 Email template created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/EmailTemplate"
    }
  }
}

400 Invalid request

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/email-templates/{template_id}

Get an email template

Returns a reusable email template linked to the authenticated workspace.

getEmailTemplate

Parameters

template_id path required

The email template identifier.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/EmailTemplate"
    }
  }
}

404 Not found

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/email-templates/{template_id}

Update an email template

Updates the content or enabled state of an existing email template.

updateEmailTemplate

Parameters

template_id path required

The email template identifier.

Request Body

{
  "$ref": "#/components/schemas/EmailTemplateUpsertRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/EmailTemplate"
    }
  }
}

400 Invalid request

{
  "$ref": "#/components/schemas/Error"
}

404 Not found

{
  "$ref": "#/components/schemas/Error"
}

409 The request conflicts with the current email template state.

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/email-templates/{template_id}

Delete an email template

Deletes an existing email template linked to the authenticated workspace.

deleteEmailTemplate

Parameters

template_id path required

The email template identifier.

Responses

204 Email template deleted

404 Not found

{
  "$ref": "#/components/schemas/Error"
}

409 The request conflicts with the current email template state.

{
  "$ref": "#/components/schemas/Error"
}

Forms

Read and manage embeddable form definitions and presentation settings.

GET /v1/forms

List forms

Returns forms from the authenticated workspace.

listForms

Parameters

search query

Filter forms by ID, name, or public URL token.

limit query

The maximum number of forms to return.

starting_after query

The opaque cursor from the previous page of forms.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Form"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 The request is not authorized.

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/forms

Create a form

Creates a form in the authenticated workspace.

createForm

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely.

Request Body

{
  "$ref": "#/components/schemas/FormUpsertRequest"
}

Responses

201 Form created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Form"
    }
  }
}

400 The request is invalid.

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/forms/{form_id}

Get a form

Returns a form from the authenticated workspace.

getForm

Parameters

form_id path required

The identifier of the form to return.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Form"
    }
  }
}

404 The form was not found.

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/forms/{form_id}

Update a form

Updates an existing form without creating a new form.

updateForm

Parameters

form_id path required

The identifier of the form to update.

Request Body

{
  "$ref": "#/components/schemas/FormUpsertRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Form"
    }
  }
}

400 The request is invalid.

{
  "$ref": "#/components/schemas/Error"
}

404 The form was not found.

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/forms/{form_id}

Delete a form

Deletes a form from the authenticated workspace.

deleteForm

Parameters

form_id path required

The identifier of the form to delete.

Responses

204 The form was deleted.

404 The form was not found.

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/forms/{form_id}/submissions

List form submissions

Returns recent real submissions for one form, including the subscriber who submitted the form. Requires both `forms:read` and `subscribers:read`.

listFormSubmissions

Parameters

form_id path required

The identifier of the form whose submissions you want to list.

limit query

The maximum number of submissions to return. Defaults to 25 and is capped at 100.

starting_after query

The opaque cursor from the previous page of form submissions.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/FormSubmission"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

404 The form was not found.

{
  "$ref": "#/components/schemas/Error"
}

Landing Pages

Read and manage hosted landing pages, page definitions, and public URLs.

GET /v1/landing-pages

List landing pages

Returns landing pages from the authenticated workspace.

listLandingPages

Parameters

search query

Filter landing pages by ID, name, slug, custom path, or public URL token.

limit query

The maximum number of landing pages to return.

starting_after query

The opaque cursor from the previous page of landing pages.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LandingPage"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 The request is not authorized.

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/landing-pages

Create a landing page

Creates a hosted landing page in the authenticated workspace.

createLandingPage

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely.

Request Body

{
  "$ref": "#/components/schemas/LandingPageUpsertRequest"
}

Responses

201 Landing page created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/LandingPage"
    }
  }
}

400 The request is invalid.

{
  "$ref": "#/components/schemas/Error"
}

409 The request conflicts with the current landing page state.

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/landing-pages/{landing_page_id}

Get a landing page

Returns a landing page from the authenticated workspace.

getLandingPage

Parameters

landing_page_id path required

The identifier of the landing page to return.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/LandingPage"
    }
  }
}

404 The landing page was not found.

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/landing-pages/{landing_page_id}

Update a landing page

Updates an existing hosted landing page without creating a new landing page.

updateLandingPage

Parameters

landing_page_id path required

The identifier of the landing page to update.

Request Body

{
  "$ref": "#/components/schemas/LandingPageUpsertRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/LandingPage"
    }
  }
}

400 The request is invalid.

{
  "$ref": "#/components/schemas/Error"
}

404 The landing page was not found.

{
  "$ref": "#/components/schemas/Error"
}

409 The request conflicts with the current landing page state.

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/landing-pages/{landing_page_id}

Delete a landing page

Deletes a landing page from the authenticated workspace.

deleteLandingPage

Parameters

landing_page_id path required

The identifier of the landing page to delete.

Responses

204 The landing page was deleted.

404 The landing page was not found.

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/landing-pages/{landing_page_id}/submissions

List landing page submissions

Returns recent real submissions for one landing page, including the subscriber who submitted the landing page. Requires both `landing_pages:read` and `subscribers:read`.

listLandingPageSubmissions

Parameters

landing_page_id path required

The identifier of the landing page whose submissions you want to list.

limit query

The maximum number of submissions to return. Defaults to 25 and is capped at 100.

starting_after query

The opaque cursor from the previous page of landing page submissions.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LandingPageSubmission"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

404 The landing page was not found.

{
  "$ref": "#/components/schemas/Error"
}

Sequences

Create and manage email sequences, sequence status, and delivery configuration.

GET /v1/sequences

List sequences

Returns sequences in the authenticated workspace.

listSequences

Parameters

search query

Filter sequences by ID, name, or status.

limit query

Maximum number of sequences to return.

starting_after query

Use the opaque cursor from the previous page to request the next page.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Sequence"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 Authentication is required or invalid

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/sequences

Create a sequence

Creates a sequence in the authenticated workspace.

createSequence

Parameters

Idempotency-Key header

Optional idempotency key to make retries safe.

Request Body

{
  "$ref": "#/components/schemas/SequenceUpsertRequest"
}

Responses

201 Sequence created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Sequence"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/sequences/{sequence_id}

Get a sequence

Returns one sequence from the authenticated workspace.

getSequence

Parameters

sequence_id path required

The sequence identifier.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Sequence"
    }
  }
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/sequences/{sequence_id}

Update a sequence

Updates an existing sequence.

updateSequence

Parameters

sequence_id path required

The sequence identifier.

Request Body

{
  "$ref": "#/components/schemas/SequenceUpsertRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Sequence"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/sequences/{sequence_id}

Delete a sequence

Deletes an existing sequence from the authenticated workspace.

deleteSequence

Parameters

sequence_id path required

The sequence identifier.

Responses

204 Sequence was deleted

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

Automations

Create and manage automation definitions and lifecycle state.

GET /v1/automations

List automations

Returns automations in the authenticated workspace.

listAutomations

Parameters

limit query

Maximum number of automations to return.

starting_after query

Use the opaque cursor from the previous page to request the next page.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Automation"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 Authentication is required or invalid

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/automations

Create an automation

Creates an automation in the authenticated workspace.

createAutomation

Parameters

Idempotency-Key header

Optional idempotency key to make retries safe.

Request Body

{
  "$ref": "#/components/schemas/AutomationUpsertRequest"
}

Responses

201 Automation created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Automation"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/automations/{automation_id}

Get an automation

Returns one automation from the authenticated workspace.

getAutomation

Parameters

automation_id path required

The automation identifier.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Automation"
    }
  }
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/automations/{automation_id}

Update an automation

Updates an existing automation.

updateAutomation

Parameters

automation_id path required

The automation identifier.

Request Body

{
  "$ref": "#/components/schemas/AutomationUpsertRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Automation"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/automations/{automation_id}

Delete an automation

Deletes an automation from the authenticated workspace.

deleteAutomation

Parameters

automation_id path required

The automation identifier.

Responses

204 Automation was deleted

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

Magic Links

Create and manage magic links used in broadcasts, sequences, and automations.

GET /v1/magic-links

List magic links

Returns magic links in the authenticated workspace.

listMagicLinks

Parameters

limit query

Maximum number of magic links to return.

starting_after query

Use the opaque cursor from the previous page to request the next page.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/MagicLink"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 Authentication is required or invalid

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/magic-links

Create a magic link

Creates a magic link in the authenticated workspace.

createMagicLink

Parameters

Idempotency-Key header

Optional idempotency key to make retries safe.

Request Body

{
  "$ref": "#/components/schemas/MagicLinkUpsertRequest"
}

Responses

201 Magic link created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/MagicLink"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

409 Request conflicts with an existing resource or current state

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/magic-links/{magic_link_id}

Get a magic link

Returns one magic link from the authenticated workspace.

getMagicLink

Parameters

magic_link_id path required

The magic link identifier.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/MagicLink"
    }
  }
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/magic-links/{magic_link_id}

Update a magic link

Updates an existing magic link.

updateMagicLink

Parameters

magic_link_id path required

The magic link identifier.

Request Body

{
  "$ref": "#/components/schemas/MagicLinkUpsertRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/MagicLink"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

409 Request conflicts with an existing resource or current state

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/magic-links/{magic_link_id}

Delete a magic link

Deletes a magic link from the authenticated workspace.

deleteMagicLink

Parameters

magic_link_id path required

The magic link identifier.

Responses

204 Magic link was deleted

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

Broadcasts

Create, schedule, test, send, and inspect one-off broadcasts.

GET /v1/broadcasts

List broadcasts

Returns broadcast drafts, scheduled sends, active sends, and completed sends.

listBroadcasts

Parameters

limit query

Maximum number of items to return.

starting_after query

Opaque cursor returned by the previous page.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Broadcast"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 Unauthorized

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/broadcasts

Create a broadcast

Creates a broadcast draft or scheduled broadcast in the authenticated workspace.

createBroadcast

Parameters

Idempotency-Key header

Optional idempotency key for safe retries.

Request Body

{
  "$ref": "#/components/schemas/BroadcastUpsertRequest"
}

Responses

201 Broadcast created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Broadcast"
    }
  }
}

400 Invalid request

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/broadcasts/{broadcast_id}

Get a broadcast

Returns a broadcast draft, scheduled send, active send, or completed send.

getBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Broadcast"
    }
  }
}

404 Not found

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/broadcasts/{broadcast_id}

Update a broadcast

Updates a broadcast draft or scheduled send in place.

updateBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Request Body

{
  "$ref": "#/components/schemas/BroadcastUpsertRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Broadcast"
    }
  }
}

400 Invalid request

{
  "$ref": "#/components/schemas/Error"
}

404 Not found

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/broadcasts/{broadcast_id}

Delete a broadcast

Deletes a draft, scheduled, or failed broadcast from the authenticated workspace. Broadcasts cannot be deleted after they start sending.

deleteBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Responses

204 Broadcast deleted

404 Not found

{
  "$ref": "#/components/schemas/Error"
}

409 Broadcast cannot be deleted

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/broadcasts/{broadcast_id}/send

Send a broadcast now

Starts delivery now for a broadcast draft or a scheduled send.

sendBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Idempotency-Key header

Optional idempotency key to make retries safe.

Responses

200 Broadcast sent

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "status",
        "resource"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        },
        "resource": {
          "$ref": "#/components/schemas/Broadcast"
        }
      }
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

409 Request conflicts with the current resource state

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/broadcasts/{broadcast_id}/test

Send a broadcast test email

Sends a test message from an existing broadcast to one recipient.

testBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Idempotency-Key header

Optional idempotency key to make retries safe.

Request Body

{
  "$ref": "#/components/schemas/BroadcastTestRequest"
}

Responses

200 Test email sent

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/ActionResult"
    }
  }
}

400 Request is invalid

{
  "$ref": "#/components/schemas/Error"
}

404 Resource not found

{
  "$ref": "#/components/schemas/Error"
}

Segments

Read saved segments and preview dynamic segment definitions.

GET /v1/segments

List segments

Returns saved segments from the authenticated workspace.

listSegments

Parameters

limit query

The maximum number of segments to return.

starting_after query

The opaque cursor from the previous page of saved segments.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Segment"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 The request is not authorized.

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/segments

Create a segment

Creates a saved segment in the authenticated workspace.

createSegment

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely.

Request Body

{
  "$ref": "#/components/schemas/SegmentUpsertRequest"
}

Responses

201 Segment created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Segment"
    }
  }
}

400 The request is invalid.

{
  "$ref": "#/components/schemas/Error"
}

409 The request conflicts with the current segment state.

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/segments/{segment_id}

Get a segment

Returns one saved segment from the authenticated workspace.

getSegment

Parameters

segment_id path required

The identifier of the segment to return.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Segment"
    }
  }
}

404 The segment was not found.

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/segments/{segment_id}

Update a segment

Updates a saved segment in the authenticated workspace.

updateSegment

Parameters

segment_id path required

The identifier of the segment to update.

Request Body

{
  "$ref": "#/components/schemas/SegmentUpsertRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Segment"
    }
  }
}

400 The request is invalid.

{
  "$ref": "#/components/schemas/Error"
}

404 The segment was not found.

{
  "$ref": "#/components/schemas/Error"
}

409 The request conflicts with the current segment state.

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/segments/{segment_id}

Delete a segment

Deletes a saved segment from the authenticated workspace.

deleteSegment

Parameters

segment_id path required

The identifier of the segment to delete.

Responses

204 The segment was deleted.

404 The segment was not found.

{
  "$ref": "#/components/schemas/Error"
}

409 The request conflicts with the current segment state.

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/segments/preview

Preview a segment definition

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.

previewSegment

Request Body

{
  "$ref": "#/components/schemas/SegmentPreviewRequest"
}

Responses

200 The preview counts were returned.

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/SegmentPreview"
    }
  }
}

400 The request is invalid.

{
  "$ref": "#/components/schemas/Error"
}

Jobs

Create and inspect asynchronous subscriber import and export jobs.

POST /v1/jobs/subscriber-exports

Create a subscriber export job

Queues an asynchronous subscriber export for the authenticated workspace. Requires `jobs:write` and `subscribers:read` because the finished file contains subscriber data.

createSubscriberExportJob

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely.

Request Body

{
  "$ref": "#/components/schemas/SubscriberExportJobCreateRequest"
}

Responses

202 The export job was queued.

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/SubscriberExportJob"
    }
  }
}

400 The request is invalid.

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/jobs/subscriber-exports/{job_id}

Get a subscriber export job

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.

getSubscriberExportJob

Parameters

job_id path required

The identifier of the export job to return.

Responses

200 The export job was returned.

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/SubscriberExportJob"
    }
  }
}

404 The export job was not found.

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/jobs/subscriber-imports

Create a subscriber import job

Queues an asynchronous import job that creates or updates subscribers from CSV text.

createSubscriberImportJob

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely.

Request Body

{
  "$ref": "#/components/schemas/SubscriberImportJobCreateRequest"
}

Responses

202 The import job was queued.

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/SubscriberImportJob"
    }
  }
}

400 The request is invalid.

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/jobs/subscriber-imports/{job_id}

Get a subscriber import job

Returns the current state of a previously created import job.

getSubscriberImportJob

Parameters

job_id path required

The identifier of the import job to return.

Responses

200 The import job was returned.

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/SubscriberImportJob"
    }
  }
}

404 The import job was not found.

{
  "$ref": "#/components/schemas/Error"
}

Webhooks

Create and manage outbound webhook subscriptions for Mailrith events and signed event delivery.

GET /v1/webhook-subscriptions

List webhook subscriptions

Returns the outbound webhook subscriptions configured for the authenticated workspace.

listWebhookSubscriptions

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/WebhookSubscription"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 Unauthorized

{
  "$ref": "#/components/schemas/Error"
}

POST /v1/webhook-subscriptions

Create a webhook subscription

Creates a signed outbound webhook subscription and returns the signing secret once. The caller must also have read scopes for the selected event families.

createWebhookSubscription

Request Body

{
  "$ref": "#/components/schemas/WebhookSubscriptionCreateRequest"
}

Responses

201 Webhook subscription created

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/WebhookSubscriptionCreateResult"
    }
  }
}

400 Invalid request

{
  "$ref": "#/components/schemas/Error"
}

409 Conflict

{
  "$ref": "#/components/schemas/Error"
}

GET /v1/webhook-subscriptions/{webhook_subscription_id}

Get a webhook subscription

Returns one outbound webhook subscription configured for the authenticated workspace.

getWebhookSubscription

Parameters

webhook_subscription_id path required

The webhook subscription identifier.

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/WebhookSubscription"
    }
  }
}

404 Not found

{
  "$ref": "#/components/schemas/Error"
}

PUT /v1/webhook-subscriptions/{webhook_subscription_id}

Update a webhook subscription

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.

updateWebhookSubscription

Parameters

webhook_subscription_id path required

The webhook subscription identifier.

Request Body

{
  "$ref": "#/components/schemas/WebhookSubscriptionUpdateRequest"
}

Responses

200 Successful response

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/WebhookSubscription"
    }
  }
}

400 Invalid request

{
  "$ref": "#/components/schemas/Error"
}

404 Not found

{
  "$ref": "#/components/schemas/Error"
}

409 Conflict

{
  "$ref": "#/components/schemas/Error"
}

DELETE /v1/webhook-subscriptions/{webhook_subscription_id}

Delete a webhook subscription

Deletes an existing outbound webhook subscription from the authenticated workspace.

deleteWebhookSubscription

Parameters

webhook_subscription_id path required

The webhook subscription identifier.

Responses

200 Webhook subscription deleted

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "id",
        "deleted"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "deleted": {
          "type": "boolean",
          "enum": [
            true
          ]
        }
      }
    }
  }
}

404 Not found

{
  "$ref": "#/components/schemas/Error"
}

Need Help Shipping an Integration?

Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.

Contact Mailrith

Webhook Subscriptions API

API Reference

OpenAPI Contract

Platform

Get API metadata

Responses

Get authenticated API capabilities

Responses

Get the OpenAPI document

Responses

Workspace

Get the current workspace

Responses

Subscribers

List subscribers

Parameters

Responses

Create or upsert a subscriber

Request Body

Responses

Update a subscriber

Parameters

Request Body

Responses

Add a subscriber to a sequence

Parameters

Responses

Remove a subscriber from a sequence

Parameters

Responses

Remove a tag from a subscriber

Parameters

Responses

Tags

List tags

Parameters

Responses

Create a tag

Request Body

Responses

Custom Fields

List custom fields

Parameters

Responses

Create a custom field

Parameters

Request Body

Responses

Get a custom field

Parameters

Responses

Update a custom field

Parameters

Request Body

Responses

Delete a custom field

Parameters

Responses

Email Templates

List email templates

Parameters

Responses

Create an email template

Parameters

Request Body

Responses

Get an email template

Parameters

Responses

Update an email template

Parameters

Request Body

Responses

Delete an email template

Parameters

Responses

Forms

List forms

Parameters

Responses

Create a form