# Testing the API > 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. - Human page: https://mailrith.com/developers/testing-the-api - Markdown page: https://mailrith.com/developers/testing-the-api.md - Category: Getting Started - Reading time: 7 min read - Last updated: 2026-07-13 - Related keywords: Testing the API, Testing the API developer docs, Getting Started, Getting Started developer docs, Mailrith developer docs, Mailrith public API, Run the Services Locally, Generate a Workspace API Key, Exercise the Endpoints, Run the Automated Coverage, Quickstart, Authentication, 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 Run the local worker, generate a workspace key, call the endpoints, and run automated integration coverage. ## Run the Services Locally Use the full local stack when you need the app UI, local data, and API worker together. This is the best option when you want to create a workspace key in the UI and then immediately test API requests against the same workspace. Use the API worker command when you only need the public API and already have the local data or fixtures required for your test. Local testing is useful before you connect a real external system. It lets you confirm the request shape, authentication behavior, pagination, and error handling without touching production data. 1. Start the full stack with `pnpm dev` when you need to create data or keys through the Mailrith UI. 2. Use `pnpm test:e2e:serve:api` when you only need the API worker. 3. Open the local app, create or select a workspace, and create a local workspace API key. 4. Send one unauthenticated request to confirm that the API worker is reachable. 5. Send one authenticated request to confirm that the key works, the workspace scope is correct, and the request body is valid. 6. Connect the external system or larger sync job only after those checks pass. **Full Stack** ```bash pnpm dev ``` **API Worker Only** ```bash pnpm test:e2e:serve:api ``` ## Generate a Workspace API Key When the app is running locally, open `http://localhost:5173`, use the workspace switcher to choose the target workspace, click `Settings`, open the `API Keys` tab, and generate a key. The local API worker listens on `http://localhost:8787`, so you can use the token immediately against the versioned `/v1` endpoints. Use a clearly fake or local-only key name, such as `Local API Smoke Test`, so you can identify and remove the key later. Do not paste production API keys into local test scripts unless you are intentionally testing production behavior. 1. Open `http://localhost:5173` while the local app is running. 2. Switch to the local workspace that the API request should use. 3. Click `Settings`, open the `API Keys` tab, and click `Generate API Key`. 4. In the `Generate API Key` drawer, choose the workspace, name the key `Local API Smoke Test` or another clearly local name, choose the access level, choose the expiration, and click `Generate`. 5. Copy the full secret once and store it in your local shell environment. 6. Use that key only against `http://localhost:8787/v1` unless you intentionally created the key in production. ## Exercise the Endpoints Start by calling unauthenticated metadata endpoints. If those endpoints respond, the worker is reachable. Then send a protected request with the workspace key. This order helps you separate connection problems from authentication problems or request-body problems. For protected requests, test one simple create or list call before you build a larger sync. One subscriber upsert is enough to confirm that the key, workspace scope, JSON body, and response parsing path work. When a local request fails, save the full response body. Mailrith's error envelope includes a stable code that identifies authentication, validation, missing resource, conflict, or another expected API condition. 1. Call `GET /v1` first. If the request fails, fix the worker URL before you debug authentication. 2. Call `GET /v1/openapi.json` next. If the request succeeds, your tool can read the current contract. 3. Call `GET /v1/capabilities` with the workspace key. If the request fails with `401`, fix the key. 4. Send one `POST /v1/subscribers` request with a test email. 5. If the request succeeds, open the app and confirm that the test subscriber exists. 6. If the request fails, inspect the error code and follow [Errors](https://mailrith.com/developers/errors.md) instead of retrying without changes. **Unauthenticated Checks** ```bash curl http://localhost:8787/v1 curl http://localhost:8787/v1/openapi.json ``` **Protected Request** ```bash curl -X POST http://localhost:8787/v1/subscribers \ -H "Authorization: Bearer mrk_example_secret_key" \ -H "Content-Type: application/json" \ -d '{ "email": "ada@example.com", "name": "Ada Lovelace", "new_tags": ["Website Signup"] }' ``` ## Run the Automated Coverage Use automated coverage when you change the public contract, API worker behavior, authentication rules, request validation, SDK generation, or docs that depend on the contract. The integration tests start the worker with a test database and verify authentication, list flows, create and update flows, webhook subscriptions, and async import and export jobs. If tests fail after a docs-only change, check whether the docs imported the wrong value or whether the generated OpenAPI contract changed unexpectedly. - `tests/integration/public-api-v1.test.ts` covers the versioned public endpoints. - `tests/integration/workspace-api-keys.test.ts` covers key creation and verification. **Integration Tests** ```bash pnpm exec vitest run --config vitest.integration.config.ts tests/integration/public-api-v1.test.ts tests/integration/workspace-api-keys.test.ts ``` ## Related Guides - [Quickstart](https://mailrith.com/developers/quickstart.md): 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. - [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. - [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.