Quickstart

Start with one workspace API key, one authenticated request, and the generated response envelope. This page covers the minimum needed to go from zero to a working subscriber sync.

4 min read

Create a workspace API key

Generate a workspace-scoped key from Mailrith Settings before you call any protected endpoint.

Keys are scoped to one workspace, so every authenticated request resolves cleanly to a single audience and set of resources.

Open the app, switch to the target workspace, and go to Settings -> API Keys.
Name each key after the integration that owns it so rotation and cleanup stay obvious later.
Store the secret immediately. Mailrith only shows the full token once.

Send your first request

Call the versioned API with Authorization: Bearer <credential>, using either a workspace API key or an OAuth access token issued to an approved client.

The public v1 surface now covers both audience sync and the core Mailrith control plane: broadcasts, templates, sequences, automations, magic links, forms, and async subscriber jobs.

Create or upsert a subscriber

curl -X POST https://api.mailrith.com/v1/subscribers \
  -H "Authorization: Bearer mrk_example_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "status": "Active",
    "new_tags": ["Website Signup"],
    "custom_fields": {
      "company": "Analytical Engines"
    }
  }'

Inspect the response envelope

Successful responses return a top-level data payload. List endpoints also include a pagination block with has_more and next_cursor.

The subscriber payload is already normalized for external consumers, so you can persist it without depending on Mailrith's internal table shape.

Response

{
  "data": {
    "id": "subscriber_123",
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "status": "Active",
    "subscribed_at": "2026-04-11T12:00:00.000Z",
    "last_opened_at": null,
    "tags": [
      { "id": "tag_website_signup", "name": "Website Signup" }
    ],
    "sequence_ids": [],
    "custom_fields": {
      "company": "Analytical Engines"
    },
    "created_at": "2026-04-11T12:00:00.000Z",
    "updated_at": "2026-04-11T12:00:00.000Z"
  }
}

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

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.

6 min read

API Reference

Browse the generated endpoint reference and download the OpenAPI contract.

Authentication