Integrate Mailbot with any stack

Mailbot is a plain HTTPS API. Create an account, verify your sender domain, then any backend, app, or automation that can make an HTTP request can send transactional email through Mailbot.

The integration model

Mailbot uses plain HTTPS and JSON. There is no proprietary protocol and no required client library. Every integration — a web app, a mobile backend, a cron job, a CI pipeline, a serverless function, or a no-code automation — performs the same three steps:

1. Authenticate with the Bearer API key from your verified Mailbot account.
2. POST a JSON body describing one email (to, subject, text and/or html) to /v1/send.
3. Read the JSON response — a 202 on acceptance, or a documented error code you can act on.

The same endpoint powers every use case in these docs, from OTP and reset links to invoice, order, and alert emails.

Base URL & environments

Use the same base URL for integration and production. For safe testing, use the standard test endpoint and keep the base URL configurable in your app environment.

Authentication

Every send is authenticated with a developer API key passed as a Bearer token:

Authorization: Bearer mb_live_xxx
Content-Type: application/json

• Keep the key server-side. Never embed it in browser JavaScript, mobile binaries, or public repositories.
• Store it in an environment variable or secret manager (for example MAILBOT_API_KEY).
• A missing, unknown, or revoked key returns 401 Unauthorized.

JSON request contract

Send POST /v1/send with a single JSON object describing one email.

{
  "from": "noreply@yourdomain.com",
  "to": "user@example.com",
  "subject": "Your verification code",
  "text": "Your code is 884921",
  "html": "<p>Your code is <strong>884921</strong></p>",
  "idempotency_key": "otp-user-142-1718000000"
}

JSON response contract

On acceptance the API returns HTTP 202 and a JSON body with an id you can log for correlation. Production queue mode returns queued; dry-run validation returns validated; delivery mode returns sent after handoff succeeds.

{
  "ok": true,
  "id": "msg_3f8c1a...",
  "status": "queued"
}

{
  "ok": true,
  "id": "msg_3f8c1a...",
  "status": "validated",
  "note": "Validated by Mailbot ID. No email was sent."
}

Always read ok and the HTTP status. Use id for your own logging and correlation.

Copy-paste code examples

The same request in four common stacks. Each reads the key from an environment variable and sends one email.

curl https://api.mailbot.id/v1/send \
  -H "Authorization: Bearer $MAILBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Your verification code",
    "text": "Your code is 884921"
  }'

const res = await fetch("https://api.mailbot.id/v1/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MAILBOT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "user@example.com",
    subject: "Your verification code",
    text: "Your code is 884921",
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error || "Mailbot send failed");
console.log(data.id, data.status);

import os, requests

res = requests.post(
    "https://api.mailbot.id/v1/send",
    headers={
        "Authorization": f"Bearer {os.environ['MAILBOT_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "to": "user@example.com",
        "subject": "Your verification code",
        "text": "Your code is 884921",
    },
    timeout=15,
)

data = res.json()
res.raise_for_status()
print(data["id"], data["status"])

use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('MAILBOT_API_KEY'))
    ->acceptJson()
    ->post('https://api.mailbot.id/v1/send', [
        'to' => 'user@example.com',
        'subject' => 'Your verification code',
        'text' => 'Your code is 884921',
    ]);

$response->throw();
$data = $response->json();
// $data['id'], $data['status']

Serverless & no-code automation

Any platform that can make an outbound HTTP request can call Mailbot. Configure a generic HTTP/webhook action with these settings — the same contract applies whether it runs on a serverless function, a workflow automation, or a no-code tool:

Safe testing

Mailbot gives you a standard test endpoint for checking an integration safely:

• POST /v1/test-email: sends a standardized Mailbot test message to an address you control. It accepts to, optional from, optional label, and optional idempotency_key.

curl https://api.mailbot.id/v1/test-email \
  -H "Authorization: Bearer $MAILBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "safe@yourdomain.com", "label": "Smoke test" }'

Error handling & common failures

Errors return a non-2xx HTTP status and a JSON body with an error string (and details for validation errors). Handle these explicitly:

{
  "error": "Invalid send request.",
  "details": ["Field \"to\" must be an email address."]
}

Idempotency & retries

Include an optional idempotency_key (up to 128 characters) on any send you might retry — for example, a value derived from your internal event id.

• A repeated request from the same account with the same idempotency_key can return the same accepted id instead of creating a duplicate.
• Use a stable value from your own system, such as an order id, invoice id, or alert event id.
• Keep the same key when retrying after a timeout or temporary 5xx response.

Production checklist

• API key stored server-side in a secret manager, never shipped to clients.
• Sender domain verified; from set to a verified address (or rely on the configured default sender).
• idempotency_key set on every send that can be retried.
• Explicit handling for 400, 401, 403, 429, 502, and 503.
• Retries limited to 429/5xx/network errors with exponential backoff.
• Request timeouts set on your HTTP client.
• Integration smoke-tested with /v1/test-email and verified against /v1/status before relying on live delivery.