Skip to navigation
API Referencemessages

Send Message

Queue one message for delivery and return its id. A 202 Accepted means the message is stored and handed off for delivery, not that it has been delivered — poll GET /v1/messages/{message_id} for the live status and the per-recipient timeline.

Every address across to, cc and bcc becomes its own delivery and counts once against your allowance. The response carries RRay-Quota-Limit, RRay-Quota-Remaining and RRay-Quota-Reset describing that allowance.

Authentication

AuthorizationBearer

A workspace key (rray_live_…, bound to one workspace) or the account’s platform key. Platform keys name the target workspace with RRay-Workspace-Id. See Credentials.

Headers

Idempotency-Keystring or nullOptional

Makes a retry safe. The first request with a key performs the send; a retry with the same key and the same body replays the stored response, returning the original message id without sending again. The same key with a different body is 409 idempotency.body_mismatch. Claims are kept for 24 hours, then the key is free to reuse. Omit the header and every attempt sends.

RRay-Workspace-Idstring or nullOptional

The workspace to act on. Required with a platform key; rejected with a workspace key, which already carries its workspace — a matching value is rejected too, rather than silently ignored. An id that is not yours returns 404 workspace.not_found.

Request

This endpoint expects an object.
fromstringRequired

Sender address, optionally with a display name (Acme Receipts <receipts@mail.rray.app>). Use an address on a sending domain you have added, so the message can be signed — unsigned mail is very likely to be refused by the recipient’s provider.

tolist of stringsRequired

Primary recipients, at least one. An address may not repeat anywhere across to, cc and bcc.

cclist of strings or nullOptional

Carbon-copy recipients. Visible to every recipient.

bcclist of strings or nullOptional

Blind carbon-copy recipients. Not visible to other recipients, but each one is a delivery you can track like any other.

reply_tostring or list of strings or nullOptional

Where replies should go instead of from — one address or several.

subjectstring or nullOptional

Subject line. Single-line text.

htmlstring or nullOptional

HTML body. Send html, text, or both; with both, the recipient’s client picks the part it prefers.

textstring or nullOptional

Plain-text body.

attachmentslist of objects or nullOptional
Files to attach, totalling at most 10 MiB once decoded.

Response

Successful Response
idstring

Identifier of the accepted message. Pass it to GET /v1/messages/{message_id} to follow the delivery.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
413
Content Too Large Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error