API documentation

Transactional email API for your application

RelyPost is a transactional email REST API for applications sending order confirmations, password resets, receipts and other service notifications from their own verified domains. API v1 supports plain text and HTML, inline images, file attachments, scheduled sending, message status, domain inspection and signed webhooks. Use it from any language that can make HTTPS requests.

Start with the quickstart, then use the full endpoint reference below. Download the Markdown guide for offline reading or import the OpenAPI specification into compatible API tools. See plans and pricing and your workspace Billing settings for allowances.

1. Set up your account

Everyone can read this guide, including organization members. An organization owner or administrator creates API keys and manages sending domains. If you are a member, ask your administrator to set up the integration and store its key on your application server.

1. Enable Email API service. Ask RelyPost support or your platform administrator to activate API access for your organization. Review the Email API plan in Developer → Billing. Creating a key alone does not activate the API.
2. Connect a sending domain. Open Developer → Domains and choose an existing verified, active domain, or add a domain and complete its DNS setup and verification.
3. Create an Email API sender. In Developer → Mailboxes, add an API sender such as hello@your-domain.com. Creating the sender enables the domain for Email API within your plan limits. Existing domains do not need to be added or verified again. Wait until the sender is active. A regular employee or shared mailbox cannot be used as an API sender.
4. Create a scoped key. Open Developer → API keys and select emails:send and emails:read for this quickstart. Copy the key when it appears; it is shown only once.

2. Send your first email

Replace the sender with your active API sender and the recipient with your test address. Set RELYPOST_API_KEY in your server environment or secret manager. These examples read that variable; do not paste a real key into this page.

For each new application event, choose a stable, unique Idempotency-Key, such as an order confirmation ID. If a request times out, retry its exact body with the same key.

curl --fail-with-body 'https://api.relypost.com/v1/emails' \
  -H "Authorization: Bearer $RELYPOST_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-123-confirmation' \
  --data '{
  "from": "hello@your-domain.com",
  "to": [
    "customer@example.com"
  ],
  "subject": "Your order confirmation",
  "text": "Thank you for your order."
}'

Successful response · HTTP 202

{
  "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
  "state": "queued",
  "revision": 1,
  "scheduled_at": "2026-09-14T12:00:00.000Z"
}

The UUID in id identifies this message. Save it in your application. 202 and queued mean the request was saved for sending; they do not mean the recipient received the email. Dates and IDs shown here are illustrative.

Send HTML email and inline images

Set html to your rendered HTML string and text to a useful plain-text alternative. RelyPost passes these bodies to the email transport. There is no template rendering endpoint or automatic CSS inlining service. Use email-compatible HTML, inline styles and meaningful image alt text; escape untrusted values before inserting them into a template.

For a hosted image, use an absolute HTTPS URL. For an attached image, upload and finalize the image first, then set its cid and reference exactly that value with cid: in the HTML. The example file ID below is a placeholder; replace it with your ready image ID. Test the rendered email in the mail clients your recipients use.

{
  "from": "hello@your-domain.com",
  "to": [
    "customer@example.com"
  ],
  "subject": "Your order confirmation",
  "text": "Thank you for your order.",
  "html": "<!doctype html><html lang=\"en\"><body><h1>Thank you for your order</h1><p>Your order <strong>#123</strong> is confirmed.</p><p><a href=\"https://your-app.com/orders/123\">View your order</a></p></body></html>"
}

{
  "from": "hello@your-domain.com",
  "to": [
    "customer@example.com"
  ],
  "subject": "Your order confirmation",
  "text": "Thank you for your order.",
  "html": "<h1>Order confirmed</h1><img src=\"cid:company-logo\" width=\"160\" alt=\"Company logo\"><p>Thank you for your order.</p>",
  "attachments": [
    {
      "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
      "cid": "company-logo"
    }
  ]
}

Schedule email and preserve threading

Add scheduled_at as an ISO 8601 UTC timestamp ending in Z, no more than 365 days in the future. Omit it to queue immediately. A past timestamp is eligible for immediate processing. A schedule is the earliest sending time; queues, quotas and delivery retries can delay it. There is no public endpoint to cancel or modify an accepted email.

Generate a future timestamp once and persist the entire request with its Idempotency-Key. Do not recompute scheduled_at on a retry: a changed payload conflicts with the original key. Uploads have a staging lifetime, so prepare attachments close to the sending time rather than assuming they remain available for a distant schedule.

For a reply, set in_reply_to to the original RFC Message-ID and references to the prior Message-ID chain. These values use angle brackets, such as <original@your-domain.com>; they are different from RelyPost’s message UUID. Set reply_to to an email address for responses. priority is high, normal or low; it is not a delivery-speed guarantee. tags, metadata and X- headers let you associate messages with application context; they do not create search or filtering endpoints.

// Node.js 18+. Generate once; persist payload and key before the first attempt.
const payload = {
  ...{
  "from": "hello@your-domain.com",
  "to": [
    "customer@example.com"
  ],
  "subject": "Your order confirmation",
  "text": "Thank you for your order."
},
  scheduled_at: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
};
const idempotencyKey = 'order-123-followup';
// Reuse these exact values for every retry of this application event.
const response = await fetch('https://api.relypost.com/v1/emails', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RELYPOST_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify(payload),
});
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result.error));
console.log(result.id, result.scheduled_at);

Response conventions and integration limits

The public base URL ends in /v1. All 12 operations require a Bearer API key and return JSON. Paths below are relative to that base; UUID path values identify resources inside the key’s organization. Send application/json for request bodies. No list operation accepts a documented pagination, search or filter parameter; webhook delivery history returns at most 100 records.

Unknown top-level email fields are rejected. Omitted optional fields receive the defaults shown in OpenAPI; null is not an omission. API email addresses are lowercased by validation. Responses can contain null for timestamps or diagnostics that are not yet available. Treat new response fields and unknown event types as forward-compatible additions.

Success responses include X-Request-Id. Errors use error.code, error.message and error.requestId; validation errors may also include error.fields entries with path and message. Keep the request ID for support. Never log your API key, SMTP app password, webhook secret or signed upload URL.

Request JSON is limited to 1,500,000 bytes. Default combined recipients: 20; each address array has a schema maximum of 100. Default complete MIME message limit: 25 MiB, including headers and attachment encoding. Default upload limit: 100 MiB, which does not mean a 100 MiB file fits in an email. Other limits depend on the deployment and plan. Upload sessions last one hour; API attachment staging defaults to 24 hours.

Sending quotas count recipients at admission, including cc and bcc. Dispatch rate limits can keep accepted messages queued. There is no public endpoint for querying remaining quota or a promise of rate-limit headers. See Developer → Billing. Message status is available only within your plan’s log-retention window.

For timeouts or temporary failures, retry the identical payload with the same organization-scoped Idempotency-Key and exponential backoff with jitter. Reusing a key with changed content returns 409 idempotency_conflict. Use a new key for each new application event. Do not treat idempotency as a permanent archive after data retention; store your own business-event/message mapping.

3. Track delivery

Use the returned message UUID with a key that has emails:read. Replace the example UUID below with your actual message ID.

curl --fail-with-body 'https://api.relypost.com/v1/emails/a19f458e-a915-4aac-8ea1-8c859b41d934' \
  -H "Authorization: Bearer $RELYPOST_API_KEY"

Read state, recipients, recipient_retry, and events. Recipient entries include SMTP status, the remote response and observation time. Use webhooks for ongoing updates instead of polling continuously. Administrators can also open Developer → Delivery logs.

Authentication & scopes

All endpoints below use the base URL https://api.relypost.com/v1 and an Authorization: Bearer rp_live_… header. JSON request bodies require Content-Type: application/json. UUID placeholders in paths must be replaced with real IDs.

Grant only the scopes your app uses. Keys belong to one organization; resources from another organization are not accessible. The key creator must remain a verified owner or administrator. If a key is exposed or its creator leaves, replace it and revoke the old key in Developer → API keys.

This is a server-to-server API. A workspace session cookie, login password or SMTP password is not a Bearer API key. Keep user-facing apps behind your own backend.

Endpoint reference

Paths are relative to https://api.relypost.com/v1. JSON examples use placeholder data. Expand an endpoint to see its request and response.

12 endpoints

{
  "from": "hello@your-domain.com",
  "to": [
    "customer@example.com"
  ],
  "subject": "Your order confirmation",
  "text": "Thank you for your order."
}

{
  "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
  "state": "queued",
  "revision": 1,
  "scheduled_at": "2026-09-14T12:00:00.000Z"
}

{
  "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
  "state": "submitted",
  "message_id": "<message@mail01.relypost.com>",
  "created_at": "2026-09-14T12:00:00.000Z",
  "scheduled_at": "2026-09-14T12:00:00.000Z",
  "submitted_at": "2026-09-14T12:00:01.000Z",
  "smtp_code": "250",
  "diagnostic": "Accepted by submission server",
  "recipients": [
    {
      "address": "customer@example.com",
      "kind": "to",
      "state": "accepted",
      "enhanced_status": "2.0.0",
      "remote_response": "status=sent (250 accepted)",
      "observed_at": "2026-09-14T12:00:02.000Z"
    }
  ],
  "recipient_retry": null,
  "events": [
    {
      "type": "email.queued",
      "created_at": "2026-09-14T12:00:00.000Z",
      "details": {}
    }
  ]
}

[
  {
    "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
    "name": "your-domain.com",
    "status": "active",
    "verified_at": "2026-09-14T10:00:00.000Z"
  }
]

{
  "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
  "name": "your-domain.com",
  "status": "active",
  "verified_at": "2026-09-14T10:00:00.000Z",
  "dkim_selector": "dkim",
  "dkim_txt": "v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY",
  "dns_state": []
}

{
  "name": "receipt.pdf",
  "size": 12345,
  "type": "application/pdf",
  "multipart": false
}

{
  "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
  "sessionId": "94f3e2c8-ff6e-45cf-90ef-8b037111ae64",
  "multipart": false,
  "url": "https://your-signed-storage-url.example",
  "fields": {
    "key": "temporary/…",
    "policy": "…",
    "x-amz-signature": "…"
  }
}

{
  "part": 1
}

{
  "url": "https://your-signed-storage-url.example/part"
}

{
  "parts": []
}

{
  "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
  "state": "ready"
}

[
  {
    "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
    "url": "https://your-app.com/webhooks/relypost",
    "enabled": true,
    "failures": 0,
    "created_at": "2026-09-14T12:00:00.000Z"
  }
]

{
  "url": "https://your-app.com/webhooks/relypost"
}

{
  "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
  "secret": "SAVE_THE_ONE_TIME_SECRET"
}

{
  "enabled": true
}

{
  "ok": true
}

[
  {
    "id": "94f3e2c8-ff6e-45cf-90ef-8b037111ae64",
    "event_id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
    "state": "pending",
    "attempts": 0,
    "last_status": null,
    "next_attempt_at": "2026-09-14T12:00:00.000Z"
  }
]

{
  "deliveryId": "94f3e2c8-ff6e-45cf-90ef-8b037111ae64"
}

{
  "ok": true
}

The public API does not provide mailbox reading, message listing, domain creation, email cancellation, or marketing campaigns. Manage mailboxes and domains in the workspace. Do not integrate against the workspace’s internal /api/org/… session routes.

Email request fields

POST /emails accepts the fields below. Unknown fields are rejected. Email addresses are plain strings, not name/address objects.

Send attachments

Use a key with attachments:write to upload and emails:send to send. Uploading alone does not make a file ready: finalize it successfully before referencing its ID.

1. Reserve a file with POST /attachments, providing its name, byte size, MIME type, and multipart:false.
2. Send every returned field, followed by the file, as multipart form data to the returned signed storage URL. Do not send your API key to storage.
3. Call POST /attachments/{sessionId}/finalize with {"parts":[]}. Scanning and validation must return state:ready.
4. Add "attachments":[{"id":"the-finalized-file-UUID"}] to a new email request.

// Node.js 20+; upload a file, finalize it, then attach its ID.
import { readFile } from 'node:fs/promises';
const file = await readFile('./receipt.pdf');
async function api(path, body) {
  const response = await fetch('https://api.relypost.com/v1' + path, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.RELYPOST_API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(JSON.stringify(result));
  return result;
}
const upload = await api('/attachments', {
  name: 'receipt.pdf', size: file.length, type: 'application/pdf', multipart: false,
});
const form = new FormData();
for (const [key, value] of Object.entries(upload.fields)) form.append(key, String(value));
form.append('file', new Blob([file], { type: 'application/pdf' }), 'receipt.pdf');
// Do not send your API key or set Content-Type on this storage request.
const stored = await fetch(upload.url, { method: 'POST', body: form });
if (!stored.ok) throw new Error('File upload failed: ' + stored.status);
const ready = await api('/attachments/' + upload.sessionId + '/finalize', { parts: [] });
if (ready.state !== 'ready') throw new Error('Attachment is not ready');
console.log(ready.id);
// Add attachments: [{ id: ready.id }] to your POST /emails payload.
// Use a new Idempotency-Key for this new message.

Large files and multipart uploads

Reserve with multipart:true. The response gives id, sessionId, partSize (5,242,880 bytes) and parts. Request a signed URL for each 1-based part with {"part":1}, PUT that part’s bytes, and retain its exact ETag. Finalize with all PartNumber/ETag pairs in ascending order. The last part may be smaller.

Upload sessions expire after one hour. API attachment staging defaults to 24 hours; create attachments close to the send time, especially for scheduled messages. The key creator must still be an organization member. Storage allowance, scanning, and message-size limits apply.

Receive delivery webhooks

Register a public HTTPS URL with POST /webhooks and the webhooks:manage scope. Store the returned secret immediately; listing endpoints will not reveal it again. Endpoints receive organization events; inspect type to decide what to process.

curl --fail-with-body 'https://api.relypost.com/v1/webhooks' \
  -H "Authorization: Bearer $RELYPOST_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://your-app.com/webhooks/relypost"}'

{
  "id": "94f3e2c8-ff6e-45cf-90ef-8b037111ae64",
  "type": "email.recipient_accepted",
  "created_at": "2026-09-14T12:00:02.000Z",
  "data": {
    "id": "a19f458e-a915-4aac-8ea1-8c859b41d934",
    "recipient": "customer@example.com",
    "dsn": "2.0.0",
    "response": "status=sent (250 accepted)",
    "occurred_at": "2026-09-14T12:00:02.000Z"
  }
}

data.id is the email UUID; the top-level id is the event UUID. Common types include email.queued, email.submitted, email.recipient_accepted, email.recipient_deferred, and email.bounced. Handle unknown event types without failing the entire endpoint.

Event data varies by type; recipient and SMTP response fields are not present on every event. Additional organization events may also arrive. Inspect the type before processing the data.

Verify the signature before parsing JSON

Read the headers webhook-id, webhook-timestamp (Unix seconds), and webhook-signature (hex). The signature is HMAC-SHA256 over id.timestamp.rawBody, using your webhook secret. Reject timestamps more than five minutes in the past or future, compare signatures in constant time, and deduplicate webhook-id durably.

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody must be the exact request bytes, before JSON parsing.
// headers is a Headers object; secret is your saved webhook secret.
export function verifyRelyPostWebhook(rawBody, headers, secret, now = Date.now()) {
  const id = headers.get('webhook-id');
  const timestamp = headers.get('webhook-timestamp');
  const signature = headers.get('webhook-signature') ?? '';
  if (!id || !timestamp || !/^\d+$/.test(timestamp)) return false;
  if (!/^[a-f0-9]{64}$/i.test(signature)) return false;
  if (Math.abs(now / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(id + '.' + timestamp + '.')
    .update(rawBody)
    .digest();
  return timingSafeEqual(expected, Buffer.from(signature, 'hex'));
}

// In your webhook handler:
// 1. Read the raw body and verify it; return 401 on failure.
// 2. Parse JSON only after verification.
// 3. Atomically store/enqueue the event using webhook-id as a UNIQUE key.
// 4. Return 2xx after durable acceptance, including for a duplicate.
// 5. Process stored events in your worker; do not send another email here.

Retries may repeat notifications and delivery order is not guaranteed. Return a 2xx response after durable acceptance, including for a duplicate. Respond promptly and process work asynchronously. Failed requests retry with bounded backoff; repeatedly failing endpoints are disabled. Inspect deliveries, fix the handler, enable the endpoint and retry the failed delivery ID. Redirects are not followed.

Retries, scheduling & limits

• Retry the same send safely. Keep the original payload and Idempotency-Key for timeouts or transient server errors. The same key with different input returns 409 idempotency_conflict. A new message requires a new key.
• Respect uncertain outcomes. Read the message status and wait for reconciliation. Creating a fresh send can duplicate a message the SMTP server already accepted.
• Plan for queues. Rate controls, sending capacity and scheduled timestamps can delay an admitted message. Monthly plan usage counts recipients; creating more keys does not bypass organization limits.
• Keep requests bounded. Defaults are 20 combined recipients and 25 MiB per final MIME message, including attachment encoding and overhead. The JSON body limit is 1,500,000 bytes. Individual file uploads default to 100 MiB, but files in an email must fit its smaller MIME limit. Deployment settings may lower or raise configurable limits.
• Retain your own message IDs. Read access to status and events expires with your API plan’s log-retention window. Store events your application needs to retain longer.

Troubleshooting

Check the HTTP status and error.code. Validation errors may include error.fields. Include error.requestId when contacting support; successful responses also include an X-Request-Id header.

{
  "error": {
    "code": "missing_scope",
    "message": "API key requires emails:send",
    "requestId": "a19f458e-a915-4aac-8ea1-8c859b41d934"
  }
}

For service availability, check system status. For an account or delivery issue, email support@relypost.com with your request ID and message UUID. Find requests in Developer → API request logs, including failures before queueing. Accepted emails also appear in Delivery logs. Do not include API keys, passwords or webhook secrets.

Using an app that asks for SMTP?

Open Organization → SMTP settings to get the public host, port, TLS mode, mailbox username and a separate send-only app password. Use those in your website, CRM or email client. A Bearer API key cannot authenticate to SMTP.

Frequently asked questions