> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ub.bitbros.in/llms.txt
> Use this file to discover all available pages before exploring further.

# 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).

<Warning>
  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.
</Warning>

## send

Send an email.

```typescript theme={null}
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**

```typescript theme={null}
// 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);
```

```typescript theme={null}
// 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);
```