Use case

System alert email

Page operators or notify users when your backend detects an event or failure, with one Mailbot API call.

Answer first: to send a system alert, POST https://api.mailbot.id/v1/send with your Bearer key and a JSON body describing the event, severity, and a link to logs or a dashboard. Route alerts to a team distribution address and deduplicate with an idempotency_key per incident so a flapping condition doesn't flood inboxes.

Use case

Your monitoring or backend logic detects something that needs a human — a failed job, a crossed threshold, a security event, a downstream outage — and emails the responsible people. The body should carry severity, what happened, when it happened, and where to look.

Your backend owns the detection logic: decide what counts as an incident, attach the relevant context, and send a clear, scannable message. Mailbot accepts the alert payload and returns a message id for incident records.

When to send

A scheduled job fails.
An error rate or resource threshold is crossed.
A security-relevant event occurs.
A critical dependency is unreachable.

Prevent alert storms. Deduplicate and throttle alerts in your monitoring layer (for example, one email per incident per time window) and use idempotency_key so retries don't multiply messages.

API call

cURL

curl https://api.mailbot.id/v1/send \
  -H "Authorization: Bearer $MAILBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "alerts@yourdomain.com",
    "to": "oncall@yourdomain.com",
    "subject": "[ALERT] Payment worker failing — error rate 12%",
    "text": "Severity: high\nSummary: Payment worker error rate at 12% (threshold 5%).\nTime: 2026-06-22T10:00 WIB\nDashboard: https://yourapp.com/dashboard/incidents/9f2",
    "idempotency_key": "alert-payment-worker-2026-06-22T10:00"
  }'

Python (requests)

import os, requests

# Called from your cron / monitoring script when a threshold is crossed.
res = requests.post(
    "https://api.mailbot.id/v1/send",
    headers={
        "Authorization": f"Bearer {os.environ['MAILBOT_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "from": "alerts@yourdomain.com",
        "to": "oncall@yourdomain.com",
        "subject": "[ALERT] Payment worker failing — error rate 12%",
        "text": (
            "Severity: high\n"
            "Summary: Payment worker error rate at 12% (threshold 5%).\n"
            "Time: 2026-06-22T10:00 WIB\n"
            "Dashboard: https://yourapp.com/dashboard/incidents/9f2"
        ),
        "idempotency_key": "alert-payment-worker-2026-06-22T10:00",
    },
)
res.raise_for_status()

Required fields

Field	Required	Notes
`to`	Yes	Can be a team distribution address (for example `oncall@yourdomain.com`).
`subject`	Yes	Encode severity in the subject so it's scannable at a glance in a crowded mailbox.
`text` or `html`	Yes	The body carrying severity, summary, timestamp, and a link to logs or a dashboard.
`from`	No	Verified sender; defaults to the configured sender if omitted.
`idempotency_key`	Recommended	Dedupe per incident / time-window so a flapping condition doesn't flood inboxes.

Example payload

JSON request

{
  "from": "alerts@yourdomain.com",
  "to": "oncall@yourdomain.com",
  "subject": "[ALERT] Payment worker failing — error rate 12%",
  "text": "Severity: high\nSummary: Payment worker error rate at 12% (threshold 5%).\nTime: 2026-06-22T10:00 WIB\nDashboard: https://yourapp.com/dashboard/incidents/9f2",
  "html": "<p><strong>Severity: high</strong></p><p>Payment worker error rate at 12% (threshold 5%).</p><p>Time: 2026-06-22T10:00 WIB</p><p><a href="https://yourapp.com/dashboard/incidents/9f2">Open incident dashboard</a></p>",
  "idempotency_key": "alert-payment-worker-2026-06-22T10:00"
}

Example response

202 · queued

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

For delivered messages, the response can include status: "sent" and a delivery_id. See the API reference for every response shape.

Errors

Status	Meaning	What to do
`400`	Invalid payload (bad `to`, missing `subject`/body).	Fix the request; read `details`.
`401`	Bad or missing API key.	Check the Bearer header.
`429`	Send limit reached.	Back off; surface a "try again later" message to the user.
`502` / `503`	Mailbot is temporarily unable to accept the send.	Retry with backoff using the same `idempotency_key`.

Full error handling guidance is in the integration guide.

Testing

For safe setup, use the standard test endpoint to confirm delivery reaches an address you control:

cURL · test email

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": "Alert test" }'

Production checklist

Alerts deduped and throttled in your monitoring layer (for example, one email per incident per time window).
idempotency_key per incident / time-window.
Routed to a monitored team address.
Severity encoded in the subject.
Verified sender domain; from set to a verified address.
API key kept server-side; never sent to the browser or mobile client.
429/5xx handled with backoff, plus a non-email fallback for when email itself is degraded.