Mail Platform - urBackend

Overview

urBackend Mail Platform extends transactional sending into a full delivery workflow with:

async queue-backed single sending (/api/mail/send), with optional replyTo
direct provider batch sending (/api/mail/send-batch, 1..100 items, per-item replyTo)
BYOK (Bring Your Own Key) with encrypted project-level Resend keys
delivery tracking via persistent MailLog
audience/contact management (BYOK-gated)
marketing broadcasts (BYOK-gated, counted against the monthly mail quota)
webhook-driven status updates with Svix verification

Implementation references:

How Mail Platform fits urBackend

Public API (/api/mail/*): app/runtime sending, logs, live status, webhook receiver.
Dashboard API (/api/projects/:projectId/mail/*): operator/admin workflows (logs, live checks, audiences, contacts, broadcasts).
Dashboard UI (/project/:projectId/mail): unified Mail Platform control plane.

Architecture

Feature gating matrix

Capability	Free (shared key)	Free + BYOK	Pro + BYOK
Monthly mail quota	50	50	1,000
Transactional send (`/api/mail/send`)	✅	✅	✅
Batch send (`/api/mail/send-batch`, max 100 items)	✅	✅	✅
Custom mail templates (`templateId` / `templateName`)	✅	✅	✅
Delivery logs + live status	✅	✅	✅
Audiences & Contacts	❌	✅	✅
Marketing Broadcasts	❌	✅ (within 50/mo limit)	✅ (within 1,000/mo limit)

BYOK is available on every plan, including Free. Audiences, contacts, and broadcasts only require a configured BYOK Resend key. They do not require a Pro plan.

Getting started

Prerequisites

Resend account
Valid Resend key with format: re_[A-Za-z0-9_]+
urBackend project with a Secret Key (sk_live_...) for public API calls

Configure BYOK in Dashboard

Open Project Settings for your project.
Set resendApiKey with your Resend key (re_...).
Optionally set resendFromEmail.
Save. urBackend stores this key encrypted at rest.

Required server environment

Variable	Required	Purpose
`RESEND_API_KEY`	✅ (fallback)	Default/shared provider key
`RESEND_API_KEY_2`	Optional	Higher-priority fallback key
`RESEND_WEBHOOK_SECRET`	✅ for webhook verification	Svix secret for `/api/mail/webhook`
`EMAIL_FROM`	✅ recommended	Default sender fallback

Register webhook in Resend

In Resend dashboard, configure webhook URL: POST https://<your-public-api-domain>/api/mail/webhook Enable relevant events at minimum:

email.sent
email.delivered
email.bounced
email.complained

Sending emails

All /api/mail/* send endpoints require your Secret Key (sk_live_...) in x-api-key.

POST `/api/mail/send` (single)

Request schema

Field	Type	Required	Notes
`to`	`string \| string[]`	✅	recipient email(s); array form must have at least one entry
`replyTo`	`string \| string[]`	Optional	reply-to address(es); forwarded to Resend as the `Reply-To` header
`subject`	`string`	Direct mode ✅	required when not using template fields
`html`	`string`	Direct mode one of `html/text`	HTML body
`text`	`string`	Direct mode one of `html/text`	Text body
`templateId`	`string`	Template mode one of `templateId/templateName`	24-char ObjectId
`templateName`	`string`	Template mode one of `templateId/templateName`	key/name lookup
`variables`	`object`	Optional	template vars

Validation notes:

to and replyTo must be valid email addresses. Array forms cannot be empty (Recipient list cannot be empty, Reply-to list cannot be empty).
Subject must be non-empty after any template/variable interpolation (Subject is required).
Rendered body must contain a non-empty html or text value; requests where both are empty after interpolation are rejected (Provide at least one of html or text content.).

Quota and limits

per-request monthly quota slot is reserved in Redis
on terminal failure, slot is refunded
over-limit returns HTTP 429

Example

curl -X POST "https://api.urbackend.in/api/mail/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY" \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome",
    "html": "<h1>Hello</h1>"
  }'

import { UrBackendClient } from 'urbackend-sdk';

const client = new UrBackendClient({ apiKey: process.env.URB_SECRET_KEY! });
const result = await client.mail.send({
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<h1>Hello</h1>'
});
console.log(result.id, result.provider);

Success envelope

{
  "success": true,
  "data": {
    "id": "<queue-job-id>",
    "provider": "byok",
    "monthlyUsage": 12,
    "monthlyLimit": 100
  },
  "message": "Mail queued successfully."
}

POST `/api/mail/send-batch` (max 100)

Request schema

Array of 1..100 items:

[
  {
    "to": "u1@example.com",
    "replyTo": "support@acme.com",
    "subject": "Campaign",
    "html": "<p>Hello</p>"
  }
]

Each item supports:

Field	Type	Required	Notes
`to`	`string \| string[]`	✅	recipient email(s); array form must have at least one entry
`replyTo`	`string \| string[]`	Optional	reply-to address(es); array form must have at least one entry
`subject`	`string`	✅	non-empty after trimming
`html`	`string`	one of `html/text` ✅	HTML body
`text`	`string`	one of `html/text` ✅	Text body

Validation is enforced by a strict Zod schema on every batch call:

The batch array itself must contain 1..100 items. Empty batches are rejected with Batch cannot be empty; larger batches are rejected with Max 100 emails per batch.
Each to and replyTo value is validated as a proper email address.
Each item must supply a non-empty subject (Subject is required).
Each item must supply at least one of html or text (Provide html or text).
Templates (templateId / templateName / variables) are not supported in batch mode. Batch items always go directly to Resend with the exact subject / html / text you provide.

Quota behavior

reserves one quota slot per batch item before provider call
if provider call fails, each reserved slot is refunded
response includes per-item provider result objects

Partial success

data returns per-recipient/provider results. Treat each item independently in your caller logic.

Example

curl -X POST "https://api.urbackend.in/api/mail/send-batch" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY" \
  -d '[
    {"to":"a@example.com","replyTo":"support@acme.com","subject":"Hi A","html":"<p>A</p>"},
    {"to":"b@example.com","subject":"Hi B","text":"Hello B"}
  ]'

import { UrBackendClient } from 'urbackend-sdk';

const client = new UrBackendClient({ apiKey: process.env.URB_SECRET_KEY! });
const result = await client.request('POST', '/api/mail/send-batch', {
  body: [
    { to: 'a@example.com', replyTo: 'support@acme.com', subject: 'Hi A', html: '<p>A</p>' },
    { to: 'b@example.com', subject: 'Hi B', text: 'Hello B' }
  ]
});
console.log(result);

Mail logs

GET `/api/mail/logs` (public) and GET `/api/projects/:projectId/mail/logs` (dashboard)

`MailLog` fields

resendEmailId
to
subject
status
usingByok
templateUsed
sentAt

current implementation returns latest 50, sorted by sentAt DESC

curl "https://api.urbackend.in/api/mail/logs" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

const logs = await client.request('GET', '/api/mail/logs');
console.log(logs);

Dashboard API variant (bearer auth):

curl "https://platform-api.urbackend.in/api/projects/<projectId>/mail/logs" \
  -H "Authorization: Bearer <dashboard-jwt>"

Live status

Public: GET /api/mail/logs/:resendId
Dashboard: GET /api/projects/:projectId/mail/logs/:resendId/live

Use live status when you need real-time provider status. Use stored logs for analytics/history and low-latency UI lists.

404 if log entry does not belong to the current project (cross-project isolation)

curl "https://api.urbackend.in/api/mail/logs/re_123" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

const status = await client.request('GET', '/api/mail/logs/re_123');
console.log(status.dbLog, status.resendStatus);

Dashboard API live check:

curl "https://platform-api.urbackend.in/api/projects/<projectId>/mail/logs/re_123/live" \
  -H "Authorization: Bearer <dashboard-jwt>"

Audiences & Contacts (BYOK-gated)

These endpoints proxy Resend API and require a valid BYOK key on the project. Error status/message semantics follow upstream Resend responses where applicable.

Audiences endpoints

GET /api/mail/audiences
POST /api/mail/audiences body: { "name": "VIP Customers" }
DELETE /api/mail/audiences/:audienceId

curl "https://api.urbackend.in/api/mail/audiences" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

curl -X POST "https://api.urbackend.in/api/mail/audiences" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY" \
  -d '{"name":"VIP Customers"}'

curl -X DELETE "https://api.urbackend.in/api/mail/audiences/aud_123" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

await client.request('GET', '/api/mail/audiences');
await client.request('POST', '/api/mail/audiences', { body: { name: 'VIP Customers' } });
await client.request('DELETE', '/api/mail/audiences/aud_123');

Contacts endpoints

GET /api/mail/audiences/:audienceId/contacts
POST /api/mail/audiences/:audienceId/contacts
PATCH /api/mail/audiences/:audienceId/contacts/:contactId
DELETE /api/mail/audiences/:audienceId/contacts/:contactId

Contact payload fields: email, firstName, lastName, unsubscribed

curl -X POST "https://api.urbackend.in/api/mail/audiences/aud_123/contacts" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY" \
  -d '{
    "email": "contact@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "unsubscribed": false
  }'

const contact = await client.request('POST', '/api/mail/audiences/aud_123/contacts', {
  body: {
    email: 'contact@example.com',
    firstName: 'Ada',
    lastName: 'Lovelace',
    unsubscribed: false
  }
});
console.log(contact);

For the remaining contact endpoints:

curl "https://api.urbackend.in/api/mail/audiences/aud_123/contacts" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

curl -X PATCH "https://api.urbackend.in/api/mail/audiences/aud_123/contacts/ct_123" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY" \
  -d '{"firstName":"Ada","unsubscribed":true}'

curl -X DELETE "https://api.urbackend.in/api/mail/audiences/aud_123/contacts/ct_123" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

await client.request('GET', '/api/mail/audiences/aud_123/contacts');
await client.request('PATCH', '/api/mail/audiences/aud_123/contacts/ct_123', {
  body: { firstName: 'Ada', unsubscribed: true }
});
await client.request('DELETE', '/api/mail/audiences/aud_123/contacts/ct_123');

Marketing broadcasts (BYOK)

Endpoints:

POST /api/mail/broadcasts
POST /api/mail/broadcasts/:id/send
GET /api/mail/broadcasts
GET /api/mail/broadcasts/:id
DELETE /api/mail/broadcasts/:id

Two-step flow

Create broadcast (draft/scheduled payload)
Send broadcast by id

`from` resolution order

from from request body
project.resendFromEmail
EMAIL_FROM env fallback

Quota checks

Broadcasts require a configured BYOK Resend key on the project. They are available on both the Free and Pro plans. Each broadcast send reserves one slot from the project’s shared monthly mail quota (50 on Free, 1,000 on Pro), the same quota used by transactional sends. If Resend rejects the send, urBackend refunds the reserved slot so failed sends do not count against your quota.

# 1) Create
curl -X POST "https://api.urbackend.in/api/mail/broadcasts" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY" \
  -d '{
    "audienceId": "aud_123",
    "subject": "May launch",
    "html": "<h1>We shipped</h1>",
    "scheduledAt": "2026-05-20T10:00:00.000Z"
  }'

# 2) Send
curl -X POST "https://api.urbackend.in/api/mail/broadcasts/brd_123/send" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

const created = await client.request('POST', '/api/mail/broadcasts', {
  body: {
    audienceId: 'aud_123',
    subject: 'May launch',
    html: '<h1>We shipped</h1>'
  }
});

await client.request('POST', `/api/mail/broadcasts/${created.id}/send`);

Other broadcast endpoints:

curl "https://api.urbackend.in/api/mail/broadcasts" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

curl "https://api.urbackend.in/api/mail/broadcasts/brd_123" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

curl -X DELETE "https://api.urbackend.in/api/mail/broadcasts/brd_123" \
  -H "x-api-key: sk_live_YOUR_SECRET_KEY"

await client.request('GET', '/api/mail/broadcasts');
await client.request('GET', '/api/mail/broadcasts/brd_123');
await client.request('DELETE', '/api/mail/broadcasts/brd_123');

Webhook integration

Endpoint: POST /api/mail/webhook

Why raw-body parsing is required

Svix signatures are computed over raw payload bytes. express.raw({ type: 'application/json' }) must run before JSON parser on this path.

Secret configuration

Set RESEND_WEBHOOK_SECRET in server env. Webhook signature verification and event processing only occur when this secret is configured correctly.

Current behavior when missing/misconfigured: the handler returns HTTP 200 with {"success":true,"message":"Webhook ignored: secret not configured."} and skips verification/processing.

Event mapping to `MailLog.status`

Resend event type	MailLog status
`email.sent`	`sent`
`email.delivered`	`delivered`
`email.bounced`	`bounced`
`email.complained`	`complained`
`email.delivery_delayed`	`queued`

email.sent represents provider acceptance (intermediate state), not final inbox delivery.

Retry behavior

Resend controls webhook retries for non-2xx/timeout outcomes. Keep endpoint idempotent and safe for repeated delivery attempts.

curl -X POST "https://api.urbackend.in/api/mail/webhook" \
  -H "Content-Type: application/json" \
  -H "svix-id: <id>" \
  -H "svix-timestamp: <timestamp>" \
  -H "svix-signature: <signature>" \
  -d '{"type":"email.delivered","data":{"email_id":"re_123"}}'

await fetch('https://api.urbackend.in/api/mail/webhook', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'svix-id': '<id>',
    'svix-timestamp': '<timestamp>',
    'svix-signature': '<signature>'
  },
  body: JSON.stringify({
    type: 'email.delivered',
    data: { email_id: 're_123' }
  })
});

Dashboard UI guide

Route: /project/:projectId/mail

Delivery Logs tab

status badge (queued/sent/delivered/bounced/complained/failed)
subject, recipient(s), provider id, sent time
live status modal fetches provider status by resend id

Audiences & Contacts tab

create/delete audiences
add/remove contacts
locked if BYOK key is not configured

Marketing Broadcasts tab

compose audience + subject + html
send campaign via broadcast API
locked if BYOK key is not configured
each send counts against the monthly mail quota

Add product screenshots/annotated walkthrough images in this section if your docs deployment supports hosted image assets.

Security notes

BYOK format validation: ^re_[A-Za-z0-9_]+$
key encryption at rest uses shared encrypt/decrypt helpers (AES)
rotate/clear BYOK through project update workflows (PATCH /api/projects/:projectId with resendApiKey: null, then set a new re_... key)
live status endpoints validate project ownership before provider lookups
webhook authenticity is checked with Svix verification

Error reference

Endpoint	Status	Typical message
`POST /api/mail/send`	`400`	`Recipient list cannot be empty` / `Reply-to list cannot be empty` / `Subject is required` / `Provide at least one of html or text content.` / `Template not found.`
`POST /api/mail/send`	`403`	`Forbidden. This action requires a Secret Key (sk_live_...).`
`POST /api/mail/send`	`429`	`Monthly mail limit exceeded.`
`POST /api/mail/send-batch`	`400`	`Batch cannot be empty` / `Max 100 emails per batch` / `Recipient list cannot be empty` / `Reply-to list cannot be empty` / `Subject is required` / `Provide html or text`
`POST /api/mail/send-batch`	`403`	`Forbidden. This action requires a Secret Key (sk_live_...).`
`POST /api/mail/send-batch`	`429`	`Monthly mail limit exceeded.`
`GET /api/mail/logs/:resendId`	`400`	Invalid resendId format
`GET /api/mail/logs/:resendId`	`404`	Mail log entry not found for this project
`GET /api/mail/audiences` + audience mutations	`403`	This feature requires a BYOK Resend key
`GET/PATCH/DELETE /api/mail/audiences/:id/contacts/*`	`400`	Invalid audience/contact id format
`GET/PATCH/DELETE /api/mail/audiences/:id/contacts/*`	`403`	Contacts require a custom Resend API Key (BYOK)
`POST /api/mail/broadcasts*`	`400`	audienceId, subject, and html are required
`POST /api/mail/broadcasts*`	`403`	Broadcasts require a configured BYOK Resend key
`POST /api/mail/webhook`	`400`	Webhook signature verification failed
Provider-proxied endpoints	passthrough	Upstream Resend status/message are surfaced

Most endpoints follow urBackend envelope shape:

{
  "success": false,
  "data": {},
  "message": "Human-readable error"
}

Webhook signature failures currently return:

{
  "success": false,
  "message": "Webhook signature verification failed."
}

Changelog & migration notes

Compared to legacy single-send usage:

/api/mail/send is now asynchronous queue-backed
/api/mail/send-batch adds bulk dispatch (up to 100 items/request)
MailLog is first-class for auditability and dashboard visibility
new BYOK-gated resources: audiences, contacts
new BYOK-gated resource: broadcasts (counted against the monthly mail quota)
webhook path requires raw-body middleware placement before JSON parser
new env dependencies for production-grade mail processing (RESEND_WEBHOOK_SECRET, sender defaults)

For release-level change history, see May 2026 changelog.

​Overview

​How Mail Platform fits urBackend

​Architecture

​Feature gating matrix

​Getting started

​Prerequisites

​Configure BYOK in Dashboard

​Required server environment

​Register webhook in Resend

​Sending emails

​POST /api/mail/send (single)

​Request schema

​Quota and limits

​Example

​Success envelope

​POST /api/mail/send-batch (max 100)

​Request schema

​Quota behavior

​Partial success

​Example

​Mail logs

​GET /api/mail/logs (public) and GET /api/projects/:projectId/mail/logs (dashboard)

​MailLog fields

​Live status

​Audiences & Contacts (BYOK-gated)

​Audiences endpoints

​Contacts endpoints

​Marketing broadcasts (BYOK)

​Two-step flow

​from resolution order

​Quota checks

​Webhook integration

​Why raw-body parsing is required

​Secret configuration

​Event mapping to MailLog.status

​Retry behavior

​Dashboard UI guide

​Delivery Logs tab

​Audiences & Contacts tab

​Marketing Broadcasts tab

​Security notes

​Error reference

​Changelog & migration notes

Overview

How Mail Platform fits urBackend

Architecture

Feature gating matrix

Getting started

Prerequisites

Configure BYOK in Dashboard

Required server environment

Register webhook in Resend

Sending emails

POST `/api/mail/send` (single)

Request schema

Quota and limits

Example

Success envelope

POST `/api/mail/send-batch` (max 100)

Request schema

Quota behavior

Partial success

Example

Mail logs

GET `/api/mail/logs` (public) and GET `/api/projects/:projectId/mail/logs` (dashboard)

`MailLog` fields

Live status

Audiences & Contacts (BYOK-gated)

Audiences endpoints

Contacts endpoints

Marketing broadcasts (BYOK)

Two-step flow

`from` resolution order

Quota checks

Webhook integration

Why raw-body parsing is required

Secret configuration

Event mapping to `MailLog.status`

Retry behavior

Dashboard UI guide

Delivery Logs tab

Audiences & Contacts tab

Marketing Broadcasts tab

Security notes

Error reference

Changelog & migration notes