FAQ

Answers to common questions about the API.

Quick answers to the questions developers ask most. Each one links to the guide that covers it in full.


Getting started

Is there a sandbox or test mode?

Not at this time. Every POST /v1/messages call sends a real text and uses credits. Testing your integration shows how to test safely with a group that contains only your team.

Do I need an SDK?

No. The API is plain HTTPS and JSON, so any language with an HTTP client works. See the Overview.

Can I try requests without writing code?

Yes. Every page in the API Reference has a console where you can enter your credentials and send a real request. You can also use the MCP server to work with your account from an AI assistant.

Which countries can I send to?

You can send to numbers in the US and Canada. Messages to Canadian numbers also fall under Canadian rules; see Compliance.


Sending messages

How many credits does a message use?

One credit per SMS segment. With standard (GSM-7) characters, a segment holds 160 characters, or 152 per segment when a message is split. If a message has one or more Unicode characters, such as an emoji or certain accented letters, it's sent with Unicode encoding, which holds 70 characters per segment, or 66 when split. If a message would need 3 or more segments, it's sent as an MMS instead, unless you set messageType to SMS. An MMS can be up to 1,600 characters and costs 3 credits regardless of length. See Core concepts.

Will my message go out as SMS or MMS?

If you don't set messageType, EZ Texting decides: text that fits in one or two SMS segments goes as SMS, longer text goes as MMS, and anything with media is MMS. Set messageType to force one or the other. See Core concepts.

Can I use the EZ Texting link shortener through the API?

Yes, if your account includes the link shortener. Use the same notation the compose box shows in the web app: put ${URL="www.eztexting.com"} in the message text and the link is shortened just as it would be in a message sent from the web app. Clicks are tracked: see them in the message report's links array or with GET /v1/message-reports/{id}/responses/link.

How do I schedule a message, or cancel a scheduled one?

Set sendAt to an ISO 8601 timestamp with a UTC offset. Scheduled messages appear in GET /v1/campaign-info until they go out, and DELETE /v1/messages with the ID returned when you sent it cancels one that hasn't been sent yet. See Appointment reminders.

What phone number format should I use?

The API accepts most common formats. Store and send the canonical form: 11 digits, country code first, digits only (15551234567). See Phone number formatting.

Can I send one message to thousands of contacts?

Yes. Sending to contacts one at a time works, but for large lists it's usually better to put the contacts in a group and send once with groupIds. One request covers everyone, and merge tags such as ${FirstName} in the message fill in each contact's own values. See Campaigns to a group.

How fast can I send?

While the API request limit is 200 requests per minute per account, a single request can send to an entire group, so one call can reach thousands of contacts. How fast those messages reach phones depends on your sending number type and its registration (10DLC, toll-free verification, or short code), not on how you call the API. See Rate limits.

I got a 201, but the text never arrived. Why?

A 201 means EZ Texting accepted the message, not that it was delivered. Check the delivery report for the message. Troubleshooting lists the usual causes, from opted-out numbers to carrier filtering.


Numbers and registration

What's the difference between 10DLC, toll-free, and short codes?

Number typeRegistrationGood for
10DLC (standard 10-digit local number)Brand and campaign registration through The Campaign RegistryMost business use, with a local presence
Toll-free (8XX)Toll-free verification formHigher throughput, nationwide identity, OTP and notifications
Short code (5 or 6 digits)Dedicated approval processVery high volume and large campaigns

See Compliance.

Do I have to register before I send?

Yes. US carriers require business senders to register, and unregistered traffic is heavily filtered or blocked. See Compliance.

Which number do my messages come from?

Your account's default number, unless you set fromNumber to use a different one. When you reply to a customer, use the number they texted. See Two-way conversations.


Compliance and opt-outs

What happens when someone texts STOP?

EZ Texting marks the contact optOut: true, sends a confirmation, and blocks further messages to that number from your account, including ones your code sends. UNSUBSCRIBE, QUIT, END, CANCEL, and REMOVE work the same way. See Compliance.

What does HELP do?

The platform automatically sends the standard, carrier-required HELP response. You don't need to handle it.

Do I need consent to send texts?

Yes. Get prior express written consent before you text anyone. A purchase, a booking, or a number on file isn't consent by itself. See Compliance.

What hours can I send?

Federal rules prohibit marketing texts before 8am or after 9pm in the recipient's local time, and several states are stricter. See Compliance.


Receiving and tracking

How do I receive replies?

Subscribe a webhook to inbound_text.received, and EZ Texting posts each inbound text to your server. See Webhooks.

Is there a webhook for delivery status?

Not at this time. Webhooks cover inbound texts, keyword opt-ins, and new contacts. For delivery status, use the message reports. See Send, track & receive.

What if my webhook endpoint goes down?

Callbacks fail while it's down, and after repeated failures EZ Texting may stop calling the subscription. If that happens, EZ Texting emails the account holder to let them know. Add a polling fallback that sweeps unread conversations. See Webhooks and Two-way conversations.


Accounts and access

Where do I get an API key?

There isn't a separate key. The API uses the same username and password you use to log in to the web app. Send them with Basic Auth, or exchange them once for an OAuth 2.0 access token and send that instead; the appKey and appSecret fields in POST /v1/tokens/create are that same username and password. See Authentication.

Can a teammate's login use the API?

Only the account holder and Admin teammates can call the API. Operator and Agent teammates' credentials return 403 Forbidden, even though they work in the web app.

How long do access tokens last?

Access tokens last 90 minutes and refresh tokens last 60 days. Cache the pair and refresh before the access token expires. See Authentication.

My credentials work in the web app, but the API returns 401. Why?

Check the Authorization header first. If it's correct, your plan may not include API access. See Troubleshooting.

Can I use EZ Texting from Claude, ChatGPT, or Cursor?

Yes, through the EZ Texting MCP server. See AI assistants & the MCP server and the setup guide.

I'm using the legacy API. Where do I start?

See Legacy API for what changed and how to move to the current API.


Did this page help you?