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>
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. |
// 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);
