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.net"], "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. Attachments, templates, 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, separately for test and live sends. Request limits are 100 accepted requests per second per key and 200 per workspace. The worker also observes the SES account's recipient-weighted rate and daily allowance.