Developer Documentation

httphttps://api.mail.utobo.com/v1

json// Success
{ "id": "3c9b0f4e-1a2b-...", "message": "Email sent." }

// Error
{ "error": "The 'from' domain is not verified." }

httpAuthorization: Bearer av_live_your_api_key_here

bash# Store your key as an environment variable (never hardcode it)
export UTOBO_MAIL_API_KEY="av_live_a1b2c3d4e5f6..."

json{ "id": "3c9b0f4e-1a2b-4c3d-8e5f-6a7b8c9d0e1f", "message": "Email sent." }

jsonPOST /v1/send-email
Authorization: Bearer av_live_your_api_key_here
Content-Type: application/json

{
  "from":     "Acme Support <support@acme.com>",
  "to":       ["alice@example.com", "bob@example.com"],
  "cc":       "manager@acme.com",
  "subject":  "Your order #4521 has shipped",
  "html":     "<p>Your order is on the way! Track it at <a href='...'>acme.com/track</a></p>",
  "text":     "Your order is on the way! Track it at acme.com/track",
  "reply_to": "orders@acme.com",
  "headers":  { "X-Order-ID": "4521" }
}

json{ "id": "3c9b0f4e-1a2b-4c3d-8e5f-6a7b8c9d0e1f", "message": "Email sent." }

bashcurl https://api.mail.utobo.com/v1/send-email/3c9b0f4e-1a2b-4c3d-8e5f-6a7b8c9d0e1f \
  -H "Authorization: Bearer $UTOBO_MAIL_API_KEY"

json{
  "id":             "3c9b0f4e-1a2b-4c3d-8e5f-6a7b8c9d0e1f",
  "from":           "Acme Support <support@acme.com>",
  "to":             ["alice@example.com"],
  "subject":        "Your order has shipped",
  "status":         "sent",
  "ses_message_id": "0100019...@us-east-1.amazonses.com",
  "created_at":     "2026-05-29T10:30:00.000Z"
}

jsonHTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Resource: key

{ "error": "API key rate limit exceeded.", "retry_after": 60 }

javascriptconst { data, error } = await client.emails.send({ ... });

if (error) {
  switch (error.statusCode) {
    case 401:
      console.error('Invalid API key — check your UTOBO_MAIL_API_KEY env var');
      break;
    case 422:
      console.error('Domain not verified — go to Account → Domains');
      break;
    case 429:
      console.error('Rate limited — retry after 60 seconds');
      break;
    default:
      console.error('Send failed:', error.message);
  }
  return;
}

console.log('Sent:', data.id);

bashnpm install utobo-mail # or yarn add utobo-mail # or pnpm add utobo-mail

typescriptimport { UtoboMail } from 'utobo-mail';

// Option 1: Pass key directly
const client = new UtoboMail('av_live_your_api_key');

// Option 2: Use environment variable (recommended)
// Set UTOBO_MAIL_API_KEY in your .env file
const client = new UtoboMail(); // reads process.env.UTOBO_MAIL_API_KEY

// Option 3: Custom base URL (advanced)
const client = new UtoboMail(process.env.UTOBO_MAIL_API_KEY, {
  baseUrl: 'https://api.mail.utobo.com/v1',
});

typescriptconst { data, error } = await client.emails.send({
  from:    'Acme <noreply@acme.com>',
  to:      'user@example.com',          // or ['a@b.com', 'c@d.com']
  subject: 'Welcome to Acme!',
  html:    '<p>Thanks for signing up.</p>',
  // Optional:
  text:     'Thanks for signing up.',   // Plain text fallback
  cc:       'team@acme.com',
  bcc:      'archive@acme.com',
  reply_to: 'support@acme.com',
  headers:  { 'X-User-ID': '12345' },
});

if (error) console.error(error.message);
else console.log('Email ID:', data.id);

typescriptconst { data, error } = await client.emails.get('3c9b0f4e-...');

if (!error) {
  console.log(data.status);      // "sent" | "failed"
  console.log(data.created_at);  // ISO timestamp
}

bashnpm install @react-email/render react react-dom

typescriptimport { WelcomeEmail } from './emails/WelcomeEmail';

const { data, error } = await client.emails.send({
  from:    'Acme <noreply@acme.com>',
  to:      'user@example.com',
  subject: 'Welcome!',
  react:   <WelcomeEmail name="Alice" plan="Starter" />,
  // html is auto-generated from the React component
});

typescriptimport type {
  CreateEmailOptions,
  CreateEmailResponseSuccess,
  GetEmailResponseSuccess,
  ErrorResponse,
  Response,
} from 'utobo-mail';

bashcurl -X POST https://api.mail.utobo.com/v1/send-email \
  -H "Authorization: Bearer $UTOBO_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from":    "Acme <noreply@acme.com>",
    "to":      ["user@example.com"],
    "subject": "Hello from Utobo Mail!",
    "html":    "<p>Your message here.</p>"
  }'

bashcurl https://api.mail.utobo.com/v1/send-email/3c9b0f4e-1a2b-... \
  -H "Authorization: Bearer $UTOBO_MAIL_API_KEY"

bash# Encode file as base64
B64=$(base64 -i invoice.pdf | tr -d '\n')

curl -X POST https://api.mail.utobo.com/v1/send-email \
  -H "Authorization: Bearer $UTOBO_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"from\":    \"Billing <billing@acme.com>\",
    \"to\":      [\"customer@example.com\"],
    \"subject\": \"Your invoice\",
    \"html\":    \"<p>Please find your invoice attached.</p>\",
    \"attachments\": [{
      \"filename\":    \"invoice.pdf\",
      \"content\":     \"$B64\",
      \"contentType\": \"application/pdf\"
    }]
  }"

bashpip install requests

pythonimport os
import requests

UTOBO_MAIL_API_KEY = os.environ["UTOBO_MAIL_API_KEY"]

response = requests.post(
    "https://api.mail.utobo.com/v1/send-email",
    headers={
        "Authorization": f"Bearer {UTOBO_MAIL_API_KEY}",
        "Content-Type":  "application/json",
    },
    json={
        "from":    "Acme <noreply@acme.com>",
        "to":      ["user@example.com"],
        "subject": "Welcome to Acme!",
        "html":    "<p>Thanks for joining us.</p>",
    },
)

data = response.json()

if response.status_code == 200:
    print(f"Sent! Email ID: {data['id']}")
else:
    print(f"Error {response.status_code}: {data.get('error')}")

pythonimport asyncio
import os
import httpx

async def send_email():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.mail.utobo.com/v1/send-email",
            headers={"Authorization": f"Bearer {os.environ['UTOBO_MAIL_API_KEY']}"},
            json={
                "from":    "Acme <noreply@acme.com>",
                "to":      ["user@example.com"],
                "subject": "Async email!",
                "html":    "<p>Sent asynchronously.</p>",
            },
        )
        return response.json()

asyncio.run(send_email())

bashcomposer require guzzlehttp/guzzle

php<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://api.mail.utobo.com/v1/send-email', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('UTOBO_MAIL_API_KEY'),
        'Content-Type'  => 'application/json',
    ],
    'json' => [
        'from'    => 'Acme <noreply@acme.com>',
        'to'      => ['user@example.com'],
        'subject' => 'Welcome!',
        'html'    => '<p>Thanks for joining.</p>',
    ],
]);

$data = json_decode($response->getBody(), true);
echo 'Email ID: ' . $data['id'];

php<?php
$payload = json_encode([
    'from'    => 'Acme <noreply@acme.com>',
    'to'      => ['user@example.com'],
    'subject' => 'Welcome!',
    'html'    => '<p>Thanks for joining.</p>',
]);

$ch = curl_init('https://api.mail.utobo.com/v1/send-email');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('UTOBO_MAIL_API_KEY'),
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo 'Email ID: ' . $data['id'];

bashnpm install utobo-mail @react-email/render react react-dom npm install -D @react-email/components

typescript// emails/WelcomeEmail.tsx
import { Html, Head, Body, Container, Text, Button } from '@react-email/components';

interface WelcomeEmailProps {
  name: string;
  loginUrl: string;
}

export function WelcomeEmail({ name, loginUrl }: WelcomeEmailProps) {
  return (
    <Html>
      <Head />
      <Body style={{ fontFamily: 'sans-serif', backgroundColor: '#f4f4f4' }}>
        <Container style={{ maxWidth: '600px', margin: '0 auto', padding: '24px' }}>
          <Text style={{ fontSize: '24px', fontWeight: 'bold' }}>
            Welcome, {name}!
          </Text>
          <Text style={{ color: '#555' }}>
            Your account is ready. Click below to sign in.
          </Text>
          <Button
            href={loginUrl}
            style={{ background: '#4f46e5', color: '#fff', padding: '12px 24px', borderRadius: '6px' }}
          >
            Sign in to your account
          </Button>
        </Container>
      </Body>
    </Html>
  );
}

typescriptimport { UtoboMail } from 'utobo-mail';
import { WelcomeEmail } from './emails/WelcomeEmail';

const client = new UtoboMail(process.env.UTOBO_MAIL_API_KEY);

const { data, error } = await client.emails.send({
  from:    'Acme <noreply@acme.com>',
  to:      'alice@example.com',
  subject: 'Welcome to Acme!',
  // The SDK renders the React component to HTML automatically
  react:   <WelcomeEmail name="Alice" loginUrl="https://acme.com/login" />,
});