Email API

Every MarkRelay deployment includes a focused HTTP API under/openapi/v1. Use it to add email to an application, automation, internal tool, or AI agent without operating SMTP.

Open the interactive reference

• /open/markrelay/docs — interactive Swagger documentation
• /open/markrelay/openapi.json — OpenAPI 3.1 schema

Both are served directly by your MarkRelay deployment.

Create an API key

1. Open Developer → API keys.
2. Give the key a name that identifies the application using it.
3. Choose owner, domain, or selected-mailbox access.
4. Copy the sk-... key and store it securely.

Authorization: Bearer sk-...

Send an email

curl https://mail.your-domain.com/openapi/v1/emails/send \
  -H "Authorization: Bearer $MARKRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Support <support@acme.com>",
    "to": "customer@example.com",
    "subject": "Welcome, {{first_name}}!",
    "markdown": "## Hi {{first_name}}!\n\nThanks for joining us.",
    "variables": { "first_name": "Ada" }
  }'

Choose Markdown, HTML, or plain text for the body. Add CC, BCC, Reply-To, a preheader, variables, and uploaded attachments as needed.

Work with mailboxes

Start with GET /mailboxes to discover the addresses available to the key. Then list a mailbox by folder, search text, sender, subject, date, or read state. Cursor pagination lets applications continue through larger result sets efficiently.

Reply, forward, and organize

• Fetch message detail without changing its read state.
• Reply or forward by email ID while MarkRelay handles conversation headers.
• Mark messages read, star them, or move them between folders with PATCH.
• Delete messages with the DELETE endpoint.

Attachments

Upload files with POST /attachments, then include the returned attachment IDs when sending. Received-email detail also provides IDs that can be downloaded through GET /attachments/{attachmentId}. Upload IDs remain available for 24 hours.

Endpoints

Base URL: https://<your-deployment>/openapi/v1

Build inbound workflows

Pair the API with Inbound webhooks to react as soon as new mail arrives.