Mail

Send transactional emails from your server using the SDK mail module.

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:

1. Project template (override)
2. Global/system template
3. 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: '[e-mail]',
  templateName: 'welcome',
  variables: {
    name: 'Ava',
    projectName: 'Acme',
    appUrl: 'https://acme.com'
  }
});

console.log(response.id);

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

console.log(response.id);