Order & shipping notifications

Text customers order and shipping updates.

Order and shipping updates keep customers informed from checkout to delivery. They work best when they're timely, specific, and expected.

You still need consent

A purchase isn't permission to text. Capture a "text me order updates" opt-in at checkout and store it. See Compliance.

This guide maps order lifecycle events to messages and shows two ways to send them: inline text built in your code (the default for anything order-specific) and templates with variables that EZ Texting fills in per contact, which fit batch sends where each contact has exactly one current value.

When to use this guide

Use it when…Use something else when…
An event in your order system (placed, shipped, delivered, delayed) should send that customer a text.You're promoting something to customers → Campaigns to a group
You're sending a verification code → One-time passcodes

What you'll build

  1. A mapping from order events to message copy.
  2. An inline send for simple notifications.
  3. A template-based send that pulls the order ID and tracking link from the contact record.
  4. An MMS "it's here!" message with a product photo, and a look at who clicked the tracking link.

Map events to messages

Not every event deserves a text. Pick the ones a customer would ask about if they didn't hear:

Order eventSend?Example copy
Order placedYes(Acme) Thanks, Jane! Order #A1234 is confirmed. We'll text you when it ships.
Payment failedYes(Acme) We couldn't process payment for order #A1234. Update your card: https://acme.co/p/A1234
ShippedYes(Acme) Order #A1234 shipped! Track it: https://acme.co/t/A1234
Out for deliveryYes(Acme) Order #A1234 is out for delivery today.
DeliveredYes (MMS optional)(Acme) Order #A1234 was delivered. Enjoy!
DelayYes(Acme) Order #A1234 is running late — new ETA is Fri, Nov 21. Sorry about that.
Picked, packed, label printed…NoInternal milestones.

Every message names the company (companyName does this for you), states the order, and uses a short URL for anything with a link. Include the opt-out reminder (Reply STOP to opt out) on at least the first message in a sequence.


Option A: Inline text (default)

Build the string in your code and send it. For order-specific details (order number, tracking link, ETA), this is the right default: the data lives with the order, not with the contact, so two orders for the same customer can't collide.

curl -X POST https://a.eztexting.com/v1/messages \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumbers": ["15551234567"],
    "companyName": "Acme",
    "message": "Order #A1234 shipped! Track it: https://acme.co/t/A1234",
    "strictValidation": true
  }'
import os
import requests

auth = (os.environ["EZTEXTING_USERNAME"], os.environ["EZTEXTING_PASSWORD"])

COPY = {
    "placed":    "Thanks, {first}! Order #{order} is confirmed. We'll text you when it ships. Reply STOP to opt out.",
    "shipped":   "Order #{order} shipped! Track it: {tracking}",
    "out":       "Order #{order} is out for delivery today.",
    "delivered": "Order #{order} was delivered. Enjoy!",
    "delayed":   "Order #{order} is running late — new ETA is {eta}. Sorry about that.",
}

def notify(order, event):
    resp = requests.post(
        "https://a.eztexting.com/v1/messages",
        auth=auth,
        json={
            "toNumbers": [order.phone],
            "companyName": "Acme",
            "message": COPY[event].format(
                first=order.first_name, order=order.number,
                tracking=order.tracking_url, eta=order.eta_display,
            ),
            "strictValidation": True,
        },
        timeout=30,
    )
    resp.raise_for_status()
    order.log_notification(event, resp.json()["id"])
const credentials = Buffer.from(
  `${process.env.EZTEXTING_USERNAME}:${process.env.EZTEXTING_PASSWORD}`
).toString("base64");

const COPY = {
  placed:    (o) => `Thanks, ${o.firstName}! Order #${o.number} is confirmed. We'll text you when it ships. Reply STOP to opt out.`,
  shipped:   (o) => `Order #${o.number} shipped! Track it: ${o.trackingUrl}`,
  out:       (o) => `Order #${o.number} is out for delivery today.`,
  delivered: (o) => `Order #${o.number} was delivered. Enjoy!`,
  delayed:   (o) => `Order #${o.number} is running late — new ETA is ${o.etaDisplay}. Sorry about that.`,
};

async function notify(order, event) {
  const res = await fetch("https://a.eztexting.com/v1/messages", {
    method: "POST",
    headers: { Authorization: `Basic ${credentials}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      toNumbers: [order.phone],
      companyName: "Acme",
      message: COPY[event](order),
      strictValidation: true,
    }),
  });
  if (!res.ok) throw new Error(`EZ Texting ${res.status}`);
  const { id } = await res.json();
  await order.logNotification(event, id);
}
<?php
const COPY = [
    'placed'    => 'Thanks, %1$s! Order #%2$s is confirmed. We\'ll text you when it ships. Reply STOP to opt out.',
    'shipped'   => 'Order #%2$s shipped! Track it: %3$s',
    'out'       => 'Order #%2$s is out for delivery today.',
    'delivered' => 'Order #%2$s was delivered. Enjoy!',
    'delayed'   => 'Order #%2$s is running late — new ETA is %4$s. Sorry about that.',
];

function notify(Order $order, string $event): void {
    $message = sprintf(COPY[$event], $order->firstName, $order->number, $order->trackingUrl, $order->etaDisplay);

    $ch = curl_init("https://a.eztexting.com/v1/messages");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_USERPWD => getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"),
        CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
        CURLOPT_POSTFIELDS => json_encode([
            "toNumbers" => [$order->phone],
            "companyName" => "Acme",
            "message" => $message,
            "strictValidation" => true,
        ]),
    ]);
    $body = json_decode(curl_exec($ch), true);
    curl_close($ch);
    $order->logNotification($event, $body['id']);
}
COPY = {
  placed:    ->(o) { "Thanks, #{o.first_name}! Order ##{o.number} is confirmed. We'll text you when it ships. Reply STOP to opt out." },
  shipped:   ->(o) { "Order ##{o.number} shipped! Track it: #{o.tracking_url}" },
  out:       ->(o) { "Order ##{o.number} is out for delivery today." },
  delivered: ->(o) { "Order ##{o.number} was delivered. Enjoy!" },
  delayed:   ->(o) { "Order ##{o.number} is running late — new ETA is #{o.eta_display}. Sorry about that." }
}

def notify(order, event)
  uri = URI("https://a.eztexting.com/v1/messages")
  req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
  req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
  req.body = { toNumbers: [order.phone], companyName: "Acme", message: COPY[event].call(order), strictValidation: true }.to_json
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
  raise "EZ Texting #{res.code}" unless res.code == "201"
  order.log_notification(event, JSON.parse(res.body)["id"])
end
static final Map<String, String> COPY = Map.of(
    "placed",    "Thanks, %s! Order #%s is confirmed. We'll text you when it ships. Reply STOP to opt out.",
    "shipped",   "Order #%2$s shipped! Track it: %3$s",
    "out",       "Order #%2$s is out for delivery today.",
    "delivered", "Order #%2$s was delivered. Enjoy!",
    "delayed",   "Order #%2$s is running late — new ETA is %4$s. Sorry about that."
);

void notify(Order order, String event) throws Exception {
    String message = String.format(COPY.get(event), order.firstName(), order.number(), order.trackingUrl(), order.etaDisplay());
    String json = mapper.writeValueAsString(Map.of(
        "toNumbers", List.of(order.phone()),
        "companyName", "Acme",
        "message", message,
        "strictValidation", true));

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://a.eztexting.com/v1/messages"))
        .header("Authorization", "Basic " + basicAuth)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(json))
        .build();
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() != 201) throw new RuntimeException("EZ Texting " + response.statusCode());
    order.logNotification(event, mapper.readTree(response.body()).get("id").asText());
}
static readonly Dictionary<string, Func<Order, string>> Copy = new()
{
    ["placed"]    = o => $"Thanks, {o.FirstName}! Order #{o.Number} is confirmed. We'll text you when it ships. Reply STOP to opt out.",
    ["shipped"]   = o => $"Order #{o.Number} shipped! Track it: {o.TrackingUrl}",
    ["out"]       = o => $"Order #{o.Number} is out for delivery today.",
    ["delivered"] = o => $"Order #{o.Number} was delivered. Enjoy!",
    ["delayed"]   = o => $"Order #{o.Number} is running late — new ETA is {o.EtaDisplay}. Sorry about that.",
};

async Task NotifyAsync(Order order, string evt)
{
    var payload = new { toNumbers = new[] { order.Phone }, companyName = "Acme", message = Copy[evt](order), strictValidation = true };
    var res = await client.PostAsJsonAsync("https://a.eztexting.com/v1/messages", payload);
    res.EnsureSuccessStatusCode();
    var body = await res.Content.ReadFromJsonAsync<JsonElement>();
    await order.LogNotificationAsync(evt, body.GetProperty("id").GetString()!);
}
var copyFor = map[string]func(Order) string{
	"placed":    func(o Order) string { return fmt.Sprintf("Thanks, %s! Order #%s is confirmed. We'll text you when it ships. Reply STOP to opt out.", o.FirstName, o.Number) },
	"shipped":   func(o Order) string { return fmt.Sprintf("Order #%s shipped! Track it: %s", o.Number, o.TrackingURL) },
	"out":       func(o Order) string { return fmt.Sprintf("Order #%s is out for delivery today.", o.Number) },
	"delivered": func(o Order) string { return fmt.Sprintf("Order #%s was delivered. Enjoy!", o.Number) },
	"delayed":   func(o Order) string { return fmt.Sprintf("Order #%s is running late — new ETA is %s. Sorry about that.", o.Number, o.ETADisplay) },
}

func notify(order Order, event string) error {
	body, _ := json.Marshal(map[string]any{
		"toNumbers":        []string{order.Phone},
		"companyName":      "Acme",
		"message":          copyFor[event](order),
		"strictValidation": true,
	})
	req, _ := http.NewRequest("POST", "https://a.eztexting.com/v1/messages", bytes.NewReader(body))
	req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode != 201 {
		return fmt.Errorf("EZ Texting %d", resp.StatusCode)
	}
	var out struct{ ID string `json:"id"` }
	json.NewDecoder(resp.Body).Decode(&out)
	return order.LogNotification(event, out.ID)
}
{
  "id": "128460233003"
}

Inline text is the right choice whenever the message carries per-order data, and whenever the copy lives in your codebase and changes with your releases.


Option B: Templates with contact variables

A message template is saved copy with ${Variable} placeholders that EZ Texting fills in from each recipient's contact record at send time. Templates are the right choice when:

  • marketing or support staff should be able to edit the wording without a deploy,
  • you send the same notification to many contacts in one call (a batch of shipments), or
  • you want one source of truth for copy across API sends and sends from the EZ Texting web app.
One contact, one value

Variables resolve from the contact record, which has one value per field. If Jane has two orders in flight and you write order #A1234 into custom1, then order #A1235 a minute later, both sends (if they haven't gone out yet) say #A1235. Use templates for order data only when each contact has exactly one current order at send time (a daily "shipped today" batch, say). Otherwise use Option A.

1. Create the template once

Variables can be the built-in name fields (${FirstName}, ${LastName}), the five free slots (${custom1} … ${custom5}, while they keep their default labels), or a custom field you've defined. See Merge tags. Here custom1 holds the order number and custom2 the tracking code. The fixed part of the link (https://acme.co/t/) is in the template, so only the code has to fit in the field's 20 characters.

curl -X POST https://a.eztexting.com/v1/message-templates \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order shipped",
    "companyName": "Acme",
    "message": "Hi ${FirstName}, order #${custom1} shipped! Track it: https://acme.co/t/${custom2}",
    "messageType": "SMS"
  }'
template = requests.post(
    "https://a.eztexting.com/v1/message-templates",
    auth=auth,
    json={
        "name": "Order shipped",
        "companyName": "Acme",
        "message": "Hi ${FirstName}, order #${custom1} shipped! Track it: https://acme.co/t/${custom2}",
        "messageType": "SMS",
    },
    timeout=30,
).json()
# save this in config
SHIPPED_TEMPLATE_ID = template["id"]
const template = await (await fetch("https://a.eztexting.com/v1/message-templates", {
  method: "POST",
  headers: { Authorization: `Basic ${credentials}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Order shipped",
    companyName: "Acme",
    message: "Hi ${FirstName}, order #${custom1} shipped! Track it: https://acme.co/t/${custom2}",
    messageType: "SMS",
  }),
})).json();
// save this in config
const SHIPPED_TEMPLATE_ID = template.id;
<?php
$ch = curl_init("https://a.eztexting.com/v1/message-templates");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode([
        "name" => "Order shipped",
        "companyName" => "Acme",
        // single quotes: no PHP interpolation
        "message" => 'Hi ${FirstName}, order #${custom1} shipped! Track it: https://acme.co/t/${custom2}',
        "messageType" => "SMS",
    ]),
]);
// save this in config
$shippedTemplateId = json_decode(curl_exec($ch), true)['id'];
curl_close($ch);
uri = URI("https://a.eztexting.com/v1/message-templates")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
req.body = {
  name: "Order shipped",
  companyName: "Acme",
  message: 'Hi ${FirstName}, order #${custom1} shipped! Track it: https://acme.co/t/${custom2}',
  messageType: "SMS"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
# save this in config
SHIPPED_TEMPLATE_ID = JSON.parse(res.body)["id"]
String json = """
    {
      "name": "Order shipped",
      "companyName": "Acme",
      "message": "Hi ${FirstName}, order #${custom1} shipped! Track it: https://acme.co/t/${custom2}",
      "messageType": "SMS"
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://a.eztexting.com/v1/message-templates"))
    .header("Authorization", "Basic " + basicAuth)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
// save this in config
String shippedTemplateId = mapper.readTree(response.body()).get("id").asText();
var res = await client.PostAsJsonAsync("https://a.eztexting.com/v1/message-templates", new
{
    name = "Order shipped",
    companyName = "Acme",
    message = "Hi ${FirstName}, order #${custom1} shipped! Track it: https://acme.co/t/${custom2}",
    messageType = "SMS"
});
res.EnsureSuccessStatusCode();
// save this in config
var shippedTemplateId = (await res.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("id").GetString();
body, _ := json.Marshal(map[string]string{
	"name":        "Order shipped",
	"companyName": "Acme",
	"message":     "Hi ${FirstName}, order #${custom1} shipped! Track it: https://acme.co/t/${custom2}",
	"messageType": "SMS",
})
req, _ := http.NewRequest("POST", "https://a.eztexting.com/v1/message-templates", bytes.NewReader(body))
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer resp.Body.Close()
var tmpl struct{ ID string `json:"id"` }
json.NewDecoder(resp.Body).Decode(&tmpl)
// save this in config
shippedTemplateID := tmpl.ID

2. Put the order data on the contact

When an order ships, upsert the contact with the current order number and tracking code. POST /v1/contacts creates or updates by phone number, so this is idempotent.

curl -X POST https://a.eztexting.com/v1/contacts \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "15551234567",
    "firstName": "Jane",
    "custom1": "A1234",
    "custom2": "1Z999AA1012"
  }'
requests.post(
    "https://a.eztexting.com/v1/contacts",
    auth=auth,
    json={
        "phoneNumber": order.phone,
        "firstName": order.first_name,
        "custom1": order.number,
        "custom2": order.tracking_code,
    },
    timeout=30,
).raise_for_status()
await fetch("https://a.eztexting.com/v1/contacts", {
  method: "POST",
  headers: { Authorization: `Basic ${credentials}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    phoneNumber: order.phone,
    firstName: order.firstName,
    custom1: order.number,
    custom2: order.trackingCode,
  }),
});
<?php
$ch = curl_init("https://a.eztexting.com/v1/contacts");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode([
        "phoneNumber" => $order['phone'],
        "firstName" => $order['firstName'],
        "custom1" => $order['number'],
        "custom2" => $order['trackingCode'],
    ]),
]);
curl_exec($ch);
curl_close($ch);
uri = URI("https://a.eztexting.com/v1/contacts")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
req.body = {
  phoneNumber: order.phone,
  firstName: order.first_name,
  custom1: order.number,
  custom2: order.tracking_code
}.to_json
# raises unless 2xx
Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }.value
String json = mapper.writeValueAsString(Map.of(
    "phoneNumber", order.phone(),
    "firstName", order.firstName(),
    "custom1", order.number(),
    "custom2", order.trackingCode()));
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://a.eztexting.com/v1/contacts"))
    .header("Authorization", "Basic " + basicAuth)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
client.send(request, HttpResponse.BodyHandlers.ofString());
var res = await client.PostAsJsonAsync("https://a.eztexting.com/v1/contacts", new
{
    phoneNumber = order.Phone,
    firstName = order.FirstName,
    custom1 = order.Number,
    custom2 = order.TrackingCode
});
res.EnsureSuccessStatusCode();
body, _ := json.Marshal(map[string]string{
	"phoneNumber": order.Phone,
	"firstName":   order.FirstName,
	"custom1":     order.Number,
	"custom2":     order.TrackingCode,
})
req, _ := http.NewRequest("POST", "https://a.eztexting.com/v1/contacts", bytes.NewReader(body))
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
resp.Body.Close()

For a batch of shipments, use POST /v1/contacts/batch and send all of them in step 3 with one call.

3. Send the template

curl -X POST https://a.eztexting.com/v1/messages \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumbers": ["15551234567"],
    "messageTemplateId": "27418",
    "strictValidation": true
  }'
requests.post(
    "https://a.eztexting.com/v1/messages",
    auth=auth,
    json={
        # or a list of every phone that shipped today
        "toNumbers": [order.phone],
        "messageTemplateId": SHIPPED_TEMPLATE_ID,
        "strictValidation": True,
    },
    timeout=30,
).raise_for_status()
await fetch("https://a.eztexting.com/v1/messages", {
  method: "POST",
  headers: { Authorization: `Basic ${credentials}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    // or a list of every phone that shipped today
    toNumbers: [order.phone],
    messageTemplateId: SHIPPED_TEMPLATE_ID,
    strictValidation: true,
  }),
});
<?php
$ch = curl_init("https://a.eztexting.com/v1/messages");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode([
        // or a list of every phone that shipped today
        "toNumbers" => [$order['phone']],
        "messageTemplateId" => $shippedTemplateId,
        "strictValidation" => true,
    ]),
]);
curl_exec($ch);
curl_close($ch);
uri = URI("https://a.eztexting.com/v1/messages")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
req.body = {
  # or a list of every phone that shipped today
  toNumbers: [order.phone],
  messageTemplateId: SHIPPED_TEMPLATE_ID,
  strictValidation: true
}.to_json
# raises unless 2xx
Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }.value
String json = mapper.writeValueAsString(Map.of(
    // or a list of every phone that shipped today
    "toNumbers", List.of(order.phone()),
    "messageTemplateId", shippedTemplateId,
    "strictValidation", true));
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://a.eztexting.com/v1/messages"))
    .header("Authorization", "Basic " + basicAuth)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
client.send(request, HttpResponse.BodyHandlers.ofString());
var res = await client.PostAsJsonAsync("https://a.eztexting.com/v1/messages", new
{
    // or a list of every phone that shipped today
    toNumbers = new[] { order.Phone },
    messageTemplateId = shippedTemplateId,
    strictValidation = true
});
res.EnsureSuccessStatusCode();
body, _ := json.Marshal(map[string]any{
	// or a list of every phone that shipped today
	"toNumbers":         []string{order.Phone},
	"messageTemplateId": shippedTemplateID,
	"strictValidation":  true,
})
req, _ := http.NewRequest("POST", "https://a.eztexting.com/v1/messages", bytes.NewReader(body))
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
resp.Body.Close()

Jane receives (Acme) Hi Jane, order #A1234 shipped! Track it: https://acme.co/t/1Z999AA1012. Each other recipient gets their own values.

Custom fields are short

Every text custom field holds up to 20 characters: custom1–custom5 and fields you create with POST /v1/contact-fields alike. Put the fixed part of a link in the template and store only the variable part, as above: the limit applies to 1Z999AA1012, not to the finished URL. If the variable part is longer than 20 characters, build the message from your order data instead (the first section of this guide). Do the same when a customer can have several active orders, since a contact field holds only one value.


Delivered: send a photo (MMS)

An "it's here" message with a product image can be useful for higher-value orders. Upload the image once and reuse its mediaFileId:

# 1. Upload (once)
curl -X POST https://a.eztexting.com/v1/media-files \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"mediaUrl": "https://cdn.acme.co/products/sku-8841.jpg"}'
# → {"id": "58213", ...}

# 2. Send (per order)
curl -X POST https://a.eztexting.com/v1/messages \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumbers": ["15551234567"],
    "companyName": "Acme",
    "message": "Order #A1234 was delivered. Enjoy!",
    "mediaFileId": "58213",
    "messageType": "MMS"
  }'
media = requests.post(
    "https://a.eztexting.com/v1/media-files",
    auth=auth,
    # publicly reachable, ≤ 5 MB
    json={"mediaUrl": product.image_url},
    timeout=30,
).json()

requests.post(
    "https://a.eztexting.com/v1/messages",
    auth=auth,
    json={
        "toNumbers": [order.phone],
        "companyName": "Acme",
        "message": f"Order #{order.number} was delivered. Enjoy!",
        "mediaFileId": media["id"],
        "messageType": "MMS",
    },
    timeout=30,
).raise_for_status()
const media = await (await fetch("https://a.eztexting.com/v1/media-files", {
  method: "POST",
  headers: { Authorization: `Basic ${credentials}`, "Content-Type": "application/json" },
  // publicly reachable, ≤ 5 MB
  body: JSON.stringify({ mediaUrl: product.imageUrl }),
})).json();

await fetch("https://a.eztexting.com/v1/messages", {
  method: "POST",
  headers: { Authorization: `Basic ${credentials}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    toNumbers: [order.phone],
    companyName: "Acme",
    message: `Order #${order.number} was delivered. Enjoy!`,
    mediaFileId: media.id,
    messageType: "MMS",
  }),
});
<?php
function ezPost(string $path, array $payload): array {
    $ch = curl_init("https://a.eztexting.com$path");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_USERPWD => getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"),
        CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
        CURLOPT_POSTFIELDS => json_encode($payload),
    ]);
    $body = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $body;
}

// publicly reachable, ≤ 5 MB
$media = ezPost("/v1/media-files", ["mediaUrl" => $product['imageUrl']]);

ezPost("/v1/messages", [
    "toNumbers" => [$order['phone']],
    "companyName" => "Acme",
    "message" => "Order #{$order['number']} was delivered. Enjoy!",
    "mediaFileId" => $media['id'],
    "messageType" => "MMS",
]);
def ez_post(path, payload)
  uri = URI("https://a.eztexting.com#{path}")
  req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
  req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
  req.body = payload.to_json
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
  # raises unless 2xx
  res.value
  JSON.parse(res.body)
end

# publicly reachable, ≤ 5 MB
media = ez_post("/v1/media-files", { mediaUrl: product.image_url })

ez_post("/v1/messages", {
  toNumbers: [order.phone],
  companyName: "Acme",
  message: "Order ##{order.number} was delivered. Enjoy!",
  mediaFileId: media["id"],
  messageType: "MMS"
})
JsonNode ezPost(String path, Object payload) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://a.eztexting.com" + path))
        .header("Authorization", "Basic " + basicAuth)
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(payload)))
        .build();
    return mapper.readTree(client.send(request, HttpResponse.BodyHandlers.ofString()).body());
}

// publicly reachable, ≤ 5 MB
JsonNode media = ezPost("/v1/media-files", Map.of("mediaUrl", product.imageUrl()));

ezPost("/v1/messages", Map.of(
    "toNumbers", List.of(order.phone()),
    "companyName", "Acme",
    "message", "Order #" + order.number() + " was delivered. Enjoy!",
    "mediaFileId", media.get("id").asText(),
    "messageType", "MMS"));
var mediaRes = await client.PostAsJsonAsync("https://a.eztexting.com/v1/media-files",
    // publicly reachable, ≤ 5 MB
    new { mediaUrl = product.ImageUrl });
var mediaFileId = (await mediaRes.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("id").GetString();

var res = await client.PostAsJsonAsync("https://a.eztexting.com/v1/messages", new
{
    toNumbers = new[] { order.Phone },
    companyName = "Acme",
    message = $"Order #{order.Number} was delivered. Enjoy!",
    mediaFileId,
    messageType = "MMS"
});
res.EnsureSuccessStatusCode();
func ezPost(path string, payload any, out any) error {
	body, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", "https://a.eztexting.com"+path, bytes.NewReader(body))
	req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode >= 300 {
		return fmt.Errorf("EZ Texting %d", resp.StatusCode)
	}
	if out != nil {
		return json.NewDecoder(resp.Body).Decode(out)
	}
	return nil
}

func sendDeliveredMMS(order Order, product Product) error {
	var media struct{ ID string `json:"id"` }
	// publicly reachable, ≤ 5 MB
	if err := ezPost("/v1/media-files", map[string]string{"mediaUrl": product.ImageURL}, &media); err != nil {
		return err
	}
	return ezPost("/v1/messages", map[string]any{
		"toNumbers":   []string{order.Phone},
		"companyName": "Acme",
		"message":     fmt.Sprintf("Order #%s was delivered. Enjoy!", order.Number),
		"mediaFileId": media.ID,
		"messageType": "MMS",
	}, nil)
}

You can pass mediaUrl directly on the send instead, but pre-uploading is faster and means a slow CDN can't delay the message.


Who clicked the tracking link?

EZ Texting counts clicks only on links it shortens. A plain URL in the message, like https://acme.co/t/1Z999AA1012 above, is delivered as written and produces no click data in EZ Texting.

To track clicks in EZ Texting, wrap the finished URL in the link shortener tag. This requires the link shortener on your account (see the FAQ). Build the tag in your code, as in Option A:

curl -X POST https://a.eztexting.com/v1/messages \
  --max-time 30 \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumbers": ["15551234567"],
    "message": "Order #A1234 shipped! Track it: ${URL=\"https://acme.co/t/1Z999AA1012\"}"
  }'

The customer receives a short eztxt.net link, and clicks appear in the report for that send. The tag needs a finished URL: a contact variable inside it (${URL="https://acme.co/t/${custom2}"}) is rejected with a 400, so the template send in Option B can't use a tracked link.

If you measure clicks through your own redirect instead (such as acme.co/t/...), the clicks are in your redirect's server logs or your web analytics, not in EZ Texting.

Pull the report for a send and read links, or list the contacts who clicked:

curl -G https://a.eztexting.com/v1/message-reports/128460233003/responses/link \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  --data-urlencode "filters[status][eq]=clicked"
clicks = requests.get(
    "https://a.eztexting.com/v1/message-reports/128460233003/responses/link",
    auth=auth,
    params={"filters[status][eq]": "clicked"},
    timeout=30,
).json()
for r in clicks["content"]:
    print(r)
const qs = new URLSearchParams({ "filters[status][eq]": "clicked" });
const clicks = await (await fetch(
  `https://a.eztexting.com/v1/message-reports/128460233003/responses/link?${qs}`,
  { headers: { Authorization: `Basic ${credentials}` } }
)).json();
for (const r of clicks.content) console.log(r);
<?php
$qs = http_build_query(["filters[status][eq]" => "clicked"]);
$ch = curl_init("https://a.eztexting.com/v1/message-reports/128460233003/responses/link?$qs");
curl_setopt($ch, CURLOPT_USERPWD, getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$clicks = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($clicks['content'] as $r) print_r($r);
uri = URI("https://a.eztexting.com/v1/message-reports/128460233003/responses/link")
uri.query = URI.encode_www_form("filters[status][eq]" => "clicked")
req = Net::HTTP::Get.new(uri)
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
clicks = JSON.parse(Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }.body)
clicks["content"].each { |r| p r }
String qs = URLEncoder.encode("filters[status][eq]", StandardCharsets.UTF_8) + "=clicked";
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://a.eztexting.com/v1/message-reports/128460233003/responses/link?" + qs))
    .header("Authorization", "Basic " + basicAuth)
    .GET().build();
JsonNode clicks = mapper.readTree(client.send(request, HttpResponse.BodyHandlers.ofString()).body());
clicks.get("content").forEach(System.out::println);
var qs = $"{Uri.EscapeDataString("filters[status][eq]")}=clicked";
var clicks = await client.GetFromJsonAsync<JsonElement>(
    $"https://a.eztexting.com/v1/message-reports/128460233003/responses/link?{qs}");
foreach (var r in clicks.GetProperty("content").EnumerateArray()) Console.WriteLine(r);
q := url.Values{"filters[status][eq]": {"clicked"}}
req, _ := http.NewRequest("GET", "https://a.eztexting.com/v1/message-reports/128460233003/responses/link?"+q.Encode(), nil)
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer resp.Body.Close()
var clicks struct {
	Content []map[string]any `json:"content"`
}
json.NewDecoder(resp.Body).Decode(&clicks)
for _, r := range clicks.Content {
	fmt.Println(r)
}

With one send per order, each shipment has its own message ID and its own report.


Gotchas

  • Don't send every event. Five texts per order feels like spam. Placed, shipped, delivered, plus exceptions, is plenty.
  • Get consent first. An order isn't permission to text. Capture a "text me updates" opt-in at checkout and keep it. → Compliance
  • Respect quiet hours. Shipments get scanned at 11pm. Queue the notification for 8am local, or send it with sendAt.
  • Opted-out customers. If you send directly to one opted-out number, the API returns 400 and there's no message ID to look up. Handle the opt-out error when you submit the request and use your fallback channel, such as email. For a group send, check the delivery report for recipients counted as not_sent.
  • URL length. Long carrier tracking URLs can push a message into more segments. Use a short link on your own domain and redirect.
  • Two orders, one phone. Keep order data in the message (Option A), not on the contact, unless you can guarantee one order per contact at send time.

Related

API reference


Did this page help you?