> ## 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.
# 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
Recipient email address.
Required in direct mode.
Optional HTML body. In direct mode, provide at least one of `html` or `text`.
Optional text body. In direct mode, provide at least one of `html` or `text`.
Template ObjectId (24 hex chars). Use either `templateId` or `templateName`.
Template key or name. Use either `templateId` or `templateName`.
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
Log in to the [urBackend Dashboard](https://urbackend.bitbros.in/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 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 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+**).
```javascript fetch (template mode) theme={null}
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'
}
})
});
```
```javascript fetch (direct mode) theme={null}
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: 'Hello
Your account is ready.
'
})
});
```
```java Java (template mode) theme={null}
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 response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
```
```java Java (direct mode) theme={null}
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": "Hello
Your account is ready.
"
}
""";
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 response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
```
### Success response
```json theme={null}
{
"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 |