# 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. - Human page: https://mailrith.com/developers/quickstart - Category: Getting Started - Reading time: 6 min read ## What this guide covers Create a workspace key and make the first authenticated request against 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 what that request is allowed to do. Create one key for one integration, not 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 make it easy to rotate or revoke one integration without breaking everything else. The full secret is shown only once when the key is created. Store it in a secure secret manager or environment variable before closing the dialog. 1. In Mailrith, use the workspace switcher in the left sidebar to choose the workspace you want the integration to access. The workspace you choose decides 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. In `Integration Credentials`, click `Generate API Key` to open the `Generate API Key` drawer. 4. Choose `Workspace`, enter `Name`, choose `Access Level`, and choose `Expiration`. 5. Give the key a name that identifies the owning system, such as `Website Signup Form`, `CRM Nightly Sync`, or `Data Warehouse Export`. 6. Click `Generate`, then copy the full secret from `Save Your API Key` immediately. 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 the `API Keys` tab. - Choose the narrowest access level that works for the integration. Use read-only access for reporting and 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 future rotation is straightforward. ## Send Your First Request The fastest useful test is to create or update one subscriber. This confirms that the API key works, the workspace is correct, and the request body is shaped properly. 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 is new, Mailrith creates the subscriber. If the email 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. Pick 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 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 to confirm the record, tags, and activity history look correct. 6. Delete or clearly label test subscribers before moving 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 from this public response shape rather than trying to infer anything 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 response as the source of truth for the record 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", "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 resolves through a workspace-scoped API key. This page covers the header shape, workspace scoping behavior, and authentication failure handling. - [Testing the API](https://mailrith.com/developers/testing-the-api.md): Mailrith's public API can be tested manually with local curl requests and automatically through the integration suite. This page shows the repo-native commands for both 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 it for exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.