AI agent Twilio security: four controls that prevent the $1,200 SMS bill

Handing an AI agent your Twilio key is equivalent to handing it a corporate credit card with no limit, valid in every country, that charges $0.0082 per US message and up to $0.30 per premium-route international message. Twilio has no per-key spend cap. Your agent has no retry budget. The $1,200 SMS bill is not a hypothetical — it's what a stuck retry loop at international rates looks like by the time anyone checks the dashboard.

This post covers three failure modes that produce runaway Twilio spend, why Twilio's own safety features don't prevent them, and the four controls that do — with the specific Keybrake proxy configuration for each.

How agents call Twilio today

The standard pattern for wiring Twilio SMS into an AI agent uses the Twilio Python helper library inside a LangChain tool, a CrewAI tool, or an OpenAI function-calling handler. A minimal support agent that sends confirmation texts looks something like this:

from twilio.rest import Client
from langchain.tools import BaseTool

twilio = Client(
    os.environ["TWILIO_ACCOUNT_SID"],
    os.environ["TWILIO_AUTH_TOKEN"]
)

class SendSMSTool(BaseTool):
    name = "send_sms"
    description = (
        "Send a text message to a customer's mobile number. "
        "Use the customer's E.164 phone number as 'to'."
    )

    def _run(self, to: str, body: str) -> str:
        msg = twilio.messages.create(
            to=to,
            from_=os.environ["TWILIO_FROM_NUMBER"],
            body=body
        )
        return f"Sent: {msg.sid}"

This is clean and idiomatic. The tool description is tight, the return value gives the agent a receipt, and the pattern composes naturally with any orchestration framework. The problem isn't the code. The problem is what TWILIO_AUTH_TOKEN actually grants once the agent starts running unsupervised.

A standard Twilio auth token gives the holder full account access: send SMS to any number, any country, any volume; make voice calls; provision new phone numbers; access recordings; query all message history. Even a purpose-built SMS agent with a tool definition that only exposes send_sms is one bad prompt — or one network error — away from a four-digit bill.

Three ways the bill gets out of hand

All three failure modes have the same structural shape: the Twilio auth token grants capabilities (send to any number, any volume), and nothing between the agent and Twilio's API enforces constraints (spend limit, destination scope, deduplication). The agent tool definition tells the model when to send an SMS. It cannot tell Twilio how much damage a bad call can do.

Why Twilio's own safety features don't close the gap

Twilio ships several features that look relevant here. None of them solve the problem at the right layer:

• Twilio spend alerts — Dashboard spend alerts fire an email when your account crosses a dollar threshold you configure. By the time the email arrives — typically 15–30 minutes after the threshold is crossed — a retry storm or batch broadcast has already completed. The alert is post-hoc; it doesn't stop the next message from sending.
• Sub-accounts — You can create a Twilio sub-account per agent and cap its funding. This is the closest Twilio gets to per-agent spend control: fund the sub-account with $20, and the agent can send at most ~2,400 US messages before running dry. The limitation is operational complexity: sub-accounts require manual provisioning, each needs its own credentials, and they have no per-call audit log accessible without custom querying. For a team running 10+ agents, managing 10+ sub-accounts with individually funded balances is significant overhead.
• Geographic Permissions — Twilio lets you disable entire world regions at the account level (block all messages to Africa, for example). This is coarse-grained and permanent — it's not a per-agent, per-run control, and it doesn't protect against the retry storm or the unsubscribed-list broadcast. It's also a dashboard-only setting, not configurable in code.
• Messaging Services — Twilio Messaging Services provide a pool of numbers and add opt-out handling (STOP keyword → do-not-contact list), but the opt-out list lives in Twilio's infrastructure. An agent that queries your CRM for opted-in users and then sends to everyone on the CRM list isn't protected by Twilio's STOP handling — it will send to unsubscribed users regardless, because those users never texted back STOP from the number on file.
• SDK-layer rate limiting — You can add a sleep or a semaphore to the _run method to limit calls per second. This controls throughput but not dollar exposure: a burst of 100 messages per second for three seconds is 300 messages, but 300 international-rate messages at $0.30 each is $90. Rate limiting counts calls, not dollars.

Four controls that actually prevent the damage

The common thread in all three failure modes is that enforcement needs to happen at the API call layer — after the agent constructs the request, before Twilio receives it. That's the proxy layer. Here are the four controls, mapped to the failure modes they address:

Setting up a Twilio vault key

You issue a vault key once per agent or per agent run. The key carries the real Twilio credentials (account SID and auth token) inside the proxy, along with the policy that governs this agent's calls:

curl -X POST https://proxy.keybrake.com/keys \
  -H "X-Admin-Key: $KEYBRAKE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot-prod",
    "vendor": "twilio",
    "twilio_account_sid": "'"$TWILIO_ACCOUNT_SID"'",
    "twilio_auth_token": "'"$TWILIO_AUTH_TOKEN"'",
    "policy": {
      "daily_usd_cap": 50,
      "allowed_prefixes": ["+1"],
      "dedup_window_seconds": 60,
      "expires_in": "24h"
    }
  }'

The response is a vault_key_xxx token. Your agent's environment gets two variables instead of the real Twilio credentials:

TWILIO_ACCOUNT_SID=vault_key_xxx   # the vault key replaces the real SID
TWILIO_PROXY_URL=https://proxy.keybrake.com/twilio

# In your agent code, construct the client with the proxy base URL:
from twilio.rest import Client

twilio = Client(
    os.environ["TWILIO_ACCOUNT_SID"],  # vault key
    os.environ["TWILIO_ACCOUNT_SID"],  # vault key used as both SID and token
    region=None
)
# Override the base URL via a custom HTTP client pointed at the proxy URL

The proxy receives the call with the vault key in the Authorization header, looks up the real Twilio account SID and auth token, enforces the policy (cap check, prefix check, dedup check), and if all checks pass, forwards the request to api.twilio.com using the real credentials. The Twilio response comes back verbatim; the proxy logs the cost from the response body and stores the call in the audit log before returning.

The audit log captures: vault key name, destination number prefix (not the full number — the last four digits are masked), message body length, price from Twilio's response, price_unit, message SID, whether the call was blocked and why, and a timestamp. For a batch run, you can query the log with GROUP BY vault_key_name, DATE(created_at) to get the cost breakdown per agent per day — something Twilio's own console only shows at the account level.

How the four controls map to each failure mode

The dollar cap is the backstop for every failure mode because it operates regardless of what caused the excess spend. The prefix allowlist and dedup window are more specific — they prevent the failure from happening rather than limiting the blast radius after it starts. The kill switch is the override when you need to stop an agent mid-run for any reason, including reasons that have nothing to do with spend.

What this doesn't address

Two things are outside the scope of the proxy approach:

Content-based filtering. The proxy enforces policies on destination and cost. It does not inspect message content for compliance — profanity, personally identifiable information, or content that violates Twilio's Acceptable Use Policy. Content filtering is a separate layer, typically handled at the prompt or output-validation stage before the SMS tool is called. The proxy is not a content moderation system.

Opt-in list management. The unsubscribed-list failure mode in this post is caused by a bad data pipeline query — the agent receives a list of numbers it shouldn't be texting. The proxy can limit the blast radius (the cap stops the batch mid-run), but the correct fix is enforcing the opted-in filter at the data layer before the agent's input is constructed. The proxy is a last line of defense for spend, not a substitute for correct input validation.

For a broader look at the audit trail structure that catches data-pipeline errors like this — including the agent_run_id pattern that lets you trace a bad batch back to the specific run and input data — see the audit trail schema post.

Bottom line

Twilio's auth token model is binary: you have it, you can send to anywhere at any volume, and nothing stops you until Twilio's post-hoc alert fires. For an AI agent running a batch job unsupervised, that's an unacceptable risk profile. The four controls — per-day USD cap, destination prefix allowlist, deduplication window, sub-second revoke — cover the three failure modes that actually produce large unexpected bills. All four operate at the proxy layer, before calls reach Twilio, without requiring any change to the agent's tool logic.

If your agent sends ten SMS messages a day in response to user requests, the risk profile is low and the controls are nice-to-have. If your agent runs nightly batches, processes ticket queues, or responds to external events with outbound messages, adding the proxy before going to production costs you nothing and prevents the class of incident where you're explaining a $1,200 Twilio charge to a CFO at 9am on a Tuesday.

For the Stripe equivalent of this problem — spend caps, endpoint allowlists, and kill switches for agents calling the Stripe API — see LangChain + Stripe: the spend-cap your agent doesn't have. For the general question of what to log and how to structure an audit trail that covers both Twilio and Stripe calls in a single query, see AI agent audit trail schema. And for the question of why even a Restricted Key (on Stripe) or a purpose-limited sub-account (on Twilio) isn't sufficient without a proxy enforcement layer, see Why your Stripe Restricted Key probably isn't restricted enough.