Send mail

Send transactional email with direct content or a named template.

POST /api/mail/send

Sends transactional email from your project.

For the complete Mail Platform documentation (BYOK, batch sending, logs, audiences, contacts, broadcasts, webhooks, and dashboard workflows), see Mail Platform guide.

This endpoint requires a Secret Key (sk_live_...). Do not call it from browser/client code.

Required headers

Header	Value
x-api-key	Your sk_live_... secret key
Content-Type	application/json

Request body

to · string · required

Recipient email address.

subject · string

Required in direct mode.

html · string

Optional HTML body. In direct mode, provide at least one of html or text.

text · string

Optional text body. In direct mode, provide at least one of html or text.

templateId · string

Template ObjectId (24 hex chars). Use either templateId or templateName.

templateName · string

Template key or name. Use either templateId or templateName.

variables · object

Optional template variables.

Validation rules

• Template mode: templateId or templateName
• Direct mode: subject + (html or text)
• Do not pass both templateId and templateName.
• If rendered subject/body becomes empty after variable interpolation, request is rejected with 400.

Template resolution order

When using templateName, urBackend resolves in this order:

1. Project template override
2. Global/system template
3. Legacy embedded template fallback (older projects only)

Placeholder syntax

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

For URL values, prefer escaped placeholders like {{appUrl}}. URL-like variables are sanitized to safe http/https values.

How to use

1. Get your Secret Key

   Log in to the urBackend Dashboard, create a new project, and copy your Secret Key (sk_live_...) or you can get it from rotating it from project overview page.

2. Copy the Code

   Copy your preferred language snippet from below. Use Direct Mode if you just want to send a quick HTML/Text email without setting up templates or use welcome template for fast test.

3. Paste and Run

   Paste the code into your app, replace sk_live_YOUR_SECRET_KEY with your actual key, change the to email address, and run it!

The Java examples use the native java.net.http.HttpClient (requires Java 11+) and Text Blocks for JSON formatting (requires Java 15+).

fetch (template mode)

const res = await fetch('https://api.ub.bitbros.in/api/mail/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'sk_live_YOUR_SECRET_KEY'
  },
  body: JSON.stringify({
    to: '[e-mail]',
    templateName: 'welcome',
    variables: {
      name: 'Ava',
      projectName: 'Acme',
      appUrl: 'https://acme.com'
    }
  })
});

Success response

{
  "success": true,
  "data": {
    "id": "mail_123",
    "provider": "default",
    "monthlyUsage": 1,
    "monthlyLimit": 100
  },
  "message": "Mail sent successfully."
}

Errors

Status	Cause
400 Bad Request	Invalid payload, invalid template ID, or empty rendered subject/body
401 Unauthorized	Missing project context
403 Forbidden	Non-secret key used
404 Not Found	Template or project not found
429 Too Many Requests	Monthly mail limit exceeded