Campaigns to a group

Send one message to a group of contacts.

The transactional guides send one message to one person. This one sends one message to everyone in a group (a promotion, an announcement, a weather closure, a re-engagement nudge), with one message ID for the whole campaign. You can send the same text to everyone, or add merge tags such as ${FirstName} so each contact gets their own values.

When to use this guide

Use it when…Use something else when…
One message goes to many contacts: a promotion, an announcement, a closure notice.The message is about one person's order → Order & shipping notifications
Everyone in the group has agreed to receive texts from you.It's a verification code → One-time passcodes
It's tied to someone's appointment → Appointment reminders

What you'll build

  1. Segment: load contacts with the data you'll personalize on, and put them in a group, in one batch call.
  2. Template: write the message once with ${…} variables.
  3. Pre-flight: estimate credits and check the balance.
  4. Send (or schedule) to the group in one call.
  5. Measure: delivery, replies, opt-outs, and link clicks.

Prerequisites: contacts who have given prior express written consent to receive texts from you, with the record to show for it (see Compliance), a registered sending number, and credentials in EZTEXTING_USERNAME / EZTEXTING_PASSWORD.


How a group send works

One POST /v1/messages with groupIds and a messageTemplateId does it all: EZ Texting resolves the group, fills the template from each contact's record, skips opted-out numbers, and returns one message ID with one report covering every recipient.

Sending to contacts one at a time works, and many integrations do it. For large lists, a group send is usually better: one request instead of thousands, optional personalization with variables filled in per contact, and a single report.


Step 1: Build the segment

Decide what you'll personalize on and make sure each contact has it. Here: first name, a store location in custom1, and an offer code in custom2. Create the group, then batch-upsert the contacts straight into it. If an active Workflow starts when contacts are added to this group, the upsert starts it for every contact. See Automation workflows.

# Create the group (once). Names are limited to 25 characters.
curl -X POST https://a.eztexting.com/v1/contact-groups \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "Fall Sale 2026", "note": "Opted-in customers, West region"}'
# → {"id": "48213"}

# Load contacts into it — up to hundreds per call, repeat as needed
curl -X POST https://a.eztexting.com/v1/contacts/batch \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {"phoneNumber": "15551234567", "firstName": "Jane", "custom1": "Santa Monica", "custom2": "FALL20"},
      {"phoneNumber": "15559876543", "firstName": "Sam",  "custom1": "Pasadena",     "custom2": "FALL20"}
    ],
    "groupIdsAdd": ["48213"]
  }'
import os, requests

auth = (os.environ["EZTEXTING_USERNAME"], os.environ["EZTEXTING_PASSWORD"])
BASE = "https://a.eztexting.com"

group = requests.post(f"{BASE}/v1/contact-groups", auth=auth,
                      json={"name": "Fall Sale 2026", "note": "Opted-in customers, West region"}, timeout=30).json()
GROUP_ID = group["id"]

def chunks(items, n):
    for i in range(0, len(items), n):
        yield items[i:i + n]

# customers: rows from your DB/CRM, already opted in
for batch in chunks(customers, 500):
    requests.post(f"{BASE}/v1/contacts/batch", auth=auth, json={
        "contacts": [
            {"phoneNumber": c.phone, "firstName": c.first_name,
             "custom1": c.store, "custom2": c.offer_code}
            for c in batch
        ],
        "groupIdsAdd": [GROUP_ID],
    }, timeout=30).raise_for_status()
const credentials = Buffer.from(
  `${process.env.EZTEXTING_USERNAME}:${process.env.EZTEXTING_PASSWORD}`
).toString("base64");
const BASE = "https://a.eztexting.com";
const headers = { Authorization: `Basic ${credentials}`, "Content-Type": "application/json" };

const group = await (await fetch(`${BASE}/v1/contact-groups`, {
  method: "POST", headers,
  body: JSON.stringify({ name: "Fall Sale 2026", note: "Opted-in customers, West region" }),
})).json();
const GROUP_ID = group.id;

// customers: rows from your DB/CRM, already opted in
for (let i = 0; i < customers.length; i += 500) {
  const batch = customers.slice(i, i + 500);
  const res = await fetch(`${BASE}/v1/contacts/batch`, {
    method: "POST", headers,
    body: JSON.stringify({
      contacts: batch.map((c) => ({
        phoneNumber: c.phone, firstName: c.firstName, custom1: c.store, custom2: c.offerCode,
      })),
      groupIdsAdd: [GROUP_ID],
    }),
  });
  if (!res.ok) throw new Error(`batch ${i}: ${res.status}`);
}
<?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 = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status >= 300) throw new RuntimeException("EZ Texting $status: $body");
    return json_decode($body, true) ?? [];
}

$group = ezPost("/v1/contact-groups", ["name" => "Fall Sale 2026", "note" => "Opted-in customers, West region"]);
$groupId = $group['id'];

// $customers: rows from your DB/CRM, already opted in
foreach (array_chunk($customers, 500) as $batch) {
    ezPost("/v1/contacts/batch", [
        "contacts" => array_map(fn($c) => [
            "phoneNumber" => $c['phone'], "firstName" => $c['firstName'],
            "custom1" => $c['store'], "custom2" => $c['offerCode'],
        ], $batch),
        "groupIdsAdd" => [$groupId],
    ]);
}
require "net/http"
require "json"

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

group_id = ez_post("/v1/contact-groups", { name: "Fall Sale 2026", note: "Opted-in customers, West region" })["id"]

# customers: rows from your DB/CRM, already opted in
customers.each_slice(500) do |batch|
  ez_post("/v1/contacts/batch", {
    contacts: batch.map { |c|
      { phoneNumber: c.phone, firstName: c.first_name, custom1: c.store, custom2: c.offer_code }
    },
    groupIdsAdd: [group_id]
  })
end
String basicAuth = Base64.getEncoder().encodeToString(
    (System.getenv("EZTEXTING_USERNAME") + ":" + System.getenv("EZTEXTING_PASSWORD")).getBytes());
HttpClient client = HttpClient.newHttpClient();
// Jackson
ObjectMapper mapper = new ObjectMapper();

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();
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() >= 300) throw new RuntimeException("EZ Texting " + response.statusCode() + ": " + response.body());
    return mapper.readTree(response.body());
}

String groupId = ezPost("/v1/contact-groups",
    Map.of("name", "Fall Sale 2026", "note", "Opted-in customers, West region")).get("id").asText();

// customers: rows from your DB/CRM, already opted in
for (int i = 0; i < customers.size(); i += 500) {
    List<Map<String, String>> contacts = customers.subList(i, Math.min(i + 500, customers.size())).stream()
        .map(c -> Map.of("phoneNumber", c.phone(), "firstName", c.firstName(), "custom1", c.store(), "custom2", c.offerCode()))
        .toList();
    ezPost("/v1/contacts/batch", Map.of("contacts", contacts, "groupIdsAdd", List.of(groupId)));
}
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes(
    $"{Environment.GetEnvironmentVariable("EZTEXTING_USERNAME")}:{Environment.GetEnvironmentVariable("EZTEXTING_PASSWORD")}"));
using var client = new HttpClient { BaseAddress = new Uri("https://a.eztexting.com") };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var groupRes = await client.PostAsJsonAsync("/v1/contact-groups",
    new { name = "Fall Sale 2026", note = "Opted-in customers, West region" });
groupRes.EnsureSuccessStatusCode();
var groupId = (await groupRes.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("id").GetString();

// customers: rows from your DB/CRM, already opted in
foreach (var batch in customers.Chunk(500))
{
    var res = await client.PostAsJsonAsync("/v1/contacts/batch", new
    {
        contacts = batch.Select(c => new { phoneNumber = c.Phone, firstName = c.FirstName, custom1 = c.Store, custom2 = c.OfferCode }),
        groupIdsAdd = new[] { groupId }
    });
    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
}

// customers: rows from your DB/CRM, already opted in
func loadSegment(customers []Customer) (string, error) {
	var group struct{ ID string `json:"id"` }
	if err := ezPost("/v1/contact-groups", map[string]string{"name": "Fall Sale 2026", "note": "Opted-in customers, West region"}, &group); err != nil {
		return "", err
	}
	for i := 0; i < len(customers); i += 500 {
		batch := customers[i:min(i+500, len(customers))]
		contacts := make([]map[string]string, 0, len(batch))
		for _, c := range batch {
			contacts = append(contacts, map[string]string{"phoneNumber": c.Phone, "firstName": c.FirstName, "custom1": c.Store, "custom2": c.OfferCode})
		}
		if err := ezPost("/v1/contacts/batch", map[string]any{"contacts": contacts, "groupIdsAdd": []string{group.ID}}, nil); err != nil {
			return "", fmt.Errorf("batch %d: %w", i, err)
		}
	}
	return group.ID, nil
}

Upserts are keyed by phone number, so re-running this is safe: existing contacts are updated, not duplicated, and already-opted-out contacts stay opted out.

To confirm the segment: GET /v1/contact-groups/48213 for the count, and GET /v1/contacts?filters[groupName][like]=Fall%20Sale&filters[optOut][eq]=true to see how many in it won't receive anything.


Step 2: Write the template

Variables use ${FieldName}, where FieldName is a contact field such as ${FirstName} or ${custom1} (custom fields use their label with spaces removed; see Merge tags). EZ Texting fills them in per recipient at send time, so make sure every contact in the group has a value for each field you use. To include a shortened link, use the link shortener notation ${URL="www.example.com"} if your account includes the link shortener. See the FAQ.

curl -X POST https://a.eztexting.com/v1/message-templates \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fall sale announcement",
    "companyName": "Acme Outfitters",
    "message": "Hi ${FirstName}! Fall Sale Friday at our ${custom1} store. Show code ${custom2} for 20% off: ${URL=\"https://acme.co/fall\"} Reply STOP to opt out.",
    "messageType": "SMS"
  }'
# → {"id": "27418"}
template = requests.post(f"{BASE}/v1/message-templates", auth=auth, json={
    "name": "Fall sale announcement",
    "companyName": "Acme Outfitters",
    "message": "Hi ${FirstName}! Fall Sale Friday at our ${custom1} store. "
               "Show code ${custom2} for 20% off: ${URL=\"https://acme.co/fall\"} Reply STOP to opt out.",
    "messageType": "SMS",
}, timeout=30).json()
TEMPLATE_ID = template["id"]
const template = await (await fetch(`${BASE}/v1/message-templates`, {
  method: "POST", headers,
  body: JSON.stringify({
    name: "Fall sale announcement",
    companyName: "Acme Outfitters",
    message: "Hi ${FirstName}! Fall Sale Friday at our ${custom1} store. " +
             "Show code ${custom2} for 20% off: ${URL=\"https://acme.co/fall\"} Reply STOP to opt out.",
    messageType: "SMS",
  }),
})).json();
const TEMPLATE_ID = template.id;
<?php
$template = ezPost("/v1/message-templates", [
    "name" => "Fall sale announcement",
    "companyName" => "Acme Outfitters",
    // single quotes: no PHP interpolation
    "message" => 'Hi ${FirstName}! Fall Sale Friday at our ${custom1} store. '
               . 'Show code ${custom2} for 20% off: ${URL="https://acme.co/fall"} Reply STOP to opt out.',
    "messageType" => "SMS",
]);
$templateId = $template['id'];
template_id = ez_post("/v1/message-templates", {
  name: "Fall sale announcement",
  companyName: "Acme Outfitters",
  message: 'Hi ${FirstName}! Fall Sale Friday at our ${custom1} store. ' \
           'Show code ${custom2} for 20% off: ${URL="https://acme.co/fall"} Reply STOP to opt out.',
  messageType: "SMS"
})["id"]
String templateId = ezPost("/v1/message-templates", Map.of(
    "name", "Fall sale announcement",
    "companyName", "Acme Outfitters",
    "message", "Hi ${FirstName}! Fall Sale Friday at our ${custom1} store. "
             + "Show code ${custom2} for 20% off: ${URL=\"https://acme.co/fall\"} Reply STOP to opt out.",
    "messageType", "SMS")).get("id").asText();
var templateRes = await client.PostAsJsonAsync("/v1/message-templates", new
{
    name = "Fall sale announcement",
    companyName = "Acme Outfitters",
    message = "Hi ${FirstName}! Fall Sale Friday at our ${custom1} store. " +
              "Show code ${custom2} for 20% off: ${URL=\"https://acme.co/fall\"} Reply STOP to opt out.",
    messageType = "SMS"
});
templateRes.EnsureSuccessStatusCode();
var templateId = (await templateRes.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("id").GetString();
var template struct{ ID string `json:"id"` }
err := ezPost("/v1/message-templates", map[string]string{
	"name":        "Fall sale announcement",
	"companyName": "Acme Outfitters",
	"message": "Hi ${FirstName}! Fall Sale Friday at our ${custom1} store. " +
		"Show code ${custom2} for 20% off: ${URL=\"https://acme.co/fall\"} Reply STOP to opt out.",
	"messageType": "SMS",
}, &template)
if err != nil {
	return err
}
templateID := template.ID

Jane gets (Acme Outfitters) Hi Jane! Fall Sale Friday at our Santa Monica store. Show code FALL20 for 20% off: https://eztxt.net/CZLQPn Reply STOP to opt out. Sam gets his own. ${URL="..."} sends a short link and counts its clicks in the report (it requires the link shortener on your account; see Merge tags).

Mind the length: companyName plus the filled-in text counts toward the segment limit (160 characters, or 70 if the message has Unicode characters). Each extra segment costs another credit per recipient, and a message that would need three or more segments goes as MMS (3 credits) unless you set messageType to SMS.


Step 3: Pre-flight

A campaign to 40,000 contacts is 40,000 credits for a one-segment SMS. Check before you send, not after:

members = requests.get(f"{BASE}/v1/contact-groups/{GROUP_ID}", auth=auth, timeout=30).json()
balance = requests.get(f"{BASE}/v1/credits", auth=auth, timeout=30).json()

# 2 if your filled template can exceed 160 chars
segments_per_message = 1
needed = members["contactsCount"] * segments_per_message
if balance["totalCredits"] < needed:
    raise RuntimeError(f"Need ~{needed} credits, have {balance['totalCredits']}")
const members = await (await fetch(`${BASE}/v1/contact-groups/${GROUP_ID}`, { headers })).json();
const balance = await (await fetch(`${BASE}/v1/credits`, { headers })).json();

// 2 if your filled template can exceed 160 chars
const segmentsPerMessage = 1;
const needed = members.contactsCount * segmentsPerMessage;
if (balance.totalCredits < needed) throw new Error(`Need ~${needed} credits, have ${balance.totalCredits}`);
<?php
function ezGet(string $path): array {
    $ch = curl_init("https://a.eztexting.com$path");
    curl_setopt($ch, CURLOPT_USERPWD, getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $data = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $data;
}

$members = ezGet("/v1/contact-groups/$groupId");
$balance = ezGet("/v1/credits");

// 2 if your filled template can exceed 160 chars
$segmentsPerMessage = 1;
$needed = $members['contactsCount'] * $segmentsPerMessage;
if ($balance['totalCredits'] < $needed) {
    throw new RuntimeException("Need ~$needed credits, have {$balance['totalCredits']}");
}
def ez_get(path)
  uri = URI("https://a.eztexting.com#{path}")
  req = Net::HTTP::Get.new(uri)
  req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
  JSON.parse(Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }.body)
end

members = ez_get("/v1/contact-groups/#{group_id}")
balance = ez_get("/v1/credits")

# 2 if your filled template can exceed 160 chars
segments_per_message = 1
needed = members["contactsCount"] * segments_per_message
raise "Need ~#{needed} credits, have #{balance['totalCredits']}" if balance["totalCredits"] < needed
JsonNode ezGet(String path) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://a.eztexting.com" + path))
        .header("Authorization", "Basic " + basicAuth)
        .GET().build();
    return mapper.readTree(client.send(request, HttpResponse.BodyHandlers.ofString()).body());
}

JsonNode members = ezGet("/v1/contact-groups/" + groupId);
JsonNode balance = ezGet("/v1/credits");

// 2 if your filled template can exceed 160 chars
int segmentsPerMessage = 1;
long needed = members.get("contactsCount").asLong() * segmentsPerMessage;
if (balance.get("totalCredits").asLong() < needed) {
    throw new IllegalStateException("Need ~" + needed + " credits, have " + balance.get("totalCredits").asLong());
}
var members = await client.GetFromJsonAsync<JsonElement>($"/v1/contact-groups/{groupId}");
var balance = await client.GetFromJsonAsync<JsonElement>("/v1/credits");

// 2 if your filled template can exceed 160 chars
const int segmentsPerMessage = 1;
var needed = members.GetProperty("contactsCount").GetInt64() * segmentsPerMessage;
var have = balance.GetProperty("totalCredits").GetInt64();
if (have < needed) throw new InvalidOperationException($"Need ~{needed} credits, have {have}");
func ezGet(path string, out any) error {
	req, _ := http.NewRequest("GET", "https://a.eztexting.com"+path, 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()
	return json.NewDecoder(resp.Body).Decode(out)
}

func preflight(groupID string) error {
	var members struct{ ContactsCount int `json:"contactsCount"` }
	var balance struct{ TotalCredits int `json:"totalCredits"` }
	if err := ezGet("/v1/contact-groups/"+groupID, &members); err != nil {
		return err
	}
	if err := ezGet("/v1/credits", &balance); err != nil {
		return err
	}
	// 2 if your filled template can exceed 160 chars
	segmentsPerMessage := 1
	needed := members.ContactsCount * segmentsPerMessage
	if balance.TotalCredits < needed {
		return fmt.Errorf("need ~%d credits, have %d", needed, balance.TotalCredits)
	}
	return nil
}

Then send the campaign to a test group containing only your team (see Testing your integration) with the same template, and read it on a real phone. Typos in a 40,000-recipient send are permanent.


Step 4: Send or schedule

One call. Use sendAt to land it mid-morning in the recipients' time zone (and inside the legal window; see Compliance). The time must be in the future; a sendAt that has already passed is rejected with a 400.

curl -X POST https://a.eztexting.com/v1/messages \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "groupIds": ["48213"],
    "messageTemplateId": "27418",
    "sendAt": "2027-11-16T10:00:00-08:00"
  }'
campaign = requests.post(f"{BASE}/v1/messages", auth=auth, json={
    "groupIds": [GROUP_ID],
    "messageTemplateId": TEMPLATE_ID,
    # omit to send now
    "sendAt": "2027-11-16T10:00:00-08:00",
}, timeout=30)
campaign.raise_for_status()
# store it — this is your handle for reports and cancellation
CAMPAIGN_ID = campaign.json()["id"]
const campaign = await fetch(`${BASE}/v1/messages`, {
  method: "POST", headers,
  body: JSON.stringify({
    groupIds: [GROUP_ID],
    messageTemplateId: TEMPLATE_ID,
    // omit to send now
    sendAt: "2027-11-16T10:00:00-08:00",
  }),
});
if (!campaign.ok) throw new Error(`EZ Texting ${campaign.status}: ${await campaign.text()}`);
// store it — your handle for reports and cancellation
const { id: CAMPAIGN_ID } = await campaign.json();
<?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([
        "groupIds" => [$groupId],
        "messageTemplateId" => $templateId,
        "sendAt" => "2027-11-16T10:00:00-08:00",
    ]),
]);
$campaignId = json_decode(curl_exec($ch), true)['id'];
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 = { groupIds: [group_id], messageTemplateId: template_id, sendAt: "2027-11-16T10:00:00-08:00" }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
campaign_id = JSON.parse(res.body)["id"]
String json = """
    {"groupIds": ["%s"], "messageTemplateId": "%s", "sendAt": "2027-11-16T10:00:00-08:00"}
    """.formatted(groupId, templateId);
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());
String campaignId = mapper.readTree(response.body()).get("id").asText();
var payload = new { groupIds = new[] { groupId }, messageTemplateId = templateId, sendAt = "2027-11-16T10:00:00-08:00" };
var res = await client.PostAsJsonAsync("https://a.eztexting.com/v1/messages", payload);
res.EnsureSuccessStatusCode();
var campaignId = (await res.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("id").GetString();
body, _ := json.Marshal(map[string]any{
	"groupIds":          []string{groupID},
	"messageTemplateId": templateID,
	"sendAt":            "2027-11-16T10:00:00-08:00",
})
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()
var out struct{ ID string `json:"id"` }
json.NewDecoder(resp.Body).Decode(&out)
campaignID := out.ID
{
  "id": "128470551003"
}

Until sendAt, the campaign is visible in GET /v1/campaign-info and can be cancelled with DELETE /v1/messages {"ids": ["128470551003"]}. Once it starts sending, it can't be stopped.

Group sends and strictValidation

strictValidation is for toNumbers. Group sends skip contacts that can't be messaged (opted out or invalid) and report them as not sent. Review the report rather than expecting a 400.


Step 5: Measure

Delivery runs in the background. Large campaigns are throttled by your number type's throughput, so a 40,000-contact send may take a while to finish. Poll the report every minute or two until queued reaches zero.

curl https://a.eztexting.com/v1/message-reports/128470551003 \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD"
report = requests.get(f"{BASE}/v1/message-reports/{CAMPAIGN_ID}", auth=auth, timeout=30).json()
print(report["delivery"]["queued"]["data"], "still queued")
const report = await (await fetch(`${BASE}/v1/message-reports/${CAMPAIGN_ID}`, { headers })).json();
console.log(report.delivery.queued.data, "still queued");
<?php
$report = ezGet("/v1/message-reports/$campaignId");
echo $report['delivery']['queued']['data'], " still queued\n";
report = ez_get("/v1/message-reports/#{campaign_id}")
puts "#{report['delivery']['queued']['data']} still queued"
JsonNode report = ezGet("/v1/message-reports/" + campaignId);
System.out.println(report.at("/delivery/queued/data").asInt() + " still queued");
var report = await client.GetFromJsonAsync<JsonElement>($"/v1/message-reports/{campaignId}");
Console.WriteLine($"{report.GetProperty("delivery").GetProperty("queued").GetProperty("data")} still queued");
var report struct {
	Delivery struct {
		Queued struct{ Data int `json:"data"` } `json:"queued"`
	} `json:"delivery"`
}
if err := ezGet("/v1/message-reports/"+campaignID, &report); err != nil {
	return err
}
fmt.Println(report.Delivery.Queued.Data, "still queued")
{
  "delivery": {
    "total_delivered": { "label": "Delivered", "data": 38104, "percentage": 95.3 },
    "bounced":   { "label": "Bounced",   "data": 1312,  "percentage": 3.3 },
    "queued":    { "label": "Queued",    "data": 0,     "percentage": 0.0 },
    "total_not_sent":  { "label": "Not Sent",  "data": 584,   "percentage": 1.5 }
  },
  "engagement": {
    "replied":   { "label": "Replied",   "data": 912,   "percentage": 2.3 },
    "opted_out": { "label": "Opted Out", "data": 203,   "percentage": 0.5 },
    "no_action": { "label": "No Action", "data": 38885, "percentage": 97.2 }
  },
  "links": [
    { "longUrl": "https://acme.co/fall", "clicks": 2740, "clickRate": 7 }
  ]
}

Drill into who did what with the per-recipient lists, each paged and each filterable by status (in cURL, pass bracketed filters with -G --data-urlencode, as in Pagination, so the shell and curl's URL globbing leave the brackets alone):

QuestionCall
Who bounced? (clean your list)GET /v1/message-reports/{id}/responses/delivery?filters[status][eq]=bounced
Who opted out after this campaign?GET /v1/message-reports/{id}/responses/engagement?filters[status][eq]=opted_out
Who replied? (hand to sales/support)GET /v1/message-reports/{id}/responses/engagement?filters[status][eq]=replied
Who clicked? (retarget)GET /v1/message-reports/{id}/responses/link?filters[status][eq]=clicked

The opt-out list shows who opted out in response to this send. For suppression in your CRM, sync from the contact's current optOut (GET /v1/contacts?filters[optOut][eq]=true), which includes opt-outs from any source.

Replies themselves arrive through the inbound_text.received webhook or in Conversations. A campaign to 40,000 people will generate hundreds of replies, some of them questions. Plan to answer them.


Patterns

A/B test. Split the segment into two groups (groupIdsAdd with different IDs), two templates, two sends a minute apart. Compare links[].clickRate and engagement.replied.

Multiple segments, one template. groupIds accepts several groups: ["48213", "48214"]. A contact in both receives one message.

Recurring campaigns. Schedule each occurrence as its own send with sendAt; keep the IDs so each has its own report.

Suppression. Contacts you don't want to message for business reasons (recent purchasers, VIPs handled by phone) should be removed from the group before sending (DELETE /v1/contact-groups/{id}/contacts), not blocked. Blocking is for opt-outs.

Re-engagement. GET /v1/contacts doesn't currently filter by last activity, and the engagement list doesn't filter to no_action. Instead, take everyone delivered (responses/delivery?filters[status][eq]=delivered) and subtract who replied, opted out, or clicked; contacts left over across your last few sends are candidates for a "still want to hear from us?" message, or for removal.


Gotchas

  • Check consent before adding contacts to a group. Every send to the group reaches everyone in it.
  • Group names are 25 characters max. Fall Sale 2026 – West Region – Opted In won't save.
  • Custom fields hold 20 characters, including custom1–custom5 and fields you create. Keep the fixed part of a URL in the message and store only the variable part, or use a short link.
  • Frequency. More than a few marketing messages a month drives opt-outs. Watch engagement.opted_out on every campaign; a jump is a signal.
  • Timing. sendAt is one timestamp. A national list spans several time zones, so split by region into separate groups with separate sendAt values.
  • Throughput. Delivery speed is set by your number type and registration, not by the API. If a campaign needs to land in a tight window, talk to EZ Texting about the right number before the campaign, not during.

Related

API reference


Did this page help you?