Mail

Access mail methods via client.mail. This module allows you to send emails using your project’s configured mail provider (e.g. Resend).

Mail operations require a Secret Key (sk_live_...). This module should only be used in server-side environments (Node.js, Edge Functions, etc.). Never call these methods from a browser.

send

Send an email.

send(payload: SendMailPayload): Promise<SendMailResponse>

Parameters (SendMailPayload)

Field	Type	Required	Description
`to`	`string \| string[]`	Yes	Recipient email address(es).
`subject`	`string`	Template mode: No, Direct mode: Yes	Email subject line.
`text`	`string`	Direct mode: one of `text` or `html` is required	Plain text body.
`html`	`string`	Direct mode: one of `text` or `html` is required	HTML body.
`templateId`	`string`	Template mode: one of `templateId` or `templateName` is required	Mail template ObjectId.
`templateName`	`string`	Template mode: one of `templateId` or `templateName` is required	Template key/name lookup.
`variables`	`Record<string, unknown>`	No	Variables used in template rendering.

Payload modes

Use one of these modes:

Template mode: templateId or templateName (+ optional variables)
Direct mode: subject + at least one of text or html

Do not send both templateId and templateName in the same request.

Template resolution order

When you use templateName, urBackend resolves templates in this order:

Project template (override)
Global/system template
Legacy embedded project template fallback (older projects only)

Placeholder syntax

Escaped placeholder: {{name}}
Raw placeholder: {{{htmlSnippet}}} (use carefully)
Nested variables: {{user.name}}

For URL fields, prefer escaped placeholders like {{appUrl}}. URL-like variables are sanitized to safe http/https URLs before rendering. Returns (SendMailResponse)

Field	Type	Description
`id`	`string \| null`	The message ID from the provider (`null` if unavailable).
`provider`	`"byok" \| "default"`	The provider used for sending.
`monthlyUsage`	`number`	Total emails sent this month.
`monthlyLimit`	`number`	Your project’s monthly quota.

Example

// Template mode
const response = await client.mail.send({
  to: 'customer@example.com',
  templateName: 'welcome',
  variables: {
    name: 'Ava',
    projectName: 'Acme',
    appUrl: 'https://acme.com'
  }
});

console.log(response.id);

// Direct mode
const response = await client.mail.send({
  to: 'customer@example.com',
  subject: 'Welcome to urBackend',
  html: '<h1>Hi there!</h1><p>Thanks for joining.</p>'
});

console.log(response.id);

Get Started

Core Concepts

Guides

TypeScript SDK

React SDK

Security & Limits

send

Payload modes

Template resolution order

Placeholder syntax

​send

​Payload modes

​Template resolution order

​Placeholder syntax

send

Payload modes

Template resolution order

Placeholder syntax