Skip to content

send.mdx

Latest commit

 

History

History
232 lines (190 loc) · 7.72 KB

send.mdx

File metadata and controls

232 lines (190 loc) · 7.72 KB
Raw
title Send mail
description 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, or an array of recipient addresses. Each address must be a valid email. An array must contain at least one entry. Optional reply-to address, or an array of addresses. Each address must be a valid email. When provided as an array, it must contain at least one entry. Forwarded to Resend as the message's `Reply-To` header. 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.
  • to and replyTo must contain valid email addresses. Array forms cannot be empty (Recipient list cannot be empty, Reply-to list cannot be empty).
  • Subject is required after any template resolution and variable interpolation (Subject is required).
  • The rendered message must include a non-empty html or text body. Requests where both come out empty after interpolation are rejected with Provide html or text (or Provide at least one of html or text content. when neither field was supplied).

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://app.urbackend.in), 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+**). 
const res = await fetch('https://api.urbackend.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.urbackend.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',
    replyTo: 'support@acme.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.urbackend.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.urbackend.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 Message Cause
400 Bad Request Invalid recipient email format / Recipient list cannot be empty to is missing, malformed, or an empty array
400 Bad Request Invalid replyTo email format / Reply-to list cannot be empty replyTo is malformed or an empty array
400 Bad Request Subject is required Subject missing, blank, or empty after template/variable interpolation
400 Bad Request Provide at least one of html or text content. Neither html nor text supplied (or both empty after interpolation)
400 Bad Request Template not found. templateId / templateName does not resolve
401 Unauthorized Project context missing. Request has no resolved project
403 Forbidden Forbidden. This action requires a Secret Key (sk_live_...). Non-secret key used
404 Not Found Project not found. Project record missing
429 Too Many Requests Monthly mail limit exceeded. Project quota exhausted for the month