API reference
Send an email
POST /v1/emails accepts a message for durable, asynchronous processing.
Request
curl https://api-production-1c6a.up.railway.app/v1/emails \ -H "Authorization: Bearer $RAVENRELAY_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: welcome-user-123' \ -d '{ "from": "hello@example.com", "to": ["user@example.com"], "subject": "Welcome", "text": "Hello from RavenRelay" }'| Field | Type | Requirement |
|---|---|---|
from | string | Required. Address or Name <address> on the exact verified domain. |
to | string | string[] | Required. At least one recipient. |
subject | string | Required. 1–998 characters; no line breaks. |
text / html | string | At least one nonempty body. |
cc / bcc | string | string[] | Optional. Maximum 50 recipients across To, CC and BCC. |
reply_to | string | Optional mailbox. |
headers | object | Optional custom headers. Reserved transport headers are rejected. |
tags | object | Up to 20 ASCII tags. Names beginning rr_ are reserved. |
metadata | object | Optional application data, retained in RavenRelay. |
The message limit is 10 MiB. Saved template sends are supported; see React Email and templates. Attachments, scheduled sends and batch sends are not supported by this endpoint.
Response
{ "id": "your-email-id", "status": "queued", "test_mode": false}The worker processes the message after admission. The response does not confirm provider acceptance or delivery.
{ "id": "your-email-id", "status": "suppressed", "reason": "hard_bounce"}If any recipient is actively suppressed, the entire message is stored as suppressed without a queue job or monthly quota charge.
Retry safely with idempotency
Set Idempotency-Key to a unique application operation ID, using 1–128 printable ASCII characters. Reuse the same key and identical body after a timeout. Keys are scoped to the project.
A replay returns the original admission result and email ID even if processing has advanced. Reusing a key with a changed body returns 409 idempotency_conflict. The Node SDK does not automatically retry sends.
Quotas and rate limits
Monthly quotas count accepted recipients, including CC and BCC, across production and development sends together. Development keys allow 15 accepted send requests per 60-second window, starting with the first accepted request. Replays and suppressed requests count; rejected requests do not. Excess requests return HTTP 429 rate_limit_exceeded with a wait time. Production keys allow 100 accepted requests per second; the shared workspace limit remains 200 per second. Reading emails is unaffected. Each development key is capped at 1,000 accepted recipients per UTC calendar month, including To, CC and BCC. These sends also count toward the shared workspace allowance; suppressed sends and idempotent replays do not add monthly usage. The worker also observes the delivery provider account's recipient-weighted rate and daily allowance.