Testing the API

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.

5 min read

Run the services locally

Use the full dev stack when you want the app UI available to generate keys and inspect data. If you only need the worker, run the API server directly.

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, switch to the target workspace, and create a key from Settings -> API Keys.

The local API worker listens on http://localhost:8787, so that token can be used immediately against the versioned v1 surface.

Exercise the endpoints

Start with the unauthenticated metadata endpoints, then send a protected request with the workspace key you generated locally.

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

The public v1 contract is covered by integration tests that boot the worker against a real test database and verify authentication, list flows, create flows, and async jobs.

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

Related guides

4 min read

Quickstart

Create a workspace key and make the first authenticated request against Mailrith's public API.

3 min read

Authentication

Use workspace-scoped Bearer keys and understand how protected requests are authorized.

6 min read

API Reference

Browse the generated endpoint reference and download the OpenAPI contract.

Authentication

Agents