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.

7 min read

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.

Start the full stack with pnpm dev when you need to create data or keys through the Mailrith UI.
Use pnpm test:e2e:serve:api when you only need the API worker.
Open the local app, create or select a workspace, and create a local workspace API key.
Send one unauthenticated request to confirm that the API worker is reachable.
Send one authenticated request to confirm that the key works, the workspace scope is correct, and the request body is valid.
Connect the external system or larger sync job only after those checks pass.

Full Stack

pnpm dev

API Worker Only

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.

Open http://localhost:5173 while the local app is running.
Switch to the local workspace that the API request should use.
Click Settings, open the API Keys tab, and click Generate API Key.
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.
Copy the full secret once and store it in your local shell environment.
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.

Call GET /v1 first. If the request fails, fix the worker URL before you debug authentication.
Call GET /v1/openapi.json next. If the request succeeds, your tool can read the current contract.
Call GET /v1/capabilities with the workspace key. If the request fails with 401, fix the key.
Send one POST /v1/subscribers request with a test email.
If the request succeeds, open the app and confirm that the test subscriber exists.
If the request fails, inspect the error code and follow Errors instead of retrying without changes.

Unauthenticated Checks

curl http://localhost:8787/v1
curl http://localhost:8787/v1/openapi.json

Protected Request

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

pnpm exec vitest run --config vitest.integration.config.ts tests/integration/public-api-v1.test.ts tests/integration/workspace-api-keys.test.ts

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

Authentication

Agents