Phone numbers

An agent on Starter or Pro can buy a US number and receive texts.

The number belongs to the agent’s inbox. It receives SMS today. Voice calling is coming soon. Owner account alerts are a separate opt-in at /sms.

Your agent gets a phone number

Starter and Pro agents can buy a US local number through the API or MCP and receive SMS on that inbox. Each billable number is $3 a month. Pro includes 3 numbers. Voice calling is coming soon.

What works today

  • Buy a US number with POST /api/v1/inboxes/{id}/phone-number {"area_code":"415"} or the MCP tool cooper_provision_phone_number. A verified owner is required (HTTP 409 owner_required). Idempotency-Key is supported. GET reads the number and DELETE releases it.
  • Inbound texts are stored on the inbox as messages with channel sms. Cooper sends a message.received webhook. otp_candidates lists codes found in the text.
  • Wait with the MCP tool cooper_wait_for_sms (default 20 seconds, maximum 25). GET /api/v1/inboxes/{id}/events?types=message.received&wait=25 waits for the next received message on the inbox, email or SMS. It does not filter to SMS.
  • STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, and REVOKE opt that sender out. START, YES, or UNSTOP clears the opt-out. A send to an opted-out recipient returns HTTP 409 recipient_opted_out.
  • Price: $3 a month per billable number on Starter and Pro, with 100 segments on that number.

What is not ready

  • Texting arbitrary recipients from a customer number returns HTTP 409 outbound_not_registered until per-customer registration launches.
  • Voice calling is coming soon.
  • When SMS is turned off for a deployment, the phone-number and SMS routes return HTTP 404.
  • Phone number: Free includes none. Buying a number returns HTTP 402 plan_limit_exceeded.
  • Phone number: up to 3 US numbers, each $3 a month with 100 segments. None are included.
  • Phone number: 3 US numbers and 1,500 segments included, up to 25 numbers. Each extra number is $3 a month with 100 segments.
A phone receives a one-time code by textSMS482913Agent numberStored on the inboxwebhook or wait
An OTP or 2FA text arrives on the agent’s number, is stored on the inbox, and can wake the agent by webhook or wait. Voice calling is coming soon.
curl -s https://cooperemail.com/api/v1/inboxes/$INBOX_ID/phone-number \
  -H "authorization: Bearer $COOP_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: phone-1" \
  -d '{"area_code":"415"}'

curl -s "https://cooperemail.com/api/v1/inboxes/$INBOX_ID/events?types=message.received&wait=25" \
  -H "authorization: Bearer $COOP_KEY"
The second request waits up to 25 seconds for any received message. For a text only, call cooper_wait_for_sms.

Phone numbers · SMS docs · Owner SMS alerts