API Reference

The full API reference is generated from the same source-of-truth contract used by the worker. Use it for exact parameters, schemas, and operation ids.

6 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 the 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 surface.

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 audience records in a workspace.

GET /v1/subscribers

List subscribers

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

listSubscribers

Parameters

search query

Filter by name, email, or status.

status query

Filter by subscriber status.

cold_only query

When `true`, limit results to cold subscribers.

limit query

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

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

401 Unauthorized

{
  "$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 existing subscriber is updated instead.

upsertSubscriber

Request Body

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

Responses

200 Existing subscriber updated

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

201 Subscriber created

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

400 Invalid request

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

401 Unauthorized

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

Custom Fields

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

GET /v1/custom-fields

List custom fields

Returns custom fields available to the authenticated workspace.

listCustomFields

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

401 Unauthorized

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

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

Forms

Read and manage embeddable form definitions and presentation settings.

GET /v1/forms

List forms

Returns forms in the authenticated workspace.

listForms

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

401 Unauthorized

{
  "$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 for safe retries.

Request Body

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

Responses

201 Form created

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

400 Invalid request

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

GET /v1/forms/{form_id}

Get a form

Returns a form in the authenticated workspace.

getForm

Parameters

form_id path required

The form identifier.

Responses

200 Successful response

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

404 Not found

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

PUT /v1/forms/{form_id}

Update a form

Updates an existing form in place.

updateForm

Parameters

form_id path required

The form identifier.

Request Body

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

Responses

200 Successful response

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

400 Invalid request

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

404 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 form identifier.

Responses

204 Form deleted

404 Not found

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

Sequences

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

GET /v1/sequences

List sequences

Returns sequences available in the authenticated workspace.

listSequences

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

401 Unauthorized

{
  "$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 for safe retries.

Request Body

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

Responses

201 Sequence created

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

400 Invalid request

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

GET /v1/sequences/{sequence_id}

Get a sequence

Returns a sequence in 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 Not found

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

PUT /v1/sequences/{sequence_id}

Update a sequence

Updates an existing sequence in place.

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 Invalid request

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

404 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 deleted

404 Not found

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

Automations

Create and manage automation definitions and lifecycle state.

GET /v1/automations

List automations

Returns automations available in the authenticated workspace.

listAutomations

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

401 Unauthorized

{
  "$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 for safe retries.

Request Body

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

Responses

201 Automation created

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

400 Invalid request

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

GET /v1/automations/{automation_id}

Get an automation

Returns an automation in 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 Not found

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

PUT /v1/automations/{automation_id}

Update an automation

Updates an existing automation in place.

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 Invalid request

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

404 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 deleted

404 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 available in the authenticated workspace.

listMagicLinks

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

401 Unauthorized

{
  "$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 for safe retries.

Request Body

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

Responses

201 Magic link created

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

400 Invalid request

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

409 Conflict

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

GET /v1/magic-links/{magic_link_id}

Get a magic link

Returns a magic link in 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 Not found

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

PUT /v1/magic-links/{magic_link_id}

Update a magic link

Updates an existing magic link in place.

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 Invalid request

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

404 Not found

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

409 Conflict

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

404 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 an existing broadcast from the authenticated workspace.

deleteBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Responses

204 Broadcast deleted

404 Not found

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

POST /v1/broadcasts/{broadcast_id}/send

Send a broadcast now

Launches immediate delivery for a broadcast draft or scheduled send.

sendBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Idempotency-Key header

Optional idempotency key for safe retries.

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 Invalid request

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

404 Not found

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

409 Conflict

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

POST /v1/broadcasts/{broadcast_id}/test

Send a broadcast test email

Sends a test message for an existing broadcast to a single recipient.

testBroadcast

Parameters

broadcast_id path required

The broadcast identifier.

Idempotency-Key header

Optional idempotency key for safe retries.

Request Body

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

Responses

200 Test email sent

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

400 Invalid request

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

404 Not found

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

Segments

Read saved segments and preview dynamic audience definitions.

GET /v1/segments

List segments

Returns saved segments in the authenticated workspace.

listSegments

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

401 Unauthorized

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

POST /v1/segments/preview

Preview a segment definition

Returns subscriber counts for an unsaved audience definition.

previewSegment

Request Body

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

Responses

200 Preview counts

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

400 Invalid request

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

createSubscriberExportJob

Parameters

Idempotency-Key header

Optional idempotency key for safe retries.

Request Body

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

Responses

202 Export job queued

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

400 Invalid request

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

getSubscriberExportJob

Parameters

job_id path required

The export job identifier.

Responses

200 Export job

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

404 Not found

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

POST /v1/jobs/subscriber-imports

Create a subscriber import job

Queues an asynchronous subscriber import from CSV text.

createSubscriberImportJob

Parameters

Idempotency-Key header

Optional idempotency key for safe retries.

Request Body

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

Responses

202 Import job queued

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

400 Invalid request

{
  "$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 import job identifier.

Responses

200 Import job

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

404 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.

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 a single 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.

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

Related guides

4 min read

Quickstart

Create a workspace key and make the first authenticated request against Mailrith's public API.

3 min read

Authentication

Use workspace-scoped Bearer keys and understand how protected requests are authorized.

5 min read

Testing the API

Run the local worker, generate a workspace key, exercise the endpoints, and execute automated integration coverage.

Import and Export Jobs

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

Tags

List tags

Parameters

Responses

Create a tag

Request Body

Responses

Custom Fields

List custom fields

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

Parameters

Request Body

Responses

Get a form

Parameters

Responses

Update a form

Parameters

Request Body

Responses

Delete a form

Parameters

Responses

Sequences

List sequences

Parameters

Responses

Create a sequence

Parameters

Request Body

Responses

Get a sequence

Parameters

Responses

Update a sequence

Parameters

Request Body