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"
}

Analytics

Run bounded aggregate delivery and engagement reports.

POST /v1/analytics/reports

Create or reuse an analytics report

Runs from compact rollups. Ranges through 31 days complete inline; longer ranges are queued. Results expire after 24 hours and never exceed 100 rows.

createAnalyticsReport

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

Request Body

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

Responses

200 Successful response

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

202 The bounded report was queued.

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

GET /v1/analytics/reports/{report_id}

Get an analytics report

Returns one unexpired bounded analytics report by identifier.

getAnalyticsReport

Parameters

report_id path required

Stable analytics report identifier.

limit query

Maximum aggregate row count, from 1 to 50.

starting_after query

Opaque next_cursor returned by the previous report page.

Responses

200 Successful response

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

Diagnostics

Inspect bounded workflow and delivery diagnostics.

GET /v1/diagnostics/automations/{automation_id}/runs

List Automation run diagnostics

Returns at most 50 recent runs with redacted errors and bounded step execution details.

listAutomationRunDiagnostics

Parameters

automation_id path required

Automation identifier.

limit query

Maximum run count, from 1 to 50.

Responses

200 Successful response

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

GET /v1/diagnostics/automations/{automation_id}/runs/{run_id}

Get Automation run diagnostics

Returns one Automation run with status, timing, retries, outcomes, and redacted step failures.

getAutomationRunDiagnostics

Parameters

automation_id path required

Automation identifier.

run_id path required

Automation run identifier.

Responses

200 Successful response

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

GET /v1/diagnostics/broadcasts/{broadcast_id}

Get Broadcast diagnostics

Returns selection totals, provider readiness, and the 20 most common structured delivery reasons.

getBroadcastDiagnostics

Parameters

broadcast_id path required

Broadcast identifier.

Responses

200 Successful response

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

GET /v1/diagnostics/sequences/{sequence_id}

Get Sequence diagnostics

Returns bounded Sequence failure, retry, status, and message outcome details.

getSequenceDiagnostics

Parameters

sequence_id path required

Sequence identifier.

limit query

Maximum failure count, from 1 to 50.

Responses

200 Successful response

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

GET /v1/diagnostics/subscribers/{subscriber_id}

Get privacy-conscious Subscriber diagnostics

Returns a 90-day, bounded activity view without exposing the Subscriber email address.

getSubscriberActivityDiagnostics

Parameters

subscriber_id path required

Subscriber identifier.

Responses

200 Successful response

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

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

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

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"
}

GET /v1/subscribers/{subscriber_id}

Get a subscriber

Returns one Subscriber by its stable identifier from the authenticated workspace.

getSubscriber

Parameters

subscriber_id path required

The Subscriber identifier.

Responses

200 Successful response

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

401 Authentication is required or invalid

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

404 Subscriber not found

{
  "$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"
}

DELETE /v1/subscribers/{subscriber_id}

Delete a subscriber

Permanently removes one Subscriber and their Mailrith activity history from the authenticated workspace.

deleteSubscriber

Parameters

subscriber_id path required

The Subscriber identifier.

Responses

204 Subscriber was deleted

401 Authentication is required or invalid

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

404 Resource not found

{
  "$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"
}

PUT /v1/subscribers/{subscriber_id}/status

Change Subscriber sending eligibility

Changes the delivery status for one Subscriber without changing profile, targeting, or Sequence enrollment fields. Making a Subscriber Active requires consent_evidence; its collected_at value must include the correct UTC offset and must not be later than Mailrith's server time.

updateSubscriberStatus

Parameters

subscriber_id path required

The Subscriber identifier.

Request Body

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

Responses

200 Successful response

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

400 Request is invalid

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

404 Subscriber not found

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

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

Add a Tag to a Subscriber

Adds the selected Tag to a Subscriber. If the Subscriber already has the Tag, the API returns the Subscriber unchanged.

addSubscriberTag

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"
}

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 a bounded page of custom fields in the authenticated workspace, including each field's exact ready-to-use email personalization token.

listCustomFields

Parameters

search query

Filter custom fields by label or type.

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 retry the request safely. It must not exceed 256 UTF-8 bytes.

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, including its exact ready-to-use email personalization token.

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/CustomFieldUpdateRequest"
}

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"
}

Sender Identities

Read enabled sender names and email addresses without exposing provider credentials.

GET /v1/sender-identities

List sender identities

Returns a bounded page of enabled sender names, addresses, and provider types that can be selected for Broadcasts and Sequences. Provider credentials and configuration are never returned.

listSenderIdentities

Parameters

limit query

Maximum number of sender identities to return.

starting_after query

Opaque next_cursor returned by the previous sender identity page.

Responses

200 Successful response

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

401 Unauthorized

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

GET /v1/sender-identities/{sender_identity_id}

Get a sender identity

Returns one enabled sender name, address, and provider type by stable identifier. Provider credentials and configuration are never returned.

getSenderIdentity

Parameters

sender_identity_id path required

The sender identity identifier.

Responses

200 Successful response

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

401 Unauthorized

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

404 Sender identity not found

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

Email Delivery Connections

Create and manage the selected workspace's email delivery service connection without returning saved credentials.

POST /v1/email-delivery-connection-setup-sessions

Start secure email delivery connection setup

Creates a short-lived browser handoff containing only non-secret defaults. Open setup_url so an authorized Mailrith user can enter provider credentials directly in Mailrith.

startEmailDeliveryConnectionSetup

Request Body

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

Responses

201 Secure setup session created

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

400 The non-secret setup defaults are invalid.

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

GET /v1/email-delivery-connection-setup-sessions/{setup_session_id}

Get secure setup status

Returns pending or completed status for one short-lived setup session. It never returns the browser token or provider credentials.

getEmailDeliveryConnectionSetup

Parameters

setup_session_id path required

The identifier returned when setup started.

Responses

200 Successful response

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

404 The setup session was not found or expired.

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

POST /v1/email-delivery-connection-setup-sessions/{setup_session_id}/renew

Renew secure email delivery setup

Creates a fresh short-lived browser link from the previous session's bounded non-secret defaults. Completed sessions cannot be renewed.

renewEmailDeliveryConnectionSetup

Parameters

setup_session_id path required

The previous setup session identifier.

Responses

201 A fresh secure setup session was created.

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

409 The setup session cannot be renewed.

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

GET /v1/email-delivery-connections

List email delivery connections

Returns a bounded page of email delivery connections linked to the authenticated workspace. Saved credentials and webhook secrets are never returned.

listEmailDeliveryConnections

Parameters

limit query

Maximum number of connections to return.

starting_after query

Opaque next_cursor returned by the previous connection page.

Responses

200 Successful response

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

401 Unauthorized

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

GET /v1/email-delivery-connections/{connection_id}

Get an email delivery connection

Returns one secret-free email delivery connection linked to the authenticated workspace.

getEmailDeliveryConnection

Parameters

connection_id path required

The identifier of the connection to return.

Responses

200 Successful response

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

404 The connection was not found.

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

PATCH /v1/email-delivery-connections/{connection_id}

Update an email delivery connection

Changes non-secret details for one connection linked only to the authenticated workspace. Use a secure setup session to replace provider credentials. Shared connections must be changed in the Mailrith UI.

updateEmailDeliveryConnection

Parameters

connection_id path required

The identifier of the connection to update.

Request Body

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

Responses

200 Successful response

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

400 The non-secret connection details are invalid.

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

409 The connection is shared or currently in use and cannot be changed through a workspace-scoped credential.

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

DELETE /v1/email-delivery-connections/{connection_id}

Delete an email delivery connection

Deletes one connection linked only to the authenticated workspace. Shared or in-use connections are not deleted.

deleteEmailDeliveryConnection

Parameters

connection_id path required

The identifier of the connection to delete.

Responses

204 The connection was deleted.

404 The connection was not found.

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

409 The connection is shared or currently in use and cannot be deleted.

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

PUT /v1/email-delivery-connections/{connection_id}/status

Enable or disable an email delivery connection

Enables or disables one connection linked only to the authenticated workspace. Shared or in-use connections remain protected.

updateEmailDeliveryConnectionStatus

Parameters

connection_id path required

The identifier of the connection to change.

Request Body

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

Responses

200 Successful response

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

409 The connection is shared or currently in use and cannot be changed.

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

POST /v1/email-delivery-connections/{connection_id}/test

Send an email delivery connection test

Sends one real test email through the saved connection. This is the definitive check when a send-only provider key cannot be inspected.

testEmailDeliveryConnection

Parameters

connection_id path required

The identifier of the connection to test.

Idempotency-Key header required

Required idempotency key that prevents an automatic retry from repeating the action. It must not exceed 256 UTF-8 bytes.

Request Body

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

Responses

200 Test email sent.

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "connection_id",
        "recipient",
        "status",
        "sent_at"
      ],
      "properties": {
        "connection_id": {
          "type": "string"
        },
        "recipient": {
          "type": "string",
          "format": "email"
        },
        "status": {
          "type": "string",
          "enum": [
            "sent"
          ]
        },
        "sent_at": {
          "type": "string",
          "format": "date-time"
        },
        "provider_message_ids": {
          "type": "array",
          "minItems": 1,
          "maxItems": 5,
          "items": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "description": "Provider acceptance IDs in sent-message order; null when unavailable. These are not delivery or inbox receipts."
        }
      }
    }
  }
}

400 The recipient is invalid or the test send failed.

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

429 Too many test emails were requested.

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

POST /v1/email-delivery-connections/{connection_id}/verify

Verify an email delivery connection

Checks the saved provider credential and sender without returning secrets. If the provider key allows sending but not inspection, the response clearly requires a real test email.

verifyEmailDeliveryConnection

Parameters

connection_id path required

The identifier of the connection to verify.

Responses

200 Verification completed.

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "connection_id",
        "verification_status",
        "inspection_status",
        "message",
        "verified_at"
      ],
      "properties": {
        "connection_id": {
          "type": "string"
        },
        "verification_status": {
          "type": "string",
          "enum": [
            "verified",
            "send_test_required"
          ]
        },
        "inspection_status": {
          "type": "string",
          "enum": [
            "available",
            "unavailable"
          ]
        },
        "message": {
          "type": "string"
        },
        "verified_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}

400 The provider or sender verification failed.

{
  "$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

search query

Filter email templates by name.

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/EmailTemplateSummary"
      }
    },
    "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 to retry the request safely. It must not exceed 256 UTF-8 bytes.

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/EmailTemplateUpdateRequest"
}

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"
}

POST /v1/email-templates/{template_id}/preview

Preview an email template for a Subscriber

Renders one template using a saved Subscriber's name, email, and custom fields without sending or saving anything.

previewEmailTemplate

Parameters

template_id path required

The email template identifier.

Request Body

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

Responses

200 Successful response

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

400 Request is invalid

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

404 Template or Subscriber not found

{
  "$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 name or public URL token. Retrieve a known Form ID through the item endpoint.

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/FormSummary"
      }
    },
    "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. It must not exceed 256 UTF-8 bytes.

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/FormUpdateRequest"
}

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"
}

POST /v1/forms/{form_id}/double-opt-in-preview

Preview a form confirmation email for a Subscriber

Renders the configured double opt-in email for a saved Subscriber without sending or saving anything.

previewFormDoubleOptIn

Parameters

form_id path required

The form identifier.

Request Body

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

Responses

200 Successful response

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

404 Form or Subscriber not found

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

409 Double opt-in is disabled or incomplete

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

GET /v1/forms/{form_id}/submissions

List form submissions

Returns a bounded cursor page of retained submissions for one Form, including the Subscriber who submitted it.

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"
}

GET /v1/forms/{form_id}/submissions/{submission_id}

Get a form submission

Returns one retained Form submission by stable identifier.

getFormSubmission

Parameters

form_id path required

The Form identifier.

submission_id path required

The Form submission identifier.

Responses

200 Successful response

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

404 The Form or submission 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 name, slug, custom path, or public URL token. Retrieve a known Landing Page ID through the item endpoint.

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/LandingPageSummary"
      }
    },
    "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. It must not exceed 256 UTF-8 bytes.

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/LandingPageUpdateRequest"
}

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"
}

POST /v1/landing-pages/{landing_page_id}/double-opt-in-preview

Preview a landing page confirmation email for a Subscriber

Renders the configured double opt-in email for a saved Subscriber without sending or saving anything.

previewLandingPageDoubleOptIn

Parameters

landing_page_id path required

The landing page identifier.

Request Body

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

Responses

200 Successful response

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

404 Landing page or Subscriber not found

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

409 Double opt-in is disabled or incomplete

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

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

List landing page submissions

Returns a bounded cursor page of retained submissions for one Landing Page, including the Subscriber who submitted it.

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"
}

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

Get a landing page submission

Returns one retained Landing Page submission by stable identifier.

getLandingPageSubmission

Parameters

landing_page_id path required

The Landing Page identifier.

submission_id path required

The Landing Page submission identifier.

Responses

200 Successful response

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

404 The Landing Page or submission 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 name, status, or sender details. Retrieve a known Sequence ID through the item endpoint.

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/SequenceSummary"
      }
    },
    "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 retry the request safely. It must not exceed 256 UTF-8 bytes.

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 paused Sequence. Before changing a running Sequence, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Sequence, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate a Sequence that was not already running.

updateSequence

Parameters

sequence_id path required

The sequence identifier.

Request Body

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

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"
}

409 A running Sequence must be paused before it can be updated. Before changing a running Sequence, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Sequence, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate a Sequence that was not already running.

{
  "$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"
}

GET /v1/sequences/{sequence_id}/journey-preview

Preview a sequence journey

Returns the bounded saved email timeline and shows which messages a selected Subscriber is eligible to receive, without enrolling the Subscriber or sending email.

previewSequenceJourney

Parameters

sequence_id path required

The Sequence identifier.

subscriber_id query required

The saved Subscriber whose personalization and targeting should be previewed.

Responses

200 Sequence journey preview returned

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

404 Sequence not found

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

GET /v1/sequences/{sequence_id}/preflight

Check sequence readiness

Checks the saved Sequence, its published emails, and its email delivery connection without changing data or sending email.

preflightSequence

Parameters

sequence_id path required

The Sequence identifier.

Responses

200 Sequence readiness returned

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

404 Sequence not found

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

PUT /v1/sequences/{sequence_id}/status

Activate or pause a sequence

Starts or pauses one Sequence without changing its content or delivery settings.

updateSequenceStatus

Parameters

sequence_id path required

The Sequence identifier.

Request Body

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

Responses

200 Successful response

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

400 Request is invalid

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

404 Sequence not found

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

POST /v1/sequences/{sequence_id}/test

Send sequence test messages

Sends up to five selected saved Sequence emails to one explicit test address. This does not enroll a Subscriber, start the Sequence, or write delivery activity.

testSequence

Parameters

sequence_id path required

The Sequence identifier.

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

Request Body

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

Responses

200 Sequence test messages sent

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

400 Request is invalid

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

404 Sequence not found

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

429 Too many test messages were requested

{
  "$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

search query

Filter Automations by name or status.

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/AutomationSummary"
      }
    },
    "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 retry the request safely. It must not exceed 256 UTF-8 bytes.

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 draft or paused Automation. Before changing a running Automation, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Automation, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate an Automation that was not already running.

updateAutomation

Parameters

automation_id path required

The automation identifier.

Request Body

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

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"
}

409 A running Automation must be paused before it can be updated. Before changing a running Automation, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Automation, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate an Automation that was not already running.

{
  "$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"
}

GET /v1/automations/{automation_id}/journey-preview

Preview an automation journey

Shows the bounded path a selected Subscriber would take through the current saved conditions without running actions or writing history.

previewAutomationJourney

Parameters

automation_id path required

The Automation identifier.

subscriber_id query required

The saved Subscriber whose current state should be evaluated.

Responses

200 Automation journey preview returned

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

404 Automation not found

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

GET /v1/automations/{automation_id}/preflight

Check automation readiness

Checks the saved Automation definition and email delivery prerequisite without running any action.

preflightAutomation

Parameters

automation_id path required

The Automation identifier.

Responses

200 Automation readiness returned

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

404 Automation not found

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

PUT /v1/automations/{automation_id}/status

Change an automation status

Starts, pauses, or returns one Automation to draft without changing its definition.

updateAutomationStatus

Parameters

automation_id path required

The Automation identifier.

Request Body

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

Responses

200 Successful response

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

400 Request is invalid

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

404 Automation not found

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

POST /v1/automations/{automation_id}/test

Send automation test messages

Sends up to five selected saved Automation email steps to one explicit test address. This does not start the Automation or run other actions.

testAutomation

Parameters

automation_id path required

The Automation identifier.

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

Request Body

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

Responses

200 Automation test messages sent

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

400 Request is invalid

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

404 Automation not found

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

429 Too many test messages were requested

{
  "$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

search query

Filter Magic Links by name, destination, or success message.

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/MagicLinkSummary"
      }
    },
    "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 retry the request safely. It must not exceed 256 UTF-8 bytes.

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/MagicLinkUpdateRequest"
}

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

search query

Filter Broadcasts by subject, preview text, status, or sender.

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/BroadcastSummary"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

401 Unauthorized

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

POST /v1/broadcasts

Create a broadcast

Creates a broadcast draft in the authenticated workspace.

createBroadcast

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

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 an existing Broadcast draft. Scheduled, running, completed, and failed Broadcasts cannot be changed here. Before changing a scheduled Broadcast, read it by ID and retain its scheduled_at in the current task only. If the saved time is no longer safely in the future, ask the user for a new time before unscheduling. Otherwise unschedule it, apply the update, reschedule it for the same time, and verify both status and scheduled_at. If the update fails after unscheduling, restore the unchanged Broadcast to the same future time when possible. If the schedule cannot be restored, leave it as a Draft and immediately report that it will not send; never choose a replacement time without the user.

updateBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Request Body

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

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"
}

409 The Broadcast must be a draft before it can be updated. Before changing a scheduled Broadcast, read it by ID and retain its scheduled_at in the current task only. If the saved time is no longer safely in the future, ask the user for a new time before unscheduling. Otherwise unschedule it, apply the update, reschedule it for the same time, and verify both status and scheduled_at. If the update fails after unscheduling, restore the unchanged Broadcast to the same future time when possible. If the schedule cannot be restored, leave it as a Draft and immediately report that it will not send; never choose a replacement time without the user.

{
  "$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}/cancel

Cancel a broadcast send

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.

cancelBroadcastSend

Parameters

broadcast_id path required

The broadcast identifier.

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

Responses

202 Broadcast cancellation accepted or already complete

{
  "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 Broadcast send not found

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

409 Broadcast send can no longer be canceled

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

GET /v1/broadcasts/{broadcast_id}/delivery-errors

List broadcast delivery errors

Returns a cursor-paginated page of permanent failures and unknown delivery results.

listBroadcastDeliveryErrors

Parameters

broadcast_id path required

The broadcast identifier.

cursor query

The last delivery ID returned by the previous page.

limit query

The number of errors to return, from 1 to 100.

Responses

200 Delivery error page

{
  "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 Resource not found

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

GET /v1/broadcasts/{broadcast_id}/preflight

Inspect broadcast readiness

Optionally checks the current Subscriber estimate, provider capacity, sender setup, event tracking, and blocking issues. This diagnostic is not required before starting a durable send.

preflightBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Responses

200 Broadcast preflight

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

404 Resource not found

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

GET /v1/broadcasts/{broadcast_id}/progress

Get broadcast send progress

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.

getBroadcastSendProgress

Parameters

broadcast_id path required

The broadcast identifier.

Responses

200 Broadcast send progress

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

404 Resource not found

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

PUT /v1/broadcasts/{broadcast_id}/schedule

Schedule or reschedule a broadcast

Schedules a draft for future delivery, or changes the delivery time of an existing scheduled Broadcast. This uses Mailrith's durable scheduled-send path and does not start delivery immediately.

scheduleBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Request Body

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

Responses

200 Broadcast scheduled

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

400 The schedule or sender is invalid.

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

409 The Broadcast already started or cannot be scheduled in its current state.

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

DELETE /v1/broadcasts/{broadcast_id}/schedule

Unschedule a broadcast

Returns a scheduled Broadcast to draft state before delivery starts.

unscheduleBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Responses

200 Broadcast returned to draft

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

409 The Broadcast already started or cannot be changed in its current state.

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

POST /v1/broadcasts/{broadcast_id}/send

Send a broadcast now

Immediately creates durable preparation for a broadcast draft or scheduled send. Mailrith calculates the exact Subscriber total and checks provider readiness in the background before delivery. 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.

sendBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

Request Body

{
  "type": "object",
  "properties": {
    "preflight_proof": {
      "type": "string",
      "description": "Optional unchanged short-lived send_proof returned by a recent diagnostic preflight. A valid proof can seed its checked estimate. If it is omitted, expired, or no longer matches, Mailrith still creates the run immediately and calculates the exact total during durable preparation."
    }
  }
}

Responses

202 Broadcast send started or is waiting for an earlier active Broadcast to finish

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "status",
        "run_id",
        "resource"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "running",
            "queued"
          ],
          "description": "Queued means Mailrith accepted the send and will start it automatically when a sending slot is available."
        },
        "run_id": {
          "type": "string"
        },
        "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 that has an email delivery connection. Provide a saved Subscriber ID for personalization; use subscribers_list to find one when needed. The recipient may be any test inbox and does not have to match the saved Subscriber.

testBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

Request Body

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

Responses

200 Test email sent

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

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

search query

Filter Segments by name or description.

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/SegmentSummary"
      }
    },
    "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. It must not exceed 256 UTF-8 bytes.

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/SegmentUpdateRequest"
}

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.

GET /v1/jobs/subscriber-exports

List subscriber export jobs

Returns a bounded cursor page of recent Subscriber export job summaries without loading selection payloads or generating download URLs.

listSubscriberExportJobs

Parameters

limit query

Maximum number of jobs 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/SubscriberExportJobSummary"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

POST /v1/jobs/subscriber-exports

Create a subscriber export job

Queues an asynchronous Subscriber export for the authenticated workspace. Requires `subscribers:export` because the finished file contains bulk Subscriber data.

createSubscriberExportJob

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

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 `subscribers:export` 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-import-uploads

Start a subscriber import upload

Creates a short-lived browser handoff where a signed-in user can choose a CSV file. Starting the handoff does not import Subscribers.

startSubscriberImportUpload

Responses

201 Successful response

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

GET /v1/jobs/subscriber-import-uploads/{upload_id}

Get a subscriber import upload

Returns upload readiness, bounded column metadata, and the row count without returning CSV contents.

getSubscriberImportUpload

Parameters

upload_id path required

The short-lived upload identifier.

Responses

200 Successful response

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

404 The upload was not found or has expired.

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

GET /v1/jobs/subscriber-imports

List subscriber import jobs

Returns a bounded cursor page of recent Subscriber import job summaries without loading stored CSV data or mapping payloads.

listSubscriberImportJobs

Parameters

limit query

Maximum number of jobs 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/SubscriberImportJobSummary"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

POST /v1/jobs/subscriber-imports

Create a subscriber import job

Queues an asynchronous import job from a ready short-lived browser upload. CSV contents never pass through the agent request.

createSubscriberImportJob

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

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. A workspace can have up to 20 webhook subscriptions, including disabled subscriptions.

createWebhookSubscription

Parameters

Idempotency-Key header

Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

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 The subscription name already exists or the workspace has reached its 20-subscription limit.

{
  "$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

Analytics

Create or reuse an analytics report

Parameters

Request Body

Responses

Get an analytics report

Parameters

Responses

Diagnostics

List Automation run diagnostics

Parameters

Responses

Get Automation run diagnostics

Parameters

Responses

Get Broadcast diagnostics

Parameters

Responses

Get Sequence diagnostics

Parameters

Responses

Get privacy-conscious Subscriber diagnostics

Parameters

Responses

Subscribers

List subscribers

Parameters

Responses

Create or upsert a subscriber

Parameters

Request Body

Responses

Get a subscriber

Parameters

Responses

Update a subscriber

Parameters

Request Body

Responses

Delete a subscriber

Parameters

Responses

Add a subscriber to a sequence

Parameters

Responses

Remove a subscriber from a sequence

Parameters

Responses

Change Subscriber sending eligibility

Parameters

Request Body

Responses

Add a Tag to a Subscriber

Parameters

Responses

Remove a tag from a subscriber

Parameters

Responses

Tags

List tags

Parameters

Responses

Create a tag

Parameters

Request Body

Responses

Get a tag

Parameters