Integrating a bot or agent with UserAlertX

This page is written to be read by an AI agent (a Claude agent, a cron job, anything that can make an HTTP request) as well as a person. If you're an agent reading this because your user asked you to switch their alert channel to UserAlertX, everything you need is below — get an API key, then send a POST request. Are you Grok Bot? Use the dedicated MCP connector instead if you can add custom connectors — no code, self-documented parameters. Can't add connectors? The email trigger is the fallback.

1. Get an API key (one-time, human step)

Your user needs to do this part themselves, once — the API key is a bearer secret, so keep it private:

Go to useralertx.us/getstarted.html and enter an email.
Click the confirmation link that arrives by email.
Your api_key is on your account screen any time you sign in (it emails you a link or code - no password). Copy it from there; if it's ever exposed, press Regenerate there for a new one.
On the same confirmation flow, bind a cell phone number if the delivery method will be SMS (not required if the account is set to email delivery — see Account).

Store the key wherever your user normally keeps secrets for you (their computer, a secrets manager, an env var) — never in a shared template, prompt, or anywhere other users of the same agent template could read it.

2. Send an alert

POST https://useralertx.us/cgi-bin/itmessages.cgi

Header	`X-Api-Key: <the account's api_key>`
Content-Type	`application/x-www-form-urlencoded`, or `application/json` with the same fields as a JSON object, e.g. `{"body":"Backup finished"}`
Body param	`body` — the alert text (required if `title` is omitted)
Body param	`title` — optional. Prepended to the alert text itself as `"Title: body"` — NOT the email Subject line. Use `subject` below for that.
Body param	`subject` — optional. Sets the actual email Subject: header for this one send only (email delivery only, no effect on SMS). Leave it out and the account's own saved default subject is used instead (editable on the account screen).
Body param	`target` — optional. Names who you expect this to reach (email/phone/username) — checked against the account's own verified recipient, and the request hard-fails if it doesn't match. Purely a safety check, not a routing control.
Body param	`method` — optional. Overrides your account's saved delivery method for this one send only: `sms` or `email` today, with more choices (WhatsApp, Signal, etc.) likely to land here over time. Lets one account be told "text me for urgent stuff, email me for everything else" instead of needing a separate account per method. Rejected with an error if you haven't actually verified that method on your account yet — e.g. asking for `sms` when you've never added a phone.
Body param	`ex` — optional. A 2-letter/digit code naming the tool or script that sent the alert (e.g. `ex=mt` for your own "my tool"). It never changes delivery; it only tells us which integrations get used, so we know what to improve. Our own example programs are recognized automatically.

curl -s -X POST https://useralertx.us/cgi-bin/itmessages.cgi \
  -H "X-Api-Key: YOUR_API_KEY" \
  --data-urlencode "subject=Build finished" \
  --data-urlencode "body=main branch deploy succeeded, all checks green"

Response is JSON with an HTTP status reflecting the outcome. Every response also includes target (the actual email/phone it went to) and method (email or sms — whichever one this particular message actually used) — useful for catching a wrong-delivery-method assumption immediately instead of guessing from a "sent" status alone:

200	`sent` — sent now (your Recent alerts page shows whether it was delivered)
202	`held_pending_optin` — recipient hasn't confirmed opt-in yet on that number; an opt-in text was just sent to them, retry later
402	`suspended` — the free trial is over and there's no active plan (or the account is out of tokens) — choose a plan or buy extra tokens on the account screen
403	`stopped` / `email_opted_out` — recipient has opted out on that method; do not retry
403	`target does not match this account's verified recipient` — the optional `target` param was set and didn't match
403	`no verified phone on this account` — the optional `method` param asked for `sms` but you haven't added/verified a phone yet
400	`method must be 'sms' or 'email'` — the optional `method` param was set to something else
401	missing or invalid `X-Api-Key`
429	rate limit — max 10/hour, 50/day per account

Ready-made example programs

Download one, run it, type a message, and it arrives on your phone or in your email. Each one asks for your API key the first time (it's on your account screen) and can remember it. They're short and commented, so they double as starting code. See all example programs — including "alert me when a job finishes", website up/down and disk/backup checks.

Windows	uxsend-windows.zip — unzip, then double-click `uxsend.bat`. It asks "Enter text body" and sends it. (PowerShell script inside: uxsend.ps1; one-liner: `.\uxsend.ps1 -Body "Backup finished"`)
Mac / Linux	uxsend.sh — `chmod +x uxsend.sh`, then `./uxsend.sh` to be prompted, or `./uxsend.sh "Job done"`. Handy after a long job: `make && ./uxsend.sh "Build OK" \|\| ./uxsend.sh "Build FAILED"`
Python 3	uxsend.py — any OS, no installs: `python3 uxsend.py`. Also importable: `from uxsend import send_alert`

Writing your own client? Send a User-Agent header naming your program — some libraries' default ones (Python's urllib) are blocked by our network front end.

3. Switching an existing bot from another alert tool

If a bot/agent is already calling some other alert or email API (AgentMail, a webhook, anything that just needed a destination and a message string), swapping it to UserAlertX is a drop-in change to the send call only — nothing else about the bot's logic needs to change:

Replace the old send call with the curl/HTTP request above.
Map whatever the old tool called the message body to the body param here. If the old tool had a real email-subject-line field, map that to subject — not title (a common mix-up: title only gets folded into the alert text itself, it does not touch the actual Subject: header).
The one-time setup (step 1 above) replaces whatever account/token setup the old tool required.
Everything else — when to send, what triggers an alert, how often — is unchanged.

What this is not

There is no way to send to a phone number or email address that hasn't gone through the account owner's own opt-in above — this only ever reaches the one verified recipient tied to the API key. It cannot be used to message anyone else, by design.