Limits & facts | RRay — Transactional Email API

Base URL and versioning


Base URL	`https://api.rray.app`
Version prefix	`/v1` on every endpoint except the public error catalog (`/errors`)
Content type	`application/json` requests, `application/json` responses, `application/problem+json` errors
Auth header	`Authorization: Bearer rray_live_...`

The version lives in the path. A breaking change ships as a new prefix; /v1 keeps its contract.

What fits in one send

Limit	Value
Recipients per message	At least one in `to`; no fixed ceiling across `to`, `cc` and `bcc`
Duplicate recipients	Not allowed — an address may appear only once across `to`, `cc` and `bcc`
Messages per batch	1 to 100 per `POST /v1/messages/batch`
Attachments per message	No count limit
Attachment bytes per message	10 MiB total, decoded, across every attachment
Attachment URL fetch	10 s timeout; the target must resolve to a public address
Attachment file types	Executable and script extensions are refused (`.exe`, `.bat`, `.cmd`, `.com`, `.scr`, `.msi`, `.vbs`, `.js`, `.jar`, `.ps1`, `.lnk`, `.app`, `.dll`, `.sh`, `.ps`, `.reg`, `.msc`, `.pif`, `.hta`, `.cpl`)
Subject and body size	No API-level limit; the attachment budget is the only byte ceiling

Every recipient is one delivery, and every delivery counts once against your allowance. A message to three addresses costs three.

Rate limits

Credential	Limit	Counted per
Workspace key	300 requests/minute	Workspace (all of its keys share the budget)
Platform key	3000 requests/minute	Account

Fixed one-minute windows. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 adds Retry-After in seconds. See Rate limits.

Quota headers

Send endpoints report your plan allowance as structured-field dictionaries: RRay-Quota-Limit, RRay-Quota-Remaining and RRay-Quota-Reset.

Key	Meaning
`account.daily`	Deliveries the account may send in one UTC day. Always present.
`account.monthly`	Deliveries included this period — prorated by time on each plan after a mid-period change.
`account.monthly_overage`	Deliveries available beyond the included volume, bounded by your overage budget. Present only when a budget is set.
`workspace.monthly`	Replaces the two `account.monthly*` keys when a workspace key acts on a workspace that has its own limit.

RRay-Quota-Reset values are Unix timestamps: the end of the UTC day for account.daily, the end of the billing period for the rest.

Changing plan mid-period

Your delivery counter belongs to the billing period, not to the plan: an upgrade keeps the count where it is. The allowance and the overage are prorated by the time you spent on each plan, exactly the way the plan fee is.

Upgrade from Starter to Growth on day 15 of a 30-day period and the period includes 7,500 + 37,500 = 45,000 deliveries — half of each plan’s package.

Overage is split across the plans you were on in the same proportion, and each part is priced at that plan’s own rate, so an invoice shows them as separate lines.

The dashboard and RRay-Quota-Limit report the prorated allowance the moment the upgrade applies. The plan’s full allowance applies from the next period on.

Overage for a closed period is billed on its own invoice, raised right after the period ends. While such an invoice is unpaid, sending is paused and plan changes are refused; paying it resumes both.

Downgrades and cancellation take effect at the end of the period. You keep the current plan’s allowance until then, and the next period starts on the new plan. Cancelling moves you to Free rather than removing your account.

Plan fees are charged in advance. If a renewal cannot be collected after the retries, the account moves to Free, the uncollected renewal is cancelled, and nothing is owed for it.

Retention

Data	Kept for
Message bodies (`GET /v1/messages/{id}/body`)	30 days after send, then removed — the message itself still reads normally
Messages, deliveries and events	The full stored history; no product window narrows it today
`Idempotency-Key` claims	24 hours, after which the key is free to use again

Pagination


`limit`	1 to 100, default 20
`total`	Exact up to 10 000, then reported as `total: 10000` with `total_capped: true`
`total` on cursor pages	`null` — counting runs on the first page only

See Pagination.

Statistics windows

GET /v1/stats takes last buckets of size group_by, including the current partial one. The default is 1 for every grouping.

`group_by`	Maximum `last`
`day`	90
`week`	52
`month`	24

Workspace headers


`RRay-Workspace-Id`	Exactly one workspace id, no commas
`RRay-Workspace-Ids`	1 to 50 comma-separated ids, unique, `GET /v1/stats` only
Workspace name	1 to 100 characters, unique within your account

See Workspaces.

Identifiers

Ids are a short prefix, an underscore, and an opaque suffix. The prefix tells you what kind of object it is. Treat the suffix as opaque: do not parse it, and store ids as strings.

Prefix	Object	Example
`msg_`	Message	`msg_01M4ANAVD7EYMHY0PWSH5PBDJD`
`ws_`	Workspace	`ws_01KYA3AWSZGCB9YMNKM5AQBA8G`
`evt_`	Delivery event	`evt_01M4ANAVDNW22V8M1EHEPQJ8DM`
`cus_`	Account	`cus_01KYA3AWSYX8ZWK2CJ4N0JYQ7D`
`key_`	API key record	`key_01KYA3AX04ME5Z2B3H9GQNQJ8R`

API key secrets are not ids: they look like rray_live_... or rray_test_... and are shown exactly once. Ids are stable and safe to log; secrets are neither.

Proprietary headers

Standard headers are used bare (Idempotency-Key, RateLimit-*, Retry-After). Everything proprietary is RRay--prefixed; there are no X- headers in this API.

Header	Direction
`RRay-Workspace-Id`	Request
`RRay-Workspace-Ids`	Request, `GET /v1/stats` only
`RRay-Batch-Validation`	Request, `POST /v1/messages/batch` only
`RRay-Request-Id`	Response, on every response. Send one and it is echoed back and used as the correlation id.
`RRay-Quota-Limit`, `RRay-Quota-Remaining`, `RRay-Quota-Reset`	Response, send endpoints