Skip to main content
Texting runs on Pramaan’s account: there is nothing to connect. You need a number to send from, and Pramaan gets it for you.

​
Send a text

  • If you have a number in the destination’s country, it is used.
  • If you have none, one is provisioned there first and the text is sent from it. from in the result tells you which number was used.
  • Pass from to choose one of your numbers yourself.
  • ref goes to sms.status to read the delivery status.

​
Numbers are rented by the month

  • A number’s first month is charged the moment it is bought, whether you asked for it with phone.number.provision or sms.send got it for you, and even if the rest of that call then fails: the number is yours. It then renews every month from your credit, on the same day.
  • Number charges and registration fees do not count toward your daily spend cap. They only need enough credit.
  • Retrying phone.number.provision with the same Idempotency-Key never buys a second number.
  • If a renewal cannot be paid, the number stops sending and you get a rental.past_due event. Top up within 7 days and it carries on. After 7 days it is released and you get rental.released.
  • Some countries only hand out numbers after identity or address checks. Those cannot be provisioned automatically yet; the call returns a clear invalid_request.
Your numbers are listed under Numbers in the dashboard.

​
United States: register first

US carriers only deliver business texts from a registered business and campaign. Until your registration is approved, sms.send to a US number returns invalid_request and nothing is sent.
  1. Call sms.registration.submit with your business details (legal name, tax id, address, a contact person) and your campaign (what you send, how people opted in, two to five sample messages, and public links to your privacy policy and terms: privacyPolicyUrl and termsUrl; carriers reject a campaign without them). This files the business.
  2. Poll sms.registration.status. Reviews take from minutes to a few days.
  3. When the status is brand_approved, call sms.registration.submit again with the same details and a new Idempotency-Key. This files the campaign. (Reusing the first call’s key only replays its answer.)
  4. When the status is approved, you can text US numbers.
The carriers charge for registration: a fee when the business is filed, a fee when the campaign is filed, and a monthly campaign fee. Each fee is charged once, when that filing is made; the campaign’s first month is charged when the campaign is filed, and it then renews like a number does. The call itself costs the minimum call price, also when there is nothing to file. If your credit cannot cover a fee, or a number’s first month, the call returns 402 spend_cap_reached and nothing is filed or bought. If the campaign’s monthly fee cannot be paid, you get rental.past_due and US texts keep going for 7 days. After that the campaign is withdrawn, you get rental.released, and texts to US numbers are refused again until you submit the registration again (your business stays registered; only the campaign is filed anew). Not supported yet: sole-proprietor registration, toll-free verification and short codes.

​
Delivery and replies

Subscribe a webhook endpoint to:

​
Limits

Each account can send 200 texts a day by default. Past that, sms.send returns 429 rate_limited until the next day (UTC). Ask us if you need more.