Introduction | Reloop Docs

Welcome to the Reloop API Reference. The Reloop API is built on REST principles. We enforce HTTPS in every request to improve data security, integrity, and privacy.

Authentication

Every request must include your API key in the x-api-key header. API keys are scoped to a single organization — all resources you create, read, or modify are automatically associated with that organization.

curl -X GET "https://reloop.sh/api/domain/v1/list" \
  -H "x-api-key: rl_prod_YOUR_API_KEY"

You can create, rotate, and revoke API keys from the Reloop Dashboard.

Required Headers

Header	Value	When
`x-api-key`	Your Reloop API key (prefixed `rl_prod_`)	Every request
`Content-Type`	`application/json`	Requests with a body (`POST`, `PUT`, `PATCH`)

Response Format

All responses — including errors — are returned as JSON. Successful responses typically include an event field describing the action performed:

{
  "event": "contact.created",
  ...
}

Response Codes

The API uses standard HTTP status codes to indicate the outcome of a request:

Code	Meaning	When You'll See It
`200`	OK	Request succeeded.
`201`	Created	A new resource was created successfully.
`400`	Bad Request	Missing or invalid parameters — check the `why` field for details.
`401`	Unauthorized	The `x-api-key` header is missing, invalid, or the key has been revoked.
`403`	Forbidden	The API key doesn't have permission to access the requested resource.
`404`	Not Found	The resource doesn't exist, or it belongs to a different organization.
`409`	Conflict	A resource with the same unique identifier already exists (e.g., duplicate domain or channel name).
`429`	Too Many Requests	You've exceeded a rate limit. Retry after the `Retry-After` header value.
`500`	Internal Server Error	Something went wrong on our end. If the issue persists, contact support.

Errors

When a request fails, the response body always contains four fields to help you diagnose and fix the issue:

{
  "message": "Domain not found",
  "why": "The domain acme.com was not found or is not authorized for your organization",
  "fix": "Ensure the domain is registered and verified in your dashboard",
  "link": "https://reloop.sh/docs/api/errors"
}

Field	Description
`message`	A short, human-readable summary of the error.
`why`	A detailed explanation of what went wrong and what triggered the error.
`fix`	Actionable steps you can take to resolve the issue.
`link`	A URL to the relevant documentation page for more context.

See the Errors page for a full reference of common error codes and troubleshooting tips.

Rate Limits

Rate limits are applied per organization and vary by endpoint. Every API response includes headers so you can monitor your usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	Requests remaining before the limit is reached.
`X-RateLimit-Window`	Window size in seconds (management endpoints like domains, contacts, and channels).
`X-RateLimit-Reset`	Unix epoch timestamp when the window resets (email sending endpoints).
`Retry-After`	Seconds to wait before retrying (only returned with `429` responses).

For the full breakdown of per-endpoint limits and the multi-layer email sending strategy, see Usage Limits.