API reference

Mail

Send mail from your own domains, read the delivery log, receive inbound mail, and manage suppressions.

Rytiv sends mail from domains you prove (SPF, DKIM and a verification record are shown by the domain routes) and keeps a log per message. A key with the scope mail:send or mail:send:<domain> may send and nothing else.

Endpoints

POST /v1/emails: Sends a message from one of the organization’s proven domains
GET /v1/emails: The delivery log
GET /v1/emails/:id: One message with its deliveries
GET /v1/mail/domains: The sending domains and their status
POST /v1/mail/domains: Adds a sending domain and answers the records to set
GET /v1/mail/domains/:domain: One sending domain
POST /v1/mail/domains/:domain/verify: Checks the domain’s records now
DELETE /v1/mail/domains/:domain: Removes a sending domain
POST /v1/mail/domains/:domain/inbound/routes: Routes inbound mail for an address of the domain
DELETE /v1/mail/domains/:domain/inbound/routes/:id: Removes an inbound route
GET /v1/mail/inbound: Inbound messages
GET /v1/mail/inbound/:id: One inbound message
GET /v1/mail/suppressions: Addresses Rytiv no longer sends to (bounces, complaints)
DELETE /v1/mail/suppressions/:address: Removes an address from the suppression list

POST /v1/emails

Sends a message from one of the organization’s proven domains.

Auth: API key with full access or the scope mail:send (or mail:send:<domain> for the sending domain). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Request body

JSON, the shape SendEmailRequest of the contract.

Field	Type	Required	Description
`from`	string	required	3 to 400 characters.
`to`	string	required	Another hostname of the same app to redirect to, or `null` to clear the redirect. 3 to 254 characters.
`subject`	string	required	1 to 998 characters.
`text`	string	optional	at most 1000000 characters.
`html`	string	optional	The page as HTML. at most 1000000 characters.
`replyTo`	string	optional	3 to 254 characters.
`headers`	object	optional
`headers.List-Unsubscribe`	string	optional
`headers.List-Unsubscribe-Post`	string	optional
`headers.In-Reply-To`	string	optional
`headers.References`	string	optional
`attachments`	array of object	optional	0 to 10 items.

Example request

curl -X POST "https://api.rytiv.app/v1/emails" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"<from>","to":"www.example.com","subject":"<subject>"}'

Response

202 with a JSON object carrying status.

Errors

Status	Code	Meaning
400	`bad-request`	The request is malformed or a field is out of range. `error` names every field; `issues` lists them.
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.

GET /v1/emails

The delivery log.

Auth: API key with full access or the scope read. An agent token of class production needs prodDataRead for it; sandbox and twin may call it.

Query parameters

Name	Description
`limit`	How many entries, at most.

Example request

curl -X GET "https://api.rytiv.app/v1/emails" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.

GET /v1/emails/:id

One message with its deliveries.

Auth: API key with full access or the scope read. An agent token of class production needs prodDataRead for it; sandbox and twin may call it.

Path parameters

Name	Description
`id`	The object’s id.

Example request

curl -X GET "https://api.rytiv.app/v1/emails/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON object carrying events and the fields of the object the handler builds.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

GET /v1/mail/domains

The sending domains and their status.

Auth: API key with full access or the scope read. Every class of agent token may call it.

Example request

curl -X GET "https://api.rytiv.app/v1/mail/domains" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.

POST /v1/mail/domains

Adds a sending domain and answers the records to set.

Auth: API key with full access (a key with scopes cannot call this route). An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Request body

JSON, the shape AddMailDomainRequest of the contract.

Field	Type	Required	Description
`domain`	string	required	The domain, for example `www.example.com`. Wildcards are not accepted. 1 to 253 characters.

Example request

curl -X POST "https://api.rytiv.app/v1/mail/domains" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"www.example.com"}'

Response

201 with a JSON object carrying appDomain, records and the fields of the object the handler builds.

Errors

Status	Code	Meaning
400	`bad-request`	The request is malformed or a field is out of range. `error` names every field; `issues` lists them.
400	`name-reserved`	The platform keeps this name (for example `api`, `console`, `docs`, `www`, and every name that is `rytiv` or starts with `rytiv-`).
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
409	`already-exists`	You already have it; an idempotent create may treat this as done.
409	`name-taken`	The name is used somewhere on Rytiv (an app, a database, a volume or a bucket).
429	`too-many-pending`

GET /v1/mail/domains/:domain

One sending domain.

Auth: API key with full access or the scope read. Every class of agent token may call it.

Path parameters

Name	Description
`domain`	The domain, as added.

Example request

curl -X GET "https://api.rytiv.app/v1/mail/domains/<domain>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON object carrying appDomain, records, inbound and the fields of the object the handler builds.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

POST /v1/mail/domains/:domain/verify

Checks the domain’s records now.

Path parameters

Name	Description
`domain`	The domain, as added.

Example request

curl -X POST "https://api.rytiv.app/v1/mail/domains/<domain>/verify" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON object carrying domain, status, checks.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

DELETE /v1/mail/domains/:domain

Removes a sending domain.

Path parameters

Name	Description
`domain`	The domain, as added.

Example request

curl -X DELETE "https://api.rytiv.app/v1/mail/domains/<domain>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON object carrying domain, removed.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

POST /v1/mail/domains/:domain/inbound/routes

Routes inbound mail for an address of the domain.

Path parameters

Name	Description
`domain`	The domain, as added.

Request body

JSON, the shape AddMailInboundRouteRequest of the contract.

Field	Type	Required	Description
`address`	string	required	1 to 320 characters.
`action`	`store`	optional	default `"store"`.

Example request

curl -X POST "https://api.rytiv.app/v1/mail/domains/<domain>/inbound/routes" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address":"<address>"}'

Response

201 with a JSON body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

DELETE /v1/mail/domains/:domain/inbound/routes/:id

Removes an inbound route.

Path parameters

Name	Description
`domain`	The domain, as added.
`id`	The object’s id.

Example request

curl -X DELETE "https://api.rytiv.app/v1/mail/domains/<domain>/inbound/routes/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

204 with no body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

GET /v1/mail/inbound

Inbound messages.

Auth: API key with full access or the scope read. An agent token of class production needs prodDataRead for it; sandbox and twin may call it.

Query parameters

Name	Description
`limit`	How many entries, at most.
`domain`

Example request

curl -X GET "https://api.rytiv.app/v1/mail/inbound" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.

GET /v1/mail/inbound/:id

One inbound message.

Auth: API key with full access or the scope read. An agent token of class production needs prodDataRead for it; sandbox and twin may call it.

Path parameters

Name	Description
`id`	The object’s id.

Example request

curl -X GET "https://api.rytiv.app/v1/mail/inbound/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON object carrying raw, text and the fields of the object the handler builds.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

GET /v1/mail/suppressions

Addresses Rytiv no longer sends to (bounces, complaints).

Auth: API key with full access or the scope read. An agent token of class production needs prodDataRead for it; sandbox and twin may call it.

Example request

curl -X GET "https://api.rytiv.app/v1/mail/suppressions" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.

DELETE /v1/mail/suppressions/:address

Removes an address from the suppression list.

Path parameters

Name	Description
`address`	The e-mail address.

Example request

curl -X DELETE "https://api.rytiv.app/v1/mail/suppressions/<address>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

204 with no body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.