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 Grok Bot connector instead — no code, just a URL and a key.

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 and is only ever shown one time:

Go to useralertx.com/getstarted.html and enter an email.
Click the confirmation link that arrives by email.
The confirmation page displays the account's api_key exactly once. Copy it now — it is not shown again and cannot be recovered, only rotated by creating a new account.
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.com/cgi-bin/itmessages.cgi

Header	`X-Api-Key: <the account's api_key>`
Content-Type	`application/x-www-form-urlencoded`
Body param	`title` — optional, short subject/label
Body param	`body` — the alert text (required if `title` is omitted)

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

Response is JSON with an HTTP status reflecting the outcome:

200	`sent` — delivered now
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` — free-tier limit reached with no billing on file
403	`stopped` / `email_opted_out` — recipient has opted out on that channel; do not retry
401	missing or invalid `X-Api-Key`
429	rate limit — max 10/hour, 50/day per account

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, and any subject/label field to title.
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.