API Reference
MergeMail exposes a REST API for all core platform operations. The full API is documented in OpenAPI 3.1 format.
Authentication
All API endpoints (except /api/webhooks/paystack) require a Bearer token in the Authorization header.
Obtain a token by authenticating via Supabase (the token is the Supabase JWT).
Authorization: Bearer <your-supabase-jwt>In SvelteKit, the JWT is available from the Supabase session:
const { data: { session } } = await supabase.auth.getSession();
const token = session?.access_token;
Base URL
https://your-domain.vercel.app/apiEndpoints Overview
| Method | Path | Description |
|---|---|---|
| GET | /me | Get current user profile |
| GET | /credits/balance | Get credit wallet balance |
| GET | /credits/transactions | List credit ledger entries |
| GET | /credit-packages | List active credit packages |
| POST | /payments/initialize | Initialize a Paystack payment |
| GET | /payments/{reference} | Get payment order status |
| GET | /datasets | List datasets |
| POST | /datasets | Upload and create a dataset |
| GET | /datasets/{id} | Get dataset details |
| DELETE | /datasets/{id} | Delete a dataset |
| GET | /datasets/{id}/rows | Get paginated dataset rows |
| GET | /templates | List document templates |
| POST | /templates | Upload a document template |
| GET | /templates/{id} | Get template details |
| PATCH | /templates/{id} | Update template metadata |
| DELETE | /templates/{id} | Delete a template |
| GET | /campaigns | List campaigns |
| POST | /campaigns | Create a new campaign |
| GET | /campaigns/{id} | Get campaign details |
| POST | /campaigns/{id}/start | Start a campaign |
| POST | /campaigns/{id}/pause | Pause a running campaign |
| POST | /campaigns/{id}/resume | Resume a paused campaign |
| POST | /campaigns/{id}/cancel | Cancel a campaign |
| GET | /campaigns/{id}/report | Get delivery report |
| POST | /smtp/test | Test SMTP configuration |
| POST | /webhooks/paystack | Paystack webhook (no auth) |
| POST | /internal/dispatch | Internal: dispatch next email job |
Common Response Format
All endpoints return JSON with a consistent envelope:
{"success": true, "data": { ... }}Error responses:
{"success": false, "error": "Human-readable message", "code": "ERROR_CODE"}Rate Limiting
There is currently no strict rate limit on individual API calls. Campaign dispatch throughput is limited by your SMTP server's sending rate. Abuse of the API may result in account suspension per the Acceptable Use Policy.
Notes on Internal Endpoints
The POST /internal/dispatch endpoint is used by the campaign dispatch worker (Vercel cron or manual trigger).
It requires the internal CRON_SECRET header rather than a user Bearer token.
Do not call this endpoint directly unless you are building custom dispatch automation.