# Quickstart > Start with one workspace API key, one authenticated request, and the generated response envelope. This page covers the minimum steps needed to create a working subscriber sync. - Human page: https://mailrith.com/developers/quickstart - Markdown page: https://mailrith.com/developers/quickstart.md - Category: Getting Started - Reading time: 6 min read - Last updated: 2026-07-13 - Related keywords: Quickstart, Quickstart developer docs, Getting Started, Getting Started developer docs, Mailrith developer docs, Mailrith public API, Create a Workspace API Key, Send Your First Request, Inspect the Response Envelope, Authentication, Testing the API, API Reference ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## What this guide covers Create a workspace key and make your first authenticated request to Mailrith's public API. ## Create a Workspace API Key Start every server-to-server integration with a workspace API key. A workspace key is a private credential that tells Mailrith which workspace the request belongs to and which actions the request can perform. Create one key for each integration. Do not use one key for a whole company. For example, create separate keys for a website signup form, a CRM sync, an internal reporting job, and a one-time migration. Separate keys let you rotate or revoke access for one integration without breaking the others. Mailrith shows the full secret only once when you create the key. Copy the secret and store it in a secure secret manager or environment variable before you close the dialog. 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](https://mailrith.com/docs/api-keys-and-authorized-apps.md). 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 The fastest useful test is to create or update one subscriber. This test confirms that the API key works, the request uses the correct workspace, and the request body has the correct shape. Mailrith uses the standard `Authorization` header. Put the key after `Bearer`, send JSON with `Content-Type: application/json`, and call the versioned `/v1` endpoint. The subscriber endpoint is an upsert. If the email address is new, Mailrith creates the subscriber. If the email address already exists in the workspace, Mailrith updates the existing subscriber instead of creating a duplicate. 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](https://mailrith.com/docs/subscribers.md) 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. **Create or Upsert a Subscriber** ```bash 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` object. Read fields from this public response shape. Do not infer fields from Mailrith's internal database tables or app UI. List endpoints also include a `pagination` block. When `has_more` is true, store `next_cursor` and pass it as `starting_after` on the next request. For create and update calls, treat the API response as the source of truth for the record that Mailrith saved. This is especially useful when Mailrith normalizes an email address, attaches tags, or returns generated IDs. **Response** ```json { "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" } } ``` ## Related Guides - [Authentication](https://mailrith.com/developers/authentication.md): Every protected `v1` request is authorized through a workspace-scoped API key. This page covers the required header shape, workspace scoping behavior, and authentication failure handling. - [Testing the API](https://mailrith.com/developers/testing-the-api.md): You can test Mailrith's public API manually with local curl requests or automatically with the integration suite. This page shows the repo-native commands for both testing paths. - [API Reference](https://mailrith.com/developers/api-reference.md): 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.