Relay REST API

Relay API

Scoped REST API for programmable inbound email inboxes. Create inboxes, read messages, extract authentication artifacts, receive SSE events, and manage signed webhooks.

Version 1.0.0 · Base URL https://www.relaymcp.net/api/v1

Authentication

Create a key in Relay Account settings. Keys are shown once and never stored in plaintext.

Send Authorization: Bearer rl_live_... on every request. Keys are created on /account and shown once.

GET/domains

List available Free mail domains

Auth: Bearer API key with inboxes:read.

200 Available domains. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/domainsrequest.sh

1curl "https://www.relaymcp.net/api/v1/domains" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Try request

Sends a live call to the production API from this page.

API key

Create API key ->

GET/inboxes

List the authenticated account's inboxes

Auth: Bearer API key with inboxes:read.

Parameter	In	Required	Description
`cursor`	query	No	Cursor returned by the previous page.

200 Cursor-paginated inboxes. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/inboxesrequest.sh

1curl "https://www.relaymcp.net/api/v1/inboxes?cursor=CURSOR" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Try request

Sends a live call to the production API from this page.

API keycursor

Create API key ->

POST/inboxes

Create an inbox

Auth: Bearer API key with inboxes:write.

Request body

Optional

{
  "name": "build-checks",
  "domain": "mail.example.net"
}

201 Created inbox. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

503 No active mail domain is available. · application/json

POST/inboxesrequest.sh

1curl -X POST "https://www.relaymcp.net/api/v1/inboxes" \2  -H "Authorization: Bearer $RELAY_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"name":"build-checks","domain":"mail.example.net"}'

Try request

Sends a live call to the production API from this page.

API keyJSON body

Create API key ->

GET/inboxes/{inboxId}

Get inbox metadata

Auth: Bearer API key with inboxes:read.

Parameter	In	Required	Description
`inboxId`	path	Yes	Inbox ID.

200 Inbox metadata. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/inboxes/{inboxId}request.sh

1curl "https://www.relaymcp.net/api/v1/inboxes/INBOX_ID" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Try request

Sends a live call to the production API from this page.

API keyinboxId

Create API key ->

GET/inboxes/{inboxId}/attachments/{attachmentId}

Download an attachment

Auth: Bearer API key with messages:read.

Parameter	In	Required	Description
`inboxId`	path	Yes	Inbox ID.
`attachmentId`	path	Yes	Attachment ID.

200 Binary attachment. · application/octet-stream

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/inboxes/{inboxId}/attachments/{attachmentId}request.sh

1curl "https://www.relaymcp.net/api/v1/inboxes/INBOX_ID/attachments/ATTACHMENT_ID" \2  -H "Authorization: Bearer $RELAY_API_KEY" \3  -o "attachment.bin"

Use the sample request for streaming or binary responses in your terminal or HTTP client.

GET/inboxes/{inboxId}/messages

List message previews

Auth: Bearer API key with messages:read.

Parameter	In	Required	Description
`inboxId`	path	Yes	Inbox ID.
`limit`	query	No	Number of messages to return.
`cursor`	query	No	Cursor returned by the previous page.

200 Message preview page. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/inboxes/{inboxId}/messagesrequest.sh

1curl "https://www.relaymcp.net/api/v1/inboxes/INBOX_ID/messages?limit=30&cursor=CURSOR" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Try request

Sends a live call to the production API from this page.

API keyinboxIdlimitcursor

Create API key ->

GET/inboxes/{inboxId}/messages/{messageId}

Read a full message

Auth: Bearer API key with messages:read.

Parameter	In	Required	Description
`inboxId`	path	Yes	Inbox ID.
`messageId`	path	Yes	Message ID.

200 Full message with sanitized HTML and attachment metadata. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/inboxes/{inboxId}/messages/{messageId}request.sh

1curl "https://www.relaymcp.net/api/v1/inboxes/INBOX_ID/messages/MESSAGE_ID" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Try request

Sends a live call to the production API from this page.

API keyinboxIdmessageId

Create API key ->

GET/inboxes/{inboxId}/messages/{messageId}/auth

Extract OTP and authentication links

Auth: Bearer API key with messages:read.

Parameter	In	Required	Description
`inboxId`	path	Yes	Inbox ID.
`messageId`	path	Yes	Message ID.

200 Authentication artifact extraction result. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/inboxes/{inboxId}/messages/{messageId}/authrequest.sh

1curl "https://www.relaymcp.net/api/v1/inboxes/INBOX_ID/messages/MESSAGE_ID/auth" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Try request

Sends a live call to the production API from this page.

API keyinboxIdmessageId

Create API key ->

GET/inboxes/{inboxId}/messages/{messageId}/otp

Extract a one-time password

Auth: Bearer API key with messages:read.

Parameter	In	Required	Description
`inboxId`	path	Yes	Inbox ID.
`messageId`	path	Yes	Message ID.

200 OTP extraction result. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/inboxes/{inboxId}/messages/{messageId}/otprequest.sh

1curl "https://www.relaymcp.net/api/v1/inboxes/INBOX_ID/messages/MESSAGE_ID/otp" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Try request

Sends a live call to the production API from this page.

API keyinboxIdmessageId

Create API key ->

GET/events

Stream account events over SSE

Connections last up to ten minutes and poll at five-second intervals while the client consumes events. Keys and scopes are revalidated per poll. At most three streams per account are allowed in each server process. Resume after disconnection using the last numeric event ID.

Auth: Bearer API key with events:read.

Parameter	In	Required	Description
`after`	query	No	Last event ID already received.
`limit`	query	No	Upper bound per poll; responses may contain fewer events to respect server byte and batch limits.

200 text/event-stream containing typed events and heartbeat events. · text/event-stream

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/eventsrequest.sh

1curl "https://www.relaymcp.net/api/v1/events?after=0&limit=100" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Use the sample request for streaming or binary responses in your terminal or HTTP client.

GET/webhooks

List webhook endpoints

Auth: Bearer API key with webhooks:read.

200 Webhook endpoints. The signing secret is never returned after creation. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/webhooksrequest.sh

1curl "https://www.relaymcp.net/api/v1/webhooks" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Try request

Sends a live call to the production API from this page.

API key

Create API key ->

POST/webhooks

Create a signed webhook endpoint

Auth: Bearer API key with webhooks:write.

Request body

Required

{
  "url": "https://hooks.example.com/relay",
  "events": [
    "inbox.message.received"
  ]
}

201 Created webhook. Save the one-time secret. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

POST/webhooksrequest.sh

1curl -X POST "https://www.relaymcp.net/api/v1/webhooks" \2  -H "Authorization: Bearer $RELAY_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"url":"https://hooks.example.com/relay","events":["inbox.message.received"]}'

Try request

Sends a live call to the production API from this page.

API keyJSON body

Create API key ->

DELETE/webhooks/{webhookId}

Delete a webhook endpoint

Auth: Bearer API key with webhooks:write.

Parameter	In	Required	Description
`webhookId`	path	Yes	Webhook ID.

200 Webhook deleted. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

DELETE/webhooks/{webhookId}request.sh

1curl -X DELETE "https://www.relaymcp.net/api/v1/webhooks/WEBHOOK_ID" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Try request

Sends a live call to the production API from this page.

API keywebhookId

Create API key ->

GET/webhooks/{webhookId}

List webhook delivery history

Auth: Bearer API key with webhooks:read.

Parameter	In	Required	Description
`webhookId`	path	Yes	Webhook ID.

200 Recent deliveries. · application/json

400 Invalid request. · application/json

401 Missing, invalid, revoked, or expired API key. · application/json

403 The API key does not have the required scope or access. · application/json

404 Resource not found. · application/json

409 The requested resource conflicts with an existing resource. · application/json

429 Rate limit exceeded. · application/json

GET/webhooks/{webhookId}request.sh

1curl "https://www.relaymcp.net/api/v1/webhooks/WEBHOOK_ID" \2  -H "Authorization: Bearer $RELAY_API_KEY"

Try request

Sends a live call to the production API from this page.

API keywebhookId

Create API key ->

Schemas

Component schemas from the OpenAPI document.

`Error`

ErrorError.json

1{2  "error": "string",3  "code": "string"4}

`Domain`

DomainDomain.json

1{2  "id": "string",3  "name": "string",4  "tier": "free"5}

`Inbox`

InboxInbox.json

1{2  "id": "string",3  "address": "string",4  "owned": true5}

`CreateInboxRequest`

CreateInboxRequestCreateInboxRequest.json

1{2  "name": "string",3  "domain": "string"4}

`InboxPage`

InboxPageInboxPage.json

1{2  "inboxes": [3    {4      "id": "string",5      "address": "string",6      "owned": true7    }8  ],9  "nextCursor": null10}

`MessagePreview`

MessagePreviewMessagePreview.json

1{2  "id": "string",3  "sender": null,4  "sender_address": null,5  "subject": null,6  "preview": null,7  "created": 0,8  "time": "2026-01-01T00:00:00.000Z",9  "size_bytes": 0,10  "source": null,11  "attachment_count": 012}

`Message`

MessageMessage.json

1{2  "id": "string",3  "sender": null,4  "sender_address": null,5  "subject": null,6  "preview": null,7  "created": 0,8  "time": "2026-01-01T00:00:00.000Z",9  "size_bytes": 0,10  "source": null,11  "attachment_count": 0,12  "recipient": null,13  "body": null,14  "html": null,15  "message_id": null,16  "attachments": [17    {18      "id": null,19      "filename": null,20      "content_type": null,21      "size_bytes": null,22      "sha256": null23    }24  ]25}

`MessagePage`

MessagePageMessagePage.json

1{2  "messages": [3    {4      "id": "string",5      "sender": null,6      "sender_address": null,7      "subject": null,8      "preview": null,9      "created": 0,10      "time": "2026-01-01T00:00:00.000Z",11      "size_bytes": 0,12      "source": null,13      "attachment_count": 014    }15  ],16  "nextCursor": null17}

`Attachment`

AttachmentAttachment.json

1{2  "id": "string",3  "filename": "string",4  "content_type": "string",5  "size_bytes": 0,6  "sha256": "string"7}

`OtpResult`

OtpResultOtpResult.json

1{2  "found": true,3  "ambiguous": true,4  "code": null,5  "confidence": "none"6}

`AuthArtifacts`

AuthArtifactsAuthArtifacts.json

1{2  "otp": {3    "found": true,4    "ambiguous": true,5    "code": null,6    "confidence": "none"7  },8  "links": [9    "string"10  ],11  "magicLink": null12}

`CreateWebhookRequest`

CreateWebhookRequestCreateWebhookRequest.json

1{2  "url": "string",3  "events": [4    "string"5  ]6}

`Webhook`

WebhookWebhook.json

1{2  "id": "string",3  "url": "string",4  "events": [5    "string"6  ],7  "active": true,8  "created": 0,9  "updated": 010}

`CreatedWebhook`

CreatedWebhookCreatedWebhook.json

1{2  "id": "string",3  "url": "string",4  "events": [5    "string"6  ],7  "active": true,8  "created": 0,9  "updated": 0,10  "secret": "string"11}

`WebhookDelivery`

WebhookDeliveryWebhookDelivery.json

1{2  "id": "string",3  "endpoint_id": "string",4  "event_id": 0,5  "attempt": 0,6  "state": "string",7  "next_attempt": null,8  "response_status": null,9  "last_error": null,10  "created": 0,11  "delivered": null12}

Relay API

Authentication

List available Free mail domains

Try request

List the authenticated account's inboxes

Try request

Create an inbox

Request body

Try request

Get inbox metadata

Try request

Download an attachment

List message previews

Try request

Read a full message

Try request

Extract OTP and authentication links

Try request

Extract a one-time password

Try request

Stream account events over SSE

List webhook endpoints

Try request

Create a signed webhook endpoint

Request body

Try request

Delete a webhook endpoint

Try request

List webhook delivery history

Try request

Schemas

Error

Domain

Inbox

CreateInboxRequest

InboxPage

MessagePreview

Message

MessagePage

Attachment

OtpResult

AuthArtifacts

CreateWebhookRequest

Webhook

CreatedWebhook

WebhookDelivery

Implementation guides and deeper context

`Error`

`Domain`

`Inbox`

`CreateInboxRequest`

`InboxPage`

`MessagePreview`

`Message`

`MessagePage`

`Attachment`

`OtpResult`

`AuthArtifacts`

`CreateWebhookRequest`

`Webhook`

`CreatedWebhook`

`WebhookDelivery`