Relaytera · Relay API v1

Email infrastructure with an evidence trail.

Use one stable contract for REST or SMTP submission, authenticated sender domains, suppressions, signed events, and a delivery trace your team can inspect. Relay API is not yet for public purchase — a free workspace does not include an API key while public sales stay closed.

Create a free workspace OpenAPI 3.1
Stable, bearer-authenticated `/v1` paths Idempotency-safe message submission Signed webhooks and recipient-level outcomes
HTTPS requestPOST /v1/messages
curl -X POST https://relaytera.com/v1/messages \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: password-reset:user-42:attempt-1" \
  -d '{
    "from": "Support <support@your-verified-domain.com>",
    "to": "customer@example.net",
    "subject": "Reset your password",
    "html": "<p>Use your secure reset link.</p>",
    "correlation_id": "password-reset:user-42",
    "metadata": { "purpose": "password_reset" },
    "traffic_class": "transactional"
  }'
202 accepted{ "id": "email_…", "trace_id": "trace_…", "status": "queued" }
Relay Mail and Relay Hosting are separate products.

This guide documents the outbound Relay email API. Mailbox-only email hosting and cPanel website hosting are separate client-panel products; neither is a public provisioning API resource nor an automatically-created Relay sender domain. Keep each product's mailbox DNS records separate from the sender-domain records shown in Relay. Public purchase of Relay API plans is closed while the sending IP warms.

View product boundary
Build safely

A deliberate path from key to delivery.

Relay derives the authorised workspace from the bearer key. Correlation fields are retained for your systems; they are never used to grant access.

  1. 01

    Create a workspace and scoped key

    Once your workspace has API access, give the application only the permissions it needs. Keep the key server-side and rotate it if it could be exposed.

  2. 02

    Verify a sending domain

    Publish the generated ownership, SPF, DKIM, DMARC, return-path, and bounce records—or connect an authorised Cloudflare zone.

  3. 03

    Send with an idempotency key

    Relay accepts the request durably, returns an email and trace identity, then records the delivery outcome as it changes.

Public contract

The API surface you can build against.

Download OpenAPI
POST
/v1/messages

Accept a transactional or campaign message with a durable trace ID.

GET · POST · DELETE
/v1/suppressions

Synchronize recipient safety and release only an unsubscribe suppression.

GET · POST
/v1/domains

Add, inspect, verify, and safely automate sender-domain DNS.

GET · POST
/v1/api-keys

Issue least-privilege, expiring, rate-limited workspace keys.

GET · POST
/v1/templates · /v1/audiences · /v1/broadcasts

Manage content, consent-aware audiences, and permission-provenance broadcasts.

GET · POST
/v1/webhooks

Configure signed lifecycle-event integrations.

GET
/v1/usage · /v1/analytics

Read enforced limits and delivery analytics.

Compatibility promise. Additive changes may arrive in v1. A breaking change requires a new versioned path and at least 12 months of migration notice. The older dashboard `/api/*` paths remain compatible but are not the long-term customer SDK contract.

SMTP submission

Use Relay behind your existing mail library.

Authenticate with a scoped API key over STARTTLS. Relay applies the same verified-sender, suppression, abuse, rate-limit, and audit controls as the REST endpoint.

Host: smtp.relaytera.com
Port: 587 (STARTTLS)
Username: relay
Password: scoped Relay API key with smtp:send

// The same sender-domain, suppression, rate-limit, and audit policy
// applies to SMTP and POST /v1/messages.
Domains and DNS

Verify once, send from any local-part.

After a domain is verified, your workspace can send from addresses such as `support@yourdomain.com`, `noreply@yourdomain.com`, or `billing@yourdomain.com`. Manual DNS works at every registrar; Cloudflare automation is opt-in and conflict-safe.

  • Publish the exact records Relay shows. Preserve their type, host, value, and MX priority; use DNS-only routing for mail records.
  • Never publish a second SPF or DMARC policy. Resolve an existing-policy conflict before verifying; Relay does not destructively replace customer records.
  • Keep cPanel mail DNS separate. A managed Relay Hosting account has its own account-specific MX, SPF, and DKIM instructions in Hosting; those records do not replace Relay sender-domain records.
  • Keep Relay Mail mailbox DNS separate too. Mailbox MX, SPF, DKIM, and DMARC records for the Relay Mail product are shown in Mail hosting (mailbox.relaytera.com); they are not Relay sender-domain records and the two must not be mixed on one domain.
  • Allow public DNS to propagate, then verify again. This is usually minutes but can take a provider's configured TTL. A verified domain then authorises any local-part.
Create a free workspace
Lifecycle events

Keep your system in sync with delivery.

Webhook payloads carry the Relay email ID, trace ID, workspace ID, caller correlation fields, metadata, and recipient-level statuses. Verify the raw payload before you act on it.

Events to expect

email.queued email.sent email.deferred email.delivered email.bounced email.complained email.suppressed

Verify every delivery

Compute HMAC-SHA256 for {timestamp}.{rawBody} with the endpoint's signing secret and compare it in constant time. Relay retries non-2xx responses with bounded backoff.

Control recipient safety

Bounces, complaints, and unsubscribes become suppressions. API callers can list them and may only release an active unsubscribe suppression.

Engagement tracking

Not a current public Relay feature.

Native open and click tracking is intentionally staged and is not available to public customers. It will remain unavailable until its privacy controls, retention, and release evidence are complete.

Do not integrate against it yet

Do not rely on open or click tracking fields in a production integration. The public contract is the OpenAPI document and the documented delivery lifecycle events.

Future privacy boundary

If released, tracking will require an explicit caller acknowledgement of a lawful basis and recipient notice. It must not be treated as proof that a named recipient acted.

Current alternative

Use signed delivery, bounce, complaint, suppression, and webhook outcomes for the currently documented Relay API lifecycle.

Lifecycle policy

Versioning should be boring.

Relay v1 is the supported customer surface. New non-breaking fields and endpoints are additive. Before a breaking change, Relay publishes a new versioned path, migration guidance, and a minimum 12-month notice period.

Provider-feedback receivers and one-click unsubscribe URLs intentionally use separate per-resource signatures rather than API keys. Treat them as secrets and rotate them from the dashboard when necessary.