Skip to main content

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.

​
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

HeaderValue
x-api-keyYour sk_live_... secret key
Content-Typeapplication/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+).
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: 'user@example.com',
    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

StatusCause
400 Bad RequestInvalid payload, invalid template ID, or empty rendered subject/body
401 UnauthorizedMissing project context
403 ForbiddenNon-secret key used
404 Not FoundTemplate or project not found
429 Too Many RequestsMonthly mail limit exceeded