Quickstart

Create a Workspace API Key

1. In Mailrith, use the workspace switcher in the left sidebar to choose the workspace that the integration should access. The selected workspace controls which subscribers, tags, forms, landing pages, campaigns, and jobs the key can reach.
2. Click Settings in the left sidebar, then click the API Keys tab. For a user-facing walkthrough of this screen, see API Keys and Authorized Apps.
3. Click Generate API Key to open the Generate API Key drawer.
4. Choose Workspace, enter Name, choose Access Level, and choose Expiration.
5. Use a key name that identifies the system that owns the key, such as Website Signup Form, CRM Nightly Sync, or Data Warehouse Export.
6. Click Generate, then immediately copy the full secret from Save Your API Key. Mailrith will not show the full secret again.
7. Store the secret in a server-side secret manager or environment variable. Then record who owns the integration and where the key is stored.

• Open the app, switch to the target workspace, then go to Settings and open the API Keys tab.
• Choose the narrowest access level that the integration needs. Use read-only access for reporting. Use read-write access only when the integration must create or update Mailrith data.
• Name the key after the system that owns it, such as Website Signup Form or CRM Nightly Sync.
• Store the secret immediately. Mailrith will not show the full token again after creation.
• Record who owns the integration and where the key is stored so you can rotate the key later.

Send Your First Request

1. Set MAILRITH_API_KEY in the local environment where you will run the request.
2. Choose a test email address that is safe to create in the selected workspace.
3. Send the request to POST /v1/subscribers with the Bearer token and JSON body.
4. Read the API response and store the returned subscriber ID if your integration needs to refer to the subscriber later.
5. Open Subscribers in Mailrith and search for the test email. Confirm that the subscriber record exists and that the tags and activity history are correct.
6. Delete test subscribers, or label them clearly, before you move from local testing to production workflows.

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

{
  "data": {
    "id": "subscriber_123",
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "status": "Active",
    "country": null,
    "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"
  }
}