Core concepts
The main ideas behind the API: messages, contacts, consent, credits, and delivery.
This page explains how EZ Texting models the pieces around a message: your account and numbers, messages, contacts and groups, consent, delivery, and credits.
Your account and your numbers
Every API call is made as an EZ Texting account (your username and password, or a token created from them). Each account has a default sending number and a balance of credits, and can have more numbers (10-digit local numbers, toll-free numbers, or short codes).
Sends go out from the default number unless you pass fromNumber. If your account has a single number, you never need to specify it.
Consent, opt-in, and opt-out
Text messaging is permission-based, and the platform enforces the parts it can.
Opt-in: before you text someone, make sure they've agreed to receive messages from you, through a form, a checkbox, or by texting one of your keywords to your number. Having their number, or having sold them something, is not agreement. The use-case guides capture this as a smsConsent record stored with the booking or order. Keywords are the API-visible version of that: texting any keyword you've set up (JOIN, DEALS, VIP, whatever you've claimed) is an opt-in. EZ Texting creates the contact (source: keyword), sends your configured join message, optionally adds them to a group, and can fire a keyword.opt_in webhook.
Opt-out: when a contact replies with a standard opt-out word (STOP, UNSUBSCRIBE, QUIT, END, CANCEL, REMOVE), EZ Texting marks them optOut: true and will not deliver to that number again, even if your code sends to it. You can also opt a number out yourself with POST /v1/blocks; the API can't undo that.
Your integration should still read optOut and respect it. For example, hide the "text this customer" button in your own UI.
This is an overview, not legal advice. Check the requirements for your messages with your own legal counsel.
Messages
A message is one POST /v1/messages call: a text body, a type, optional media, optional scheduling, and one or more recipients. The response returns an id (the message ID) that you use to track it.
| Concept | What it means |
|---|---|
| SMS | Plain text. Carriers transmit text in segments of up to 160 characters. A longer message is split into segments of 152 characters each (the remaining 8 carry the User Data Header, or UDH) and put back together on the handset, but each segment costs a credit. If a message has one or more Unicode characters, such as an emoji or certain accented letters, it's sent with Unicode encoding, which cuts a single segment to 70 characters (66 per segment when split). Curly quotes are converted to straight quotes before sending. A few characters aren't supported at all: the send fails with 400 and names the character. |
| MMS | A message with media (image, video, or audio, in standard formats up to 5 MB) or a long body. An MMS can be up to 1,600 characters and costs 3 credits regardless of text length. |
messageType | Pass SMS or MMS to force a type. Omit it and EZ Texting picks: text that fits in one or two SMS segments is sent as SMS; text that would need three or more segments is sent as MMS; anything with media is MMS. Set it explicitly when the type matters (an OTP should always be SMS). |
companyName | Optional. The same as the Subject field in the web app: your business name, shown in parentheses before the text, for example (Acme Dental) Your appointment is tomorrow at 9am. Use this field or put the name in the message. |
sendAt | Omit to send now. Set an ISO 8601 timestamp with a UTC offset (2026-11-20T09:00:00-08:00) to schedule. Scheduled messages appear in GET /v1/campaign-info until they go out; DELETE /v1/messages with the message ID cancels one that hasn't gone out yet. |
A message ID looks like 128443910003. Keep it: reports, details, and deletion all key off it. It identifies the whole send; individual messages in lists carry their own IDs (see Which ID goes where).
Templates and media files
A template is saved message text with ${…} variables that EZ Texting fills from each recipient's contact record. Send one with messageTemplateId. A media file is an image, video, or audio file you upload once and attach to MMS by mediaFileId.
| Endpoint | Method | Description |
|---|---|---|
/v1/message-templates | GET | List templates |
/v1/message-templates | POST | Create a template |
/v1/message-templates/{id} | GET | Get a template |
/v1/message-templates/{id} | PUT | Update a template |
/v1/message-templates/{id} | DELETE | Delete a template |
/v1/media-files | GET | List uploaded media files |
/v1/media-files | POST | Upload a media file |
/v1/media-files/{id} | GET | Get a media file |
/v1/media-files/{id} | DELETE | Delete a media file |
Merge tags
${…} in a message or template is replaced for each recipient at send time.
| Tag | Fills in |
|---|---|
${FirstName}, ${LastName} | The contact's name. Exact capitalization: ${firstName} doesn't work. |
${custom1} … ${custom5} | The five built-in slots, while they keep their default labels. A field's tag is its label with spaces removed, so if you rename custom3 to "Last Visit" in Custom Fields, its tag becomes ${LastVisit}. |
${fieldname} | Any custom field you've created, by its label with spaces removed ("appointment date" → ${appointmentdate}). |
${URL="www.example.com"} | A shortened, click-tracked link, if your account includes the link shortener. |
- Tags are case-sensitive.
- Merge tags don't currently include the built-in
emailfield. To put an email address in a message, store it in a custom field. - A tag with no matching field, or a contact with no value for it, becomes empty text. No error is returned, so test with a real contact.
- Renaming a field's label changes its tag (and, for fields you created, its key in
values). Update templates and integrations when you rename a field.
Transactional sends vs. campaigns
The same endpoint sends both. What makes a message transactional or a campaign is why it's sent, not how many numbers it goes to:
| Transactional | Campaign | |
|---|---|---|
| Targeting | Usually toNumbers with one number | groupIds (one or more contact groups), a toNumbers array, or both in the same call |
| Trigger | Something a person did: booked, ordered, logged in | A decision you made: a promotion, an announcement |
| Personalization | Build the text in your code | Optional ${FirstName}-style variables, filled in per contact |
| Typical volume | One at a time, many times a day | A few to thousands of recipients in one call |
A group send is one API call and one message ID, however many contacts are in the group.
Contacts, groups, and fields
A contact is a phone number plus whatever you know about the person. The phone number is the unique key: creating a contact with an existing number updates it rather than failing.
| Field | Notes |
|---|---|
phoneNumber | The identifier for GET and DELETE. Store it as 11 digits, country code first (15551234567). |
firstName, lastName | Up to 20 characters each. Available as ${FirstName} and ${LastName} in messages and templates (capitalized exactly like that). |
email, note | Free-form; both allow more than 20 characters. The built-in email field isn't currently available as a merge tag. |
custom1 … custom5 | Five built-in free-form slots, 20 characters each. Handy for an order ID, a store code, a plan name, but not a URL. Their merge tags are ${custom1} … ${custom5} while they keep their default labels (see Merge tags). |
values | Everything beyond the five slots. You can define as many custom fields as you need with POST /v1/contact-fields (each has a name, a label, and a type: Text or Date). Set them on a contact as a map keyed by field name ("values": {"appointmentdate": "11-21-2026", "provider": "Dr. Lee"}). Values are strings of up to 20 characters, Date values are MM-dd-yyyy, and "" or null clears a value. Responses include custom1 … custom5 both at the top level and inside values. |
source | How the contact got there: API, web widget, upload, keyword, and so on. Read-only. |
optOut | Read-only. true means EZ Texting will not deliver to this number. |
A group is a named set of contacts (names up to 25 characters). Groups work like saved filters over your contact list: each contact exists once, however many groups it's in. A message sent to several groups reaches each contact once, even if they're in more than one of those groups. Groups are what you send campaigns to and what you attach keywords to, and adding a contact to a group can start an Automation Workflow. Add a contact to groups on upsert with groupIdsAdd (and remove with groupIdsRemove), or manage membership directly on the group.
Contact fields are limited to 20 characters (email and note allow more).
For bulk work, POST /v1/contacts/batch creates or updates many contacts in one call and can add them to (or remove them from) groups in the same request.
Delivery: what happens after 201
201A 201 Created means EZ Texting accepted the message. From there each recipient is briefly queued until it ends up delivered, bounced (rejected downstream, for example by the carrier), or not_sent (never attempted: opted out, invalid, or out of credits by the time a scheduled message went out).
Two endpoints tell you where things stand:
GET /v1/message-details/{id}shows what you sent: type, from number, send time, recipient count, credits used.GET /v1/message-reports/{id}shows what happened: counts and percentages for each delivery outcome, engagement (replied, opted out, no action), and link clicks. The/responses/delivery,/responses/engagement, and/responses/linksub-resources list the individual contacts behind each number.
Delivery is usually seconds, but can be longer depending on carrier throughput for your number type, carrier congestion, queue depth on large sends, or review holds. Treat queued as "not final yet". Delivery throughput is a property of your number and registration; it is unrelated to the API request limit (see Rate limits).
Credits
Credits are the unit of billing. Sending consumes them; the balance is readable at GET /v1/credits:
planCredits | Included in your plan; reset each period as defined by the plan (monthly or annual, with rollover on some plans). |
anytimeCredits | Purchased separately; valid for one year from purchase. Used after plan credits run out. |
totalCredits | The sum: what you can actually send with right now. |
GET /v1/message-details/{id} reports the credits a specific message consumed. If the account doesn't have enough credits, a send is rejected with a 400 with INSUFFICIENT_BALANCE; a scheduled message that comes due after credits run out lands in not sent. Buy more with POST /v1/credits/purchase or in the web app. To avoid running out, we recommend setting up auto-refill on your account in the web app.
Webhooks
Rather than polling for new inbound texts, subscribe a webhook and EZ Texting will POST to your URL when things happen. Events today:
| Event | Fires when |
|---|---|
inbound_text.received | A contact texts your number (any message, including replies and STOP). |
keyword.opt_in | A contact opts in by texting one of your keywords. |
contact.created | A new contact is created in your account. |
Each subscription can carry a secret; callbacks are then signed with an HMAC-SHA256 in the X-Signature-256 header so you can verify they came from EZ Texting. Details in Webhooks.
Conversations
A conversation is the two-way thread between one of your numbers and one contact: every inbound and outbound message, with unread counts and archive state. GET /v1/conversations lists threads (filter by unread, archived, opt status, or text with filters[…]); GET /v1/conversations/conversation/USERNUMBER/{contactNumber} returns the messages in one. This is the model behind a support inbox. See Two-way conversations.
Automation workflows
EZ Texting Workflows are no-code automations built in the web app (and through the MCP server): drip sequences, reply-driven surveys, appointment confirmations, re-engagement flows. The API is a natural way to start them. A workflow begins with a trigger, and several triggers fire on things your integration already does:
| Workflow trigger | How the API fires it |
|---|---|
| Contact added to a group | POST /v1/contacts or /v1/contacts/batch with groupIdsAdd, or POST /v1/contact-groups/{id}/contacts. The trigger can filter by group and by contact source (API), so a workflow can react only to contacts your code adds. |
| Date field on a contact | Set a date custom field (an appointment date, a renewal date) via values; a workflow scheduled relative to that field ("2 days before") picks it up. |
| External webhook | Your system POSTs to the workflow's own URL with a phone number and any variables you want to use in the messages. |
| Inbound message / keyword | Not fired by the API, but when a workflow collects a reply, the message is still visible via GET /v1/conversations and your inbound_text.received webhook. |
The pattern: let the API own data (contacts, fields, group membership) and let a workflow own the conversation logic. Change the messaging in the workflow editor without a deploy. See the Workflows section of the web app, or build them conversationally through the MCP server.
IDs, pagination, and dates
- IDs are strings. Message, template, media, group, and webhook IDs are numeric-looking but returned as strings. Don't parse them. (Keyword IDs, and the group IDs inside keyword settings, come back as numbers.)
- Lists are paged.
pageis 0-based;sizeis one of 10, 20, 50, 100, 200. Responses carrycontent,totalElements,totalPages, andnumberOfElements. See Pagination. - Empty fields are omitted. A field with no value is left out of the response rather than returned as
null. - Dates are ISO 8601. Responses are UTC (
...Zor...+00:00). When you send a date (sendAt, date filters), include an explicit offset so there's no ambiguity about your timezone. Two exceptions useMM-dd-yyyy:Datecustom field values and theGET /v1/campaign-infodate filters.
Which ID goes where
There are two IDs:
- Message ID, like
128443910003: theidreturned byPOST /v1/messages. It covers every recipient of that send. Use it for message reports, message details, cancelling a scheduled send, andfilters[messageId][eq]onGET /v1/messages. Messages tied to a send, including replies to it, carry it asmessageGroupId. SoGET /v1/messages?filters[messageId][eq]=<message ID>returns the send and the replies to it. Theidin an inbound text webhook is also a message ID: the send the text is replying to, if there is one. - Individual message ID, like
EZ_128443910003_5064631149003_15551234567: theidof one individual message inGET /v1/messagesor a conversation thread. You only need it to mark messages read or unread (idList).
Using the wrong one fails silently: read/unread with a message ID instead of individual message IDs returns 200 and changes nothing. Conversations have no ID of their own; address them by userNumber and contactNumber.
Related
- Quickstart — your first send in five minutes.
- Send, track & receive — delivery reports and webhooks, the rest of the lifecycle.
- Phone number formatting — the one input that causes the most 400s.
- Compliance — consent, 10DLC, and content rules.
Try Troubleshooting, check status.eztexting.com, or contact support.
Updated about 18 hours ago