Developer Documentation

httphttps://api.email.utobo.com

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

// Error — POST /v1/emails
{
  "error":   "The 'from' domain is not verified.",
  "name":    "domain_not_verified",
  "message": "The 'from' domain is not verified."
}

httpAuthorization: Bearer ut_live_your_api_key_here

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

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

jsonPOST /v1/emails
Authorization: Bearer ut_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.email.utobo.com/v1/emails/3c9b0f4e-1a2b-4c3d-8e5f-6a7b8c9d0e1f \
  -H "Authorization: Bearer $UTOBO_EMAIL_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 }

json{
  "error":   "You don't have the 'emails:send' scope.",
  "name":    "insufficient_scope",
  "message": "You don't have the 'emails:send' scope."
}

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

if (error) {
  switch (error.statusCode) {
    case 401:
      console.error('Invalid API key — check your UTOBO_EMAIL_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);

javascriptimport nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.mail.utobo.com",
  port: 587,
  secure: false,                 // STARTTLS is negotiated on 587
  auth: { user: "apikey", pass: process.env.UTOBO_EMAIL_API_KEY },
});

await transport.sendMail({
  from: "Acme <noreply@acme.com>",
  to: "user@example.com",
  subject: "Welcome!",
  html: "<p>Thanks for joining.</p>",
});

ruby# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address:              "smtp.mail.utobo.com",
  port:                 587,
  user_name:            "apikey",
  password:             ENV["UTOBO_EMAIL_API_KEY"],
  authentication:       :plain,
  enable_starttls_auto: true,
}

python# settings.py
EMAIL_BACKEND       = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST          = "smtp.mail.utobo.com"
EMAIL_PORT          = 587
EMAIL_USE_TLS       = True
EMAIL_HOST_USER     = "apikey"
EMAIL_HOST_PASSWORD = os.environ["UTOBO_EMAIL_API_KEY"]

php$mail->isSMTP();
$mail->Host       = "smtp.mail.utobo.com";
$mail->Port       = 587;
$mail->SMTPAuth   = true;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Username   = "apikey";
$mail->Password   = getenv("UTOBO_EMAIL_API_KEY");

textcontact.created        contact.updated          contact.deleted
contact.added_to_list  contact.removed_from_list
contact.unsubscribed   contact.suppressed
email.sent             email.delivered          email.opened
email.clicked          email.bounced            email.complained
campaign.completed     sequence.enrolled

json{
  "id":         "b1e7...",              // unique event id
  "type":       "email.bounced",        // the event type
  "created_at": "2026-10-05T19:30:00Z", // when it happened (ISO 8601)
  "data": {                             // event-specific payload
    "email":       "user@example.com",
    "campaign_id": "c3a9...",
    "subject":     "Your order shipped"
  }
}

javascriptimport crypto from "crypto";

// Use the RAW request body bytes — not a re-serialized object.
function verifyUtoboWebhook(rawBody, headers, secret) {
  const signature = headers["x-utobo-signature"];   // "sha256=<hex>"
  const timestamp = headers["x-utobo-timestamp"];    // ms epoch

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60 * 1000) return false;

  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

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

typescriptimport { UtoboEmail } from 'utobo-email';

// Option 1: Pass key directly
const client = new UtoboEmail('ut_live_your_api_key');

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

// Option 3: Custom base URL (advanced)
const client = new UtoboEmail(process.env.UTOBO_EMAIL_API_KEY, {
  baseUrl: 'https://api.email.utobo.com',
});

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-email';

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

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

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

curl -X POST https://api.email.utobo.com/v1/emails \
  -H "Authorization: Bearer $UTOBO_EMAIL_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 utobo-email

pythonfrom utobo_email import UtoboEmail

client = UtoboEmail()   # or UtoboEmail("ut_live_...")

result = client.emails.send(
    from_="Acme <noreply@acme.com>",   # note: from_ (from is reserved)
    to="user@example.com",
    subject="Welcome!",
    html="<p>Thanks for joining.</p>",
)
print(result["id"])

pythonstatus = client.emails.get("3c9b0f4e-...")
print(status["status"])   # "sent" | "failed"

bashgem install utobo-email

rubyrequire "utobo_email"

client = UtoboEmail.new("ut_live_...")

result = client.emails.send(
  from: "Acme <noreply@acme.com>",
  to: "user@example.com",
  subject: "Welcome!",
  html: "<p>Thanks for joining.</p>"
)
puts result["id"]

rubystatus = client.emails.get("3c9b0f4e-...")
puts status["status"]   # "sent" | "failed"

bashgo get github.com/myutobo/utobo-email-go

goimport utoboemail "github.com/myutobo/utobo-email-go"

client, err := utoboemail.New("ut_live_...")
if err != nil { log.Fatal(err) }

resp, err := client.Emails.Send(&utoboemail.SendEmailRequest{
    From:    "Acme <noreply@acme.com>",
    To:      []string{"user@example.com"},
    Subject: "Welcome!",
    HTML:    "<p>Thanks for joining.</p>",
})
if err != nil { log.Fatal(err) }
fmt.Println("Sent:", resp.ID)

gostatus, err := client.Emails.Get("3c9b0f4e-...")
fmt.Println(status.Status)   // "sent" | "failed"

bashcomposer require guzzlehttp/guzzle

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

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://api.email.utobo.com/v1/emails', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('UTOBO_EMAIL_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.email.utobo.com/v1/emails');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('UTOBO_EMAIL_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-email @react-email/render react react-dom

typescript// emails/WelcomeEmail.tsx

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 { UtoboEmail } from 'utobo-email';
import { WelcomeEmail } from './emails/WelcomeEmail';

const client = new UtoboEmail(process.env.UTOBO_EMAIL_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" />,
});