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.
`202`	Accepted	A background job was started. Poll the URL in the `Location` header (see Long-running operations).
`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), or a request with the same Idempotency-Key is still running.
`422`	Unprocessable Content	The request did not match the endpoint's schema (`errors` lists each field), or an Idempotency-Key was reused with a different request.
`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.

Long-running operations

Operations that take longer than a request, such as emailing a contacts export, return 202 Accepted right away and run in the background. The response includes:

A Location header with the URL of the job's status resource (also in the body as statusUrl).
A Retry-After header with the seconds to wait before polling.

curl -X POST "https://reloop.sh/api/contacts/v1/export/email" \
  -H "x-api-key: rl_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "subscribed"}'
# HTTP/1.1 202 Accepted
# Location: /api/contacts/v1/exports/exp_abc123
# Retry-After: 5

curl "https://reloop.sh/api/contacts/v1/exports/exp_abc123" \
  -H "x-api-key: rl_prod_YOUR_API_KEY"
# { "object": "contact_export", "id": "exp_abc123", "status": "processing", ... }

Poll the Location URL with GET until status is final (ready or failed), waiting Retry-After seconds between requests. Job status is kept for 7 days.

Errors

When a request fails, the response body is a JSON object with a stable code plus fields that help you diagnose and fix the issue:

{
  "code": "not_found",
  "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
`code`	A stable, machine-readable error code such as `validation_error` or `rate_limited`. Branch on this.
`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.