Mail API

Ration exposes mail only through /apis/v1/mail. The API provides allowlisted, user-scoped mailbox, message, attachment, flag, and folder operations while authenticating clients with Ration bearer tokens. Paths not listed on this page are not available through the public Mail API.

This reference is the public contract. Mail resource operations preserve the status and JSON resource returned by Ration's mail service; Ration does not wrap or rename those resource responses. Integrations should use the fields documented here and tolerate additional fields in a response.

Authentication and path mapping

Send the Ration access token:

Authorization: Bearer <ration_access_token>
Accept: application/json

Ration executes the request as the authenticated user. Use the Ration bearer header shown above; do not include provider-specific authentication headers.

For mail resource operations, use the /apis/v1/mail prefix. For example:

Mail resource	Ration API path
/users/me/mailboxes	/apis/v1/mail/users/me/mailboxes
/users/me/mailboxes/:mailbox/messages	/apis/v1/mail/users/me/mailboxes/:mailbox/messages
/users/me/mailboxes/:mailbox/messages/:message	/apis/v1/mail/users/me/mailboxes/:mailbox/messages/:message

Only the method-and-path combinations documented below are available. Requests to account administration, security, storage, filters, automatic replies, raw message source, or any path outside the caller's /users/me mailbox tree return 404 unless Ration provides a separate documented endpoint.

Ration-specific convenience endpoints

Save a draft

POST /apis/v1/mail/draft

Creates a message in a mailbox and records the recipient addresses for Ration autocomplete. The request must contain mailbox plus a structured-message body.

{
  "mailbox": "<drafts_mailbox_id>",
  "draft": true,
  "from": {"name": "Ada", "address": "ada@example.com"},
  "to": [{"name": "Sam", "address": "sam@example.net"}],
  "cc": [],
  "bcc": [],
  "subject": "Project update",
  "text": "Hello Sam,\n\nHere is the update.",
  "html": "<p>Hello Sam,</p><p>Here is the update.</p>"
}

Response: the message result wrapped as {"message": {...}}. Ration returns 403 {"error":"tenant_id_required"} when the authenticated user has no tenant context.

Request parameters

Name	In	Type	Required	Description
mailbox	Body	String	Yes	Target mailbox identifier.
draft	Body	Boolean	No	Set true to save rather than send.
from, replyTo	Body	Address object	No	Sender or reply-to identity.
to, cc, bcc	Body	Address array	No	Recipient lists.
subject	Body	String	No	Message subject.
text, html	Body	String	No	Plain-text and HTML content.
attachments, files	Body	Array	No	Inline attachment payloads or stored file identifiers.
reference	Body	Object	No	Reply, reply-all, or forward source.
replacePrevious	Body	Object	No	Existing draft to replace.

Response parameters — 200 OK

Name	Type	Description
message	Object	Stored-message result. Ration wraps this endpoint's result in message when necessary.
message.id	Number	New message identifier, when returned.
message.mailbox	String	Mailbox identifier, when returned.
message.size	Number	Message size in bytes, when returned.

Submit a draft

POST /apis/v1/mail/draft/submit

{
  "mailbox_id": "<drafts_mailbox_id>",
  "message_id": "123"
}

This submits the selected draft for delivery. The response status and JSON body contain the submission result. Recipient addresses from the submitted draft are added to Ration’s autocomplete data.

Request parameters

Name	In	Type	Required	Description
mailbox_id	Body	String	Yes	Mailbox containing the draft.
message_id	Body	String	Yes	Draft message identifier.

Response parameters — 200 OK

Name	Type	Description
Response body	Object	Submission result returned by the mail service. Do not rely on an id or message field being present.

Download an attachment

GET /apis/v1/mail/attachment

Query parameters:

Parameter	Required	Description
mailbox_id	Yes	Mailbox containing the message.
message_id	Yes	Message identifier.
attachment_id	Yes	Attachment identifier.
filename	Yes	Filename used in the download response.

Response: attachment bytes as a download, rather than a JSON envelope.

Response parameters — 200 OK

Name	In	Type	Description
Content-Disposition	Header	String	Download filename, based on filename.
Response body	Body	Binary	Attachment content.

Mailbox operations

The following Ration Mail API operations are available through the mail prefix.

Method	Ration path	Main request parameters	Successful response
GET	/mail/users/me/mailboxes	Pagination and mailbox-list query options.	Mailbox list and cursors.
POST	/mail/users/me/mailboxes	Mailbox path/name and optional mailbox configuration.	Created mailbox.
GET, PUT, DELETE	/mail/users/me/mailboxes/:mailbox	Read or manage one mailbox.	Mailbox or deletion result.
GET, POST, PUT	/mail/users/me/mailboxes/:mailbox/messages	List, create, or update a set of messages.	Message list or operation result.
GET, PUT, DELETE	/mail/users/me/mailboxes/:mailbox/messages/:message	Read or manage one message.	Message or deletion result.
POST	/mail/users/me/mailboxes/:mailbox/messages/:message/submit	Submit a stored draft.	Submission result.

List mailboxes

GET /apis/v1/mail/users/me/mailboxes

Request parameters

Name	In	Type	Required	Description
counters	Query	Boolean	No	Include mailbox counters when available. Used by the Ration client.
Other query parameters	Query	String	No	Passed through only for this allowlisted list route. Use documented response cursors rather than relying on undocumented filters.

Response parameters — 200 OK

Name	Type	Description
total	Number	Total number of matching mailboxes.
nextCursor, previousCursor	String or Boolean	Cursor for another page, or false when unavailable.
results	Array	Mailbox records.
results[].id	String	Mailbox identifier.
results[].path	String	Mailbox path/name.
results[].specialUse	String	Special-use role such as Inbox, Sent, Drafts, or Trash when configured.

Create a mailbox

POST /apis/v1/mail/users/me/mailboxes

Request parameters

Name	In	Type	Required	Description
path	Body	String	Yes	Mailbox name or path.
retention	Body	Number	No	Retention setting, where enabled for the tenant.
subscribed	Body	Boolean	No	Whether the mailbox is subscribed by default.
hidden	Body	Boolean	No	Reserved for Ration system mailboxes. A value of true or the string "true" is rejected.

Response parameters — 200 or 201

Name	Type	Description
id	String	New mailbox identifier.
path	String	Created mailbox path.
name	String	Display name.
specialUse	String	System role when one is assigned.

Read or manage one mailbox

GET|PUT|DELETE /apis/v1/mail/users/me/mailboxes/:mailbox

Request parameters

Name	In	Type	Required	Description
mailbox	Path	String	Yes	Mailbox identifier.
path	Body (PUT)	String	No	New mailbox path/name.
retention, subscribed	Body (PUT)	Number, Boolean	No	Supported mailbox settings.
hidden	Body (PUT)	Boolean	No	A value of true or the string "true" is rejected; this setting is reserved for Ration system mailboxes.

Response parameters — 200 OK

Name	Type	Description
id	String	Mailbox identifier.
path, name	String	Current mailbox path and display name.
success	Boolean	Returned for operations that do not return a mailbox object.

List messages in a mailbox

GET /apis/v1/mail/users/me/mailboxes/:mailbox/messages

Request parameters

Name	In	Type	Required	Description
mailbox	Path	String	Yes	Mailbox identifier.
limit	Query	Number	No	Maximum messages to return.
order	Query	String	No	Sort order. The Ration client sends its selected sort value.
unseen	Query	Boolean	No	Limit results by read state when supported.
threadCounters	Query	Boolean	No	Request thread counters where supported.
cursor	Query	String	No	Pagination cursor returned as nextCursor or previousCursor.
direction	Query	String	No	Cursor direction. The Ration client uses next when loading another page.

Response parameters — 200 OK

Name	Type	Description
total	Number	Total matching messages.
nextCursor, previousCursor	String or Boolean	Pagination cursor or false.
results	Array	Message summary records.
results[].id	Number	Message identifier within the mailbox.
results[].mailbox	String	Parent mailbox identifier.
results[].from, results[].to	Address object/array	Sender and recipient summary.
results[].subject	String	Message subject.
results[].date	ISO 8601 string	Message timestamp.
results[].unseen, results[].flagged	Boolean	Read and flagged state.
results[].attachments	Array	Attachment metadata, when present.

Create or update mailbox messages

POST|PUT /apis/v1/mail/users/me/mailboxes/:mailbox/messages

Use POST to create a message. Use PUT to apply a supported action to the message IDs supplied in message—for example, update seen/flagged state or move messages.

Request parameters

Name	In	Type	Required	Description
mailbox	Path	String	Yes	Source or destination mailbox identifier.
message	Body (PUT)	String or Number array	Yes for PUT	One or more message identifiers.
seen	Body (PUT)	Boolean	No	Read state to apply.
moveTo	Body (PUT)	String	No	Destination mailbox identifier.
restoreToOrigin	Body (PUT)	Boolean	No	Restore the selected message(s) to their original mailbox when supported.
Structured message fields	Body (POST)	Object	Yes	See Structured message fields.

Response parameters — 200 or 201

Name	Type	Description
Response body	Object	Created-message or bulk-operation result returned by the mail service. The exact result depends on the operation.

Read, update, or delete one message

GET|PUT|DELETE /apis/v1/mail/users/me/mailboxes/:mailbox/messages/:message

Request parameters

Name	In	Type	Required	Description
mailbox	Path	String	Yes	Mailbox identifier.
message	Path	Number	Yes	Message identifier.
Message fields	Body (PUT)	Object	No	Update fields accepted for an individual message. For bulk seen-state and moving messages, use the collection PUT endpoint above.

Response parameters — 200 OK

Name	Type	Description
id	Number	Message identifier.
mailbox	String	Message mailbox.
text, html	String	Rendered body content, when available.
headers	Array	Parsed message headers, when available.
attachments	Array	Attachment metadata, when present.

For DELETE, the successful response contains the deletion result rather than a message object.

Submit a mailbox draft

POST /apis/v1/mail/users/me/mailboxes/:mailbox/messages/:message/submit

Request parameters

Name	In	Type	Required	Description
mailbox	Path	String	Yes	Mailbox containing the draft.
message	Path	Number	Yes	Draft message identifier.
Delivery fields	Body	Object	No	Optional delivery fields supported for the draft.

Response parameters — 200 OK

Name	Type	Description
Response body	Object	Submission result returned by the mail service.

Structured message fields

When creating or saving a structured message, use the fields below as needed.

Field	Type	Purpose
from, replyTo	Address object	{ "name": "…", "address": "…" } sender/reply address.
to, cc, bcc	Address array	Recipient lists.
subject	String	Subject line.
text, html	String	Plain-text and HTML bodies.
draft, unseen, flagged	Boolean	Initial message state.
attachments	Array	Inline attachment objects with filename, MIME type, base64 content, and optional content ID/disposition.
files	String array	Previously stored attachment IDs.
reference	Object	Reply, reply-all, or forward source (mailbox, id, action, optional attachments).
replacePrevious	Object	Replace an existing draft (mailbox, id).

The Ration composer creates structured messages with the fields above. File references in files are not publicly uploadable through this API; use inline attachments for an API-created draft or message.

Responses and errors

Ration-owned errors

Mail-service validation and missing-resource responses are forwarded unchanged. The errors below are generated by Ration itself and are safe for an integration to branch on.

Status	Body	Meaning
401	Authentication error	The bearer token is missing, expired, or invalid.
403	{ "error": "tenant_id_required" }	The draft convenience endpoint requires a tenant-scoped user.
404	{ "error": "mail_endpoint_not_available" }	The method/path pair is not part of the public Mail API.
422	{ "error": "hidden_mailbox_not_allowed" }	A mailbox create/update attempted to set hidden to true.
500	{ "error": "Proxy failed" } or { "error": "Internal server error" }	Ration could not complete the proxy or a convenience operation. Retry only when appropriate for your client.

Common successful statuses are 200 for reads/updates and 201 for creates. A downstream 400, 403, 404, or other non-2xx resource response is returned with its original status and JSON body.

Use cursors returned by list endpoints rather than offset-based pagination where the response provides nextCursor or previousCursor. Do not assume IDs are interchangeable between mailboxes, messages, attachments, and outbound queue entries.

Scope mail clients carefully

The mail proxy acts as the bearer-token user. Never place a Ration access token in browser-visible source, mobile logs, screenshots, or a third-party client that you do not control.