Authentication & Rate limiting
On this page:
Authenticate requests with a Bearer token. Create a token under API Tokens in your account settings.
Authentication
Enter a token name, choose its permissions, and click Create. Copy the token when it is displayed; it will not be shown again. The page also lists your team’s API URL and domain.
- All API endpoints is intended for integrations that manage lists, subscribers, templates, or campaigns. Your account’s permissions still apply.
- Send only is intended for integrations that only send transactional emails. Use this more limited permission when it covers your integration’s needs.
Keep the token on your server, outside your source code. Never expose it in browser JavaScript. Requests must use a team domain your account can access, such as https://<your-team>.mailcoach.app/api.
Use an All API endpoints token for this read-only authentication check:
MAILCOACH_API_URL='https://<your-team>.mailcoach.app/api' MAILCOACH_TOKEN='your-api-token' curl "$MAILCOACH_API_URL/user" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json'
The response contains the ID and email address of the user who owns the token:
{ "data": { "id": 1, "email": "john@example.com" } }
For an explanation of unsuccessful responses, see error handling.
Rate limiting
The default limits for Mailcoach Cloud are:
- Authenticated API requests: 300 per minute, shared by tokens belonging to the same user.
- Transactional sends: 3,000 per minute for
POST /api/transactional-mails/send, instead of the default authenticated limit. Tokens belonging to the same user share this allowance. - Unauthenticated requests that reach the API limiter: 60 per minute, shared by requests from the same IP address.
The transactional exception applies only to sending, not to every transactional email endpoint. Authenticated endpoints still require a valid token; the unauthenticated limit does not grant access to them. Account-specific limits may differ.
Campaign click statistics (GET /api/campaigns/{campaign}/clicks) and individual link lookups (GET /api/links/{link}) also share a 5 requests per second per team burst limit. The normal minute limit still applies to those requests.
Minute limits are not per-second limits or a guarantee of sustained throughput. Multiple API tokens belonging to one user do not each receive a separate minute allowance.
Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers for the applicable limit. When a limit is exceeded, the API returns 429 Too Many Requests and a Retry-After header with the number of seconds to wait before trying again.