Sending SMS and MMS

Send SMS and MMS messages through the TextGrid API, then track their delivery using status callbacks.

Before you begin

You need:

Your TextGrid Account SID and Auth Token.
A sending phone number registered and enabled for your account.
A recipient phone number in E.164 format, such as +12025550101.
A public callback endpoint if you want delivery-status notifications.

For traffic requiring 10DLC registration, complete the required campaign approval and phone-number attachment first. Creating a campaign or submitting an attachment request does not enable sending by itself. Attachment usually completes within a few minutes but can take up to a few days, especially over a weekend or legal holiday. See 10DLC Registration.

The phone numbers, URLs, and identifiers in this guide are fictitious. Replace them with your own values before sending a request.

Authenticate your request

Base64-encode your literal AccountSid:AuthToken pair and send it in the Authorization header:

Authorization: Bearer YOUR_BASE64_ENCODED_CREDENTIALS

Make requests from your server and keep credentials private. See Getting Started with TextGrid for setup instructions.

Send an SMS

Send a POST request with a JSON body to:

POST https://api.textgrid.com/2010-04-01/Accounts/YOUR_ACCOUNT_SID/Messages.json
Content-Type: application/json
Authorization: Bearer YOUR_BASE64_ENCODED_CREDENTIALS

Example body:

{
  "from": "+12025550100",
  "to": "+12025550101",
  "body": "Your appointment is confirmed for tomorrow at 10 AM.",
  "statusCallback": "https://example.com/webhooks/message-status"
}

Field	Description
`from`	Your sending phone number. Required.
`to`	The recipient phone number. Required.
`body`	Message text. Required when no media is supplied.
`statusCallback`	Optional URL for delivery-status notifications for this message.

Keep phone numbers as strings, including the leading +. Use the field names shown above; statusCallback has a lowercase s and no capital B.

Send an MMS

Use the same endpoint and include a mediaUrl array:

{
  "from": "+12025550100",
  "to": "+12025550101",
  "body": "Here is the image you requested.",
  "mediaUrl": [
    "https://example.com/media/appointment-details.jpg"
  ],
  "statusCallback": "https://example.com/webhooks/message-status"
}

mediaUrl is an array of URL strings, even when sending one media item. Supply URLs from which the media can be retrieved; do not put Base64 file content in this field.

You must supply either a nonempty body or a nonempty mediaUrl array. A media-only message can omit body. Media acceptance depends on the destination and provider; consult the API Reference and your account's supported media requirements.

Save the message identifier

Check the HTTP status and response body. For a successful send request, save the returned sid with your application's message record. Use it to match later status callbacks and retrieve the message.

Useful response fields include:

Field	Description
`sid`	TextGrid message identifier.
`status`	Message status at the time of the response.
`from`, `to`	Sender and recipient.
`body`	Message text.
`num_segments`	Segment count, represented as a string.
`num_media`	Media count, represented as a string.
`error_code`, `error_message`	Error information when present.

A successful API response does not confirm delivery to the recipient. Track subsequent delivery results using callbacks or message retrieval.

Track delivery status

If you supply statusCallback in the send request, TextGrid sends status notifications to that URL using POST. Otherwise, it uses the sending phone number's configured status callback and method, when available.

POST notifications contain application/x-www-form-urlencoded fields, not JSON. A number-level callback configured for GET receives query parameters instead.

Use MessageSid to match the callback to the sid saved from the send response. Read MessageStatus or SmsStatus for the reported status. Other fields include SmsSid, To, From, and Segments. SmsStatusDetail is included when additional mapped error detail is available.

Before processing a callback, verify its X-TextGrid-Signature using your account's Webhook Secret. This is separate from your API Auth Token. Capture the raw POST body before parsing the form fields.

Return HTTP 200, 201, 202, or 204 to acknowledge a delivery-status callback. The delivery-status sender makes one request without an automatic retry loop or fallback. Make processing tolerant of duplicate events.

See Messaging Webhooks for the callback contract and Verifying Webhook Signatures for verification samples.

Retrieve a message

Use the saved message SID to retrieve its current record:

GET https://api.textgrid.com/2010-04-01/Accounts/YOUR_ACCOUNT_SID/Messages/YOUR_MESSAGE_SID.json
Authorization: Bearer YOUR_BASE64_ENCODED_CREDENTIALS

Use message retrieval to check current status or reconcile a missing callback. Do not send another message merely because a delivery callback has not arrived.

Handle errors and retries

Check the HTTP status first. Error bodies vary and can be empty; do not assume every error contains the same property names or a numeric error code. Keep the HTTP status and response body when investigating a failure, while protecting credentials and customer information.

When a request is rejected, correct the reported issue before submitting it again. Check the sending account, phone-number eligibility, campaign attachment, recipient, and message or media content as applicable.

If the request times out or the connection closes before you receive a response, the outcome may be uncertain: the message might already have been accepted. Check message records and available callbacks before retrying. Sending the same POST request again can create another message and result in duplicate delivery and charges.