Introduction

The Account API lets you manage your Maileroo account programmatically. It’s a simple RESTful, JSON-based API that allows you to handle the same tasks you would normally do in the dashboard, directly from your own code.

All resources share the same conventions for authentication, rate limiting, responses, and errors described below.

Should you require more features, please reach out to our support team and we will be happy to help.

Base URL

All endpoints are served under the /v1 prefix:

https://api.maileroo.com/v1

Authentication

Every request must be authenticated with an API key, supplied as a Bearer token in the Authorization header:

GET /v1/account HTTP/1.1
Host: api.maileroo.com
Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl https://api.maileroo.com/v1/account \
  -H "Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Requirements for every request:

• The API key must be valid and not revoked.
• The key must include the scope required by the endpoint being called (see below).
• If the key has an IP allowlist configured, the request must originate from an allowed IP address.

Scopes

API keys are granted granular scopes. Each endpoint requires a specific scope, and write scopes imply their corresponding read scope. Common scopes include:

A request made with a key that lacks the required scope is rejected with 403 Forbidden.

Rate Limits

Requests are rate limited per account to 180 requests per minute.

Every response includes the following headers so you can track your usage:

When the limit is exceeded, the API responds with 429 Too Many Requests and also sets a Retry-After header (in seconds) indicating how long to wait before retrying.

Response

Successful responses return a 2xx status code with the payload wrapped in a top-level data object:

{
  "data": {
    "user_id": 12345,
    "name": "Jane Doe",
    "email": "[email protected]"
  }
}

data may be an object or an array depending on the endpoint (for example, list endpoints return a paginated collection). The HTTP status code indicates the outcome of the request.

Error Codes & Messages

Errors return the appropriate HTTP status code with the payload wrapped in a top-level error object:

{
  "error": {
    "message": "Your API key does not have the required scope to access this resource."
  }
}

Common errors that can occur on any endpoint:

Endpoint-specific validation errors (for example, a bad request body) are returned with a 4xx status and a descriptive message in the same error envelope.