Send mail

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

string

required

Recipient email address.

string

Required in direct mode.

string

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

string

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

string

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

string

Template key or name. Use either templateId or templateName.

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:

Project template override
Global/system template
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

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.

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.

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'
    }
  })
});

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',
    subject: 'Welcome to Acme',
    html: '<h1>Hello</h1><p>Your account is ready.</p>'
  })
});

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String jsonBody = """
      {
        "to": "user@example.com",
        "templateName": "welcome",
        "variables": {
          "name": "Ava",
          "projectName": "Acme",
          "appUrl": "https://acme.com"
        }
      }
      """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.ub.bitbros.in/api/mail/send"))
        .header("Content-Type", "application/json")
        .header("x-api-key", "sk_live_YOUR_SECRET_KEY")
        .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
        .build();

    HttpClient client = HttpClient.newHttpClient();
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  public static void main(String[] args) throws Exception {
    String jsonBody = """
      {
        "to": "user@example.com",
        "subject": "Welcome to Acme",
        "html": "<h1>Hello</h1><p>Your account is ready.</p>"
      }
      """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.ub.bitbros.in/api/mail/send"))
        .header("Content-Type", "application/json")
        .header("x-api-key", "sk_live_YOUR_SECRET_KEY")
        .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
        .build();

    HttpClient client = HttpClient.newHttpClient();
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
}

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

Overview

Authentication

Database

Storage

Mail

POST `/api/mail/send`

Required headers

Request body

Validation rules

Template resolution order

Placeholder syntax

How to use

Success response

Errors

​POST /api/mail/send

​Required headers

​Request body

​Validation rules

​Template resolution order

​Placeholder syntax

​How to use

​Success response

​Errors

POST `/api/mail/send`

Required headers

Request body

Validation rules

Template resolution order

Placeholder syntax

How to use

Success response

Errors