Sample API Requests to Send Personalized SMS with a Coupon Code (Mobile Text Alerts API) - 2026

This guide shows how to build sample API requests to send personalized SMS with a coupon code using the Mobile Text Alerts API. It covers the core /v3/send request, required fields, and personalization patterns that enable you to deliver unique coupon messages to each subscriber in a single API call.

By the end, you’ll know how to move from a basic test message to production-ready coupon campaigns with proper personalization, tracking, and compliance in place.

Note: Response formats can vary by endpoint. Some responses include additional status or message fields, so always refer to the example response shown in each endpoint’s documentation.

Quickstart: Send personalized coupon SMS via API

To send a coupon SMS, generate an API key, include it as a Bearer token in the Authorization header, and make a POST request to the /v3/send endpoint.

Below are two production-ready requests you can copy and adapt. The first covers a basic coupon send. The second shows per-recipient personalization using variables.

Example 1: Send a basic coupon SMS

This request sends the same coupon message to multiple subscribers and includes required opt-out language.

{
  "subscribers": [15551234567, 15559876543],
  "message": "Thanks for signing up! Use code SAVE20 for 20% off your next purchase. Reply STOP to end."
}

What’s happening in this request:

• POST /v3/send is the endpoint used for all outbound SMS sends
• The Authorization header passes your API token using the Bearer scheme
• subscribers accepts an array of phone numbers as integers or strings
• message contains the SMS body, including opt-out copy such as “Reply STOP to end”

This pattern works well for broadcast-style coupon campaigns where every recipient receives the same offer.

Example 2: Send personalized coupon SMS using variables

This request personalizes each message using variables defined per phone number.

{
  "subscribers": [15551234567, 15559876543],
  "message": "Hi {{firstName}}! Here's your exclusive coupon: {{couponCode}}. Enjoy {{discount}} off! Reply STOP to end.",
  "properties": {
    "15551234567": {
      "firstName": "Sarah",
      "couponCode": "SARAH20",
      "discount": "20%"
    },
    "15559876543": {
      "firstName": "Michael",
      "couponCode": "MIKE15",
      "discount": "15%"
    }
  }
}

How personalization works:

• Variables use the {{variableName}} syntax inside the message body
• The properties object maps each phone number to its variable values
• During send, variables are replaced per recipient

Each subscriber receives a distinct message. For example:

• Sarah receives: “Hi Sarah! Here's your exclusive coupon: SARAH20. Enjoy 20% off!”
• Michael receives: “Hi Michael! Here's your exclusive coupon: MIKE15. Enjoy 15% off!”

Prerequisites

Before sending personalized coupon SMS campaigns, ensure the following basics are in place: an API key, a verified connection to the API, at least one test subscriber, and, depending on your account, permission to send custom message content.

Generate and use your API key

An API key authenticates your application with Mobile Text Alerts. You generate your API key from the web dashboard:

1. Open Settings from the three-dot menu in the top-right.
2. Navigate to Developer (or Developer Resources).
3. Click Generate a New Key, assign a descriptive name, and confirm.

The key is displayed only once. Copy it immediately and store it securely, ideally in a secrets manager. In all API requests, the key is passed as a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE

Every request shown in this guide assumes that the header is present and valid.

Verify your API key with a simple call

Before sending messages, it’s worth confirming two things:

• The API key is valid
• Your application can reach the API

You can do this by calling the verification endpoint:

GET /v3/auth/verify-api-key
Authorization: Bearer YOUR_API_KEY_HERE

A successful response looks like this:

{
  "message": "API Key verified",
  "data": {
    "name": "Your Account Name",
    "email": "you@example.com"
  }
}

If the header is missing or the key is invalid, the API returns an authorization error (for example, 401 Unauthorized). This usually points to a copied token, a revoked key, or a key that was never generated.

Add a test subscriber

To confirm end-to-end delivery, you’ll need to add at least one subscriber to your account.

Subscribers are created or updated via POST /v3/subscribers:

• You must provide at least one contact channel: a phone number or an email
• If the contact already exists, the API updates the subscriber instead of creating a duplicate

A minimal test subscriber request might look like this:

{
  "firstName": "Sarah",
  "number": 15551234567
}

On success, the API returns a confirmation such as "Subscriber created successfully." The response also includes the subscriber’s normalized E.164 phone number (e164Number), which Mobile Text Alerts derives automatically.

From that point on, you can reference this subscriber in your /v3/send requests.

The same endpoint also supports richer data, such as last name, group assignments (groupIds), and custom fields (subscriberFields), but none of that is required for initial testing.

Trial accounts, verification, and custom content

Sending capabilities vary by account status. For compliance and deliverability reasons:

• Trial accounts and some unverified setups may be limited to template-only sending
• In that mode, /v3/send relies on a templateId (and sometimes a linkId) instead of free-form message text

To send custom coupon messages with inline variables, you typically need:

• A non-trial account
• A verified sending number or long code configured on your account

Once approved, you can send messages using raw message text, personalize them with Liquid-style variables like {{firstName}} and {{couponCode}}, and rely on the same /v3/send endpoint for both basic and highly personalized campaigns.

Understanding the send request

The /v3/send endpoint is the primary endpoint for sending SMS and MMS, including personalized coupon campaigns. Conceptually, every send combines three things:

• What the subscriber sees (content)
• Who receives it (recipients)
• How it’s tracked, timed, or repeated (delivery and metadata)

Once you understand how those pieces fit together, the payload becomes easier to reason about, whether you’re sending a one-off test message or a scheduled, personalized campaign at scale.

At a glance, every /v3/send request is built from the same set of field groups.

You won’t use all of them in every send, but knowing what each group controls makes it easy to assemble or modify a payload without guesswork.

Required fields: the non-negotiables

Every /v3/send request must satisfy two conditions.

First, the request must include content. You can provide this as raw message text (message), a saved template reference (templateId), or an image attachment (image). At least one of these is required for the request to be valid.

Second, the request must specify recipients. This can be done by listing phone numbers or emails (subscribers), internal subscriber IDs (subscriberIds), one or more groups (groups), an account-wide send (allSubscribers), or an existing conversation (threadId). At least one recipient field must be present.

If either the content or the recipients are missing, the request is rejected. A simple pre-send check helps avoid most errors: do I have content, and do I have recipients? Everything else builds on top of that foundation.

How personalization works in Mobile Text Alerts

Mobile Text Alerts treats 1:1 personalization as a core capability. A single send request can deliver messages to each subscriber, with each subscriber seeing their own name, coupon code, link, and expiry without loops or multiple API calls.

The basic personalization pattern

Personalized sends follow a consistent pattern you can reuse across campaigns.

Put variables into your message content: Write your SMS using Liquid-style placeholders such as {{firstName}}, {{couponCode}}, {{link}}, or {{expiresAt}}. These act as markers that will be replaced per recipient.

Example message:

Hi {{firstName}}! Use code {{couponCode}} before {{expiresAt}}.

Pass per-recipient values in the properties field: In the request body, include a properties object. Each key maps to a subscriber (most commonly their phone number), and each value contains the data used to resolve variables for that person.

"properties": {
  "15551234567": {
    "firstName": "Sarah",
    "couponCode": "SARAH20",
    "link": "https://example.com/checkout?c=SARAH20",
    "expiresAt": "Jan 30"
  }
}

When the API processes the request, each variable is replaced with the corresponding subscriber value. One request produces many distinct messages.

Common personalization variables

These variables show up frequently in coupon and lifecycle campaigns:

You can add additional variables such as {{discount}}, {{productName}}, or {{lastOrderTotal}} as long as each variable has a corresponding value in properties for the subscribers you’re targeting.

Complete example: One request, many unique coupon SMS

The request body below shows how a single send can generate multiple personalized messages. Use any HTTP client that fits your stack.

{
  "subscribers": [15551234567, 15559876543, 15552468101],
  "message": "Hi {{firstName}}! Enjoy {{discount}} off with code {{couponCode}}. Offer ends {{expiresAt}}. Redeem here: {{link}} Reply STOP to end.",
  "properties": {
    "15551234567": {
      "firstName": "Sarah",
      "discount": "20%",
      "couponCode": "SARAH20",
      "expiresAt": "Jan 31",
      "link": "https://example.com/checkout?c=SARAH20"
    },
    "15559876543": {
      "firstName": "Michael",
      "discount": "15%",
      "couponCode": "MIKE15",
      "expiresAt": "Jan 28",
      "link": "https://example.com/checkout?c=MIKE15"
    },
    "15552468101": {
      "firstName": "Jessica",
      "discount": "25%",
      "couponCode": "JESS25",
      "expiresAt": "Feb 2",
      "link": "https://example.com/checkout?c=JESS25"
    }
  }
}

All of this is driven by a single /v3/send request. Teams typically keep this structure fixed and vary only the message copy, variables, and optional metadata based on the event that triggered the send.

💡 Once you understand this pattern, the same request shape applies across flash sales, abandoned cart reminders, order confirmations, and post-purchase incentives. Only the values change.

Recipe 1 (primary): Personalized coupon code SMS

This recipe shows a complete starting pattern for coupon campaigns. It begins with a shared code sent to everyone, then transitions to a personalized version in which each subscriber receives a unique coupon.

Layer A: Same coupon for everyone

When to use this: A single shared coupon code works well when speed and simplicity matter more than individual tracking:

• Broad promotions such as sitewide discounts, seasonal offers, or flash sales
• Campaigns where code sharing is acceptable (for example, a public FLASH25 code)
• Situations where attribution happens at the campaign level rather than per subscriber

In these cases, the API payload stays small: one message, one shared code, and a list of phone numbers in subscribers.

The /v3/send endpoint accepts phone numbers as integers or strings and creates subscribers automatically for new numbers. You can test quickly without syncing your entire contact database first.

Layer B: Unique coupon per recipient

When to use this: Per-recipient coupon codes make sense when control and attribution matter:

• Single-use codes that must not be shared
• High-value offers where misuse would be costly
• Campaigns where you need to know exactly which customer redeemed which offer

Mobile Text Alerts supports this pattern through the properties field. The message includes variables such as {{firstName}} and {{couponCode}}, while properties supply the values for each subscriber. One request still produces many unique messages.

Structurally, this request is almost identical to the shared-code version:

• Same /v3/send endpoint is used
• Recipients are still specified through the subscribers field
• The request must still include both content and recipients to be valid

What changes:

• The message field introduces Liquid-style variables such as {{firstName}} or {{couponCode}} instead of fixed text
• A properties object is added to supply per-recipient values for those variables

In practice, coupon codes, links, and other personalized values are generated upstream and injected into properties at send time. You still make a single API request, but each subscriber receives a message rendered with their own data.

This allows teams to move from shared promotions to tightly controlled, per-recipient offers without changing their integration or send logic.

Optional power-ups

Beyond basic sends, the API includes a set of power-ups that help teams run large or high-stakes campaigns with fewer surprises. These features focus on safety, predictability, and operational clarity, especially useful when sends are automated or closely reviewed.

Idempotency: Protect against double-sending

When a campaign runs via background jobs or retry logic, network timeouts can cause the same request to be submitted multiple times. Adding an X-Request-Id header can help recognize repeated attempts as a single send.

How it works:

• You generate a unique X-Request-Id per campaign or send attempt (for example, spring-sale-2026-001)
• The /v3/send endpoint treats requests with the same ID as a single operation
• If a request with that ID was already processed, a retry can return 409 Conflict instead of sending messages again

This is especially useful when your job runner automatically retries failed HTTP calls. You can retry aggressively without risking duplicate blasts or unexpected spend.

Preflight: Validate recipients

Before moving on to cost estimation or scheduling, it’s worth confirming that the people you plan to message can receive text messages. The /v3/send/validate-recipients endpoint provides a preflight check for this exact step.

Instead of inferring recipients from groups or rules, you pass a concrete list of phone numbers or emails, optionally paired with anexternalId, and the API evaluates each entry. This validation is typically run after any groups or other sources have been expanded into a final recipient list.

Typical flow:

• Submit a list of recipients to /v3/send/validate-recipients
• Optionally enable unsubscribe validation
• Review valid and invalid recipients

The response distinguishes valid recipients from invalid recipients and returns error codes (e.g., malformed numbers or opt-outs). Teams use this step to reduce compliance risk, catch data issues early, and produce accurate “ready-to-send” counts before launch.

Preflight: Estimate message cost

Once your recipient list is finalized, the next question is: how much will the campaign cost? Teams often need visibility into costs for planning and approval. The /v3/send/cost endpoint lets you estimate SMS or MMS cost without sending a message.

This endpoint is intentionally scoped to a single-recipient cost check. Instead of mirroring a full /v3/send payload, you provide only the fields that influence billing.

How it works:

You call POST /v3/send/cost with:

• to (required): The destination phone number
• from (optional): The sending number
• message (optional): The message body
• isMMS (optional): Whether the message should be treated as MMS

The API evaluates message length, encoding, and format, then returns an estimated cost of sending the message to a single recipient.

What the response includes:

The response focuses on billing and segmentation details, such as:

• messageCount: How many message units would be sent
• messageCredits: Credits required for the send
• carrierFee: Carrier-level charges, when applicable
• totalCost: Combined estimated cost

Teams typically multiply this per-message estimate by the recipient count to plan campaign budgets, compare short vs. long copy, and avoid surprises from multi-segment messages.

Shorten links and reduce character count

SMS billing is segment-based, so long URLs or verbose copy can cause messages to split across multiple segments. The /v3/send/shorten-message helper endpoint lets you optimize message text before sending.

Typical use:

• Submit a draft message that includes all URLs and variables
• The endpoint shortens links and rewrites the message where applicable
• It returns the optimized text (for example, data.shortenedMessage)

Because the response does not include segment or credit counts, teams pair this step with /v3/send/cost to understand how the shortened message affects billing.

This is particularly useful when:

• You’re sending to large lists and need tighter cost control
• Marketing wants richer copy without triggering multi-segment SMS
• You’re comparing multiple message versions and balancing performance with spend

Used together, /send/shorten-message and /send/cost help teams control message length and cost while keeping their core /v3/send integration unchanged.

Tracking delivery and outcomes

After sending coupon campaigns, the next question is whether messages are reaching subscribers and how reliably. Mobile Text Alerts supports both historical reporting and real-time delivery status, so teams can investigate issues, monitor live sends, and review performance over time.

Historical reporting with GET /v3/deliveries

For analytics, audits, and post-campaign reviews, the GET /v3/deliveries endpoint returns a log of sent messages, including their most recent delivery state.

Each record includes fields such as:

• messageId
• externalId
• message
• status
• date
• to and from
• carrier
• type (for example, sms or mms)

You can filter results by:

• Status: sent, delivered, undelivered, undeliverable, unknown, or rejected
• Date range using filters[startDate] and filters[endDate] in YYYY-MM-DD format
• Type to separate SMS coupon traffic from other message categories

Teams commonly use this endpoint to build dashboards, export data into BI tools, and answer questions like:

• What percentage of last week’s flash sale messages were delivered?
• Which carriers account for most delivery failures?

Because this endpoint reflects settled data, it is best suited for reporting and analysis rather than for live monitoring.

Real-time updates with delivery-status webhooks

For live operations, like support workflows, alerting, or real-time dashboards, polling /v3/deliveries isn’t ideal. Delivery-status webhooks deliver push notifications whenever Mobile Text Alerts receives updated delivery information from carriers.

These events fire throughout the message lifecycle, from initial send through final outcomes such as delivery or rejection. Each event includes a JSON payload describing the message, its current status, and related metadata so your system can react immediately.

To use delivery-status webhooks:

1. Expose an HTTPS endpoint that accepts POST requests and returns HTTP 200 on success
2. Register that endpoint using the /v3/webhooks API

Registering a delivery-status webhook

Webhooks are configured by calling POST /v3/webhooks and specifying the event type, destination, and security options. A minimal webhook registration payload looks like this:

{
  "event": "delivery-status",
  "url": "https://your-app.example.com/webhooks/delivery-status",
  "secret": "your-shared-secret-value",
  "sendAlertEmail": true,
  "alertEmail": "alerts@example.com"
}

Key fields explained:

• event: Set to "delivery-status" to receive delivery updates. Other supported events include message-reply, message-send, and number-opt-in
• url: A public HTTPS endpoint where delivery events will be sent as POST requests
• secret: A shared secret used to sign webhook payloads so your application can verify authenticity (for example, via HMAC validation)
• sendAlertEmail: Enables email notifications when webhook deliveries repeatedly fail
• alertEmail: Specifies where failure alerts should be sent when email alerts are enabled

What can you do with real-time delivery events?

Once registered, your application can:

• Update in-app delivery indicators or live dashboards as statuses change
• Trigger follow-up actions when messages fail or succeed, such as retries, support tickets, or alternate channels
• Store a complete delivery timeline per message, complementing the “latest status” snapshot returned by /v3/deliveries

Used together, historical reporting and delivery-status webhooks give teams both hindsight and real-time visibility, covering audits, debugging, and operational response without relying on polling.

Common errors and troubleshooting

This section maps common HTTP errors to likely causes and quick checks, followed by answers to common personalization, message length, and webhook issues that arise when teams go live.

HTTP errors and what to check:

Why did my message show raw {{variable}} text?

If a subscriber sees {{firstName}} or {{couponCode}} literally, the templating engine didn’t find a value to substitute.

Common causes:

• Key mismatch between recipients and properties:The keys in properties must match how recipients are identified. If subscribers use 15551234567 but properties use a different format (for example, +1-555-123-4567), the lookup fails.
• Missing variable in properties:Every variable used in message or a template must exist in that subscriber’s data. If {{couponCode}} is missing for one person, only that message will show the raw placeholder.
• Typos or case differences: {{FirstName}} and {{firstName}} are treated as separate variables.

💡 A quick way to debug is to send the payload to a single test number and inspect the rendered SMS to see which variables didn’t resolve.

Why did my message split into multiple segments?

SMS is delivered in segments, and longer messages may be split into multiple billable parts, even if they appear as a single message on modern devices.

High-level rules:

• GSM-7 messages support up to 160 characters per segment; concatenated messages use approximately 153 characters per segment.
• Messages with Unicode characters, like emoji or non-Latin scripts, drop to 70 characters per segment, or about 67 when concatenated.
• Long URLs and required opt-out text consume characters.

You can reduce segment count by shortening links or using a helper like /send/shorten-message to preview optimized text and segment counts. And, avoid emojis or uncommon symbols when character efficiency matters.

Why might a webhook fail and how do alerts help?

Webhooks send real-time events, just like delivery-status, message-reply, or message-send, to your server via HTTP POST. If delivery fails, downstream events won’t be recorded.

Common failure reasons:

• Non-200 responses: Your endpoint must return HTTP 200. Any 4xx or 5xx response is treated as a failure.
• Endpoint unreachable: Incorrect URLs, firewall rules, TLS issues, or slow response times can all block delivery.
• Signature or secret validation errors: If you configured a webhook secret, your handler must validate it correctly. Incorrect validation logic can cause valid events to be rejected.

To surface these issues early, webhook registration supports an alertEmail field. When deliveries repeatedly fail, alerts are sent so teams can catch issues such as expired TLS certificates, route changes, or recent deployment bugs before they affect reporting or automation.

Compliance and best practices

Here’s how you can keep coupon campaigns aligned with common SMS expectations.

Include clear opt-out instructions

Promotional SMS messages should clearly explain how recipients can opt out of future messages. A short line such as “Reply STOP to end” is the most widely recognized pattern and is expected by carriers in both initial and follow-up campaigns.

Message only subscribers who have opted in

Send coupon messages only to people who have explicitly consented to receive them. Consent may come from a signup form, checkout checkbox, SMS keyword, in-person interaction, or another clear opt-in flow but it should always be intentional and documented.

Consider account status and sending limits

Sending behavior is also shaped by account configuration. Trial or unverified accounts may be limited to template-only messaging, while verified accounts can send custom text with inline variables.

Before launching coupon campaigns, confirm:

• Your sending number or long code is approved
• Your account supports free-form message content
• Your use case aligns with carrier and platform guidelines

This avoids last-minute blocks when moving from testing to production.

Review higher-risk campaigns when in doubt

Large sends, high-value promotions, or automated coupon workflows deserve extra scrutiny. Reviewing opt-in flows, message copy, and frequency with internal stakeholders or legal and compliance advisors when appropriate helps prevent avoidable issues later.

As a baseline, include opt-out language in every promotional message, text-only opt-in subscribers, and confirm account readiness before scaling. Everything else builds on those fundamentals.

A practical foundation for SMS coupon campaigns

Sample API requests to send personalized SMS with a coupon code using the Mobile Text Alerts API follow a consistent structure: define your message, specify recipients, and pass personalization data through properties. Once that pattern is clear, most campaigns differ only in copy and variables.

Mobile Text Alerts is built around this model. The same /v3/send request supports shared promotions, per-recipient coupon codes, lifecycle messaging, and high-volume campaigns while keeping delivery, retries, and reporting predictable as you scale.

If you want to test this flow end-to-end, you can start a free trial of Mobile Text Alerts and send your first personalized coupon SMS with the same API patterns shown in this guide.

Author bio

Manya is a B2B SaaS writer specializing in SME-led, product-driven content across ecommerce, customer experience, and workflow automation. She can work closely with a company’s product team to translate complex systems into clear, practical documentation and guides that support real-world use cases. When not writing, she studies how SaaS teams structure messaging to improve product adoption and long-term use.