Send, track & receive

Send a message, confirm it was delivered, and receive replies.

The Quickstart sends a text. This guide finishes the loop: it confirms the text was actually delivered, then sets up a webhook so the reply lands in your app instead of in a dashboard. These are the three building blocks of most SMS integrations.

Before you start

Complete the Quickstart and keep the message id it returned. The examples below use 128443910003; substitute yours. Credentials are assumed to be in EZTEXTING_USERNAME / EZTEXTING_PASSWORD.


1. Send

You've done this. For reference, a send is one call:

curl -X POST https://a.eztexting.com/v1/messages \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"toNumbers": ["15551234567"], "message": "Hello from the EZ Texting API! Reply to this message."}'
import os, requests

auth = (os.environ["EZTEXTING_USERNAME"], os.environ["EZTEXTING_PASSWORD"])
sent = requests.post(
    "https://a.eztexting.com/v1/messages",
    auth=auth,
    json={"toNumbers": ["15551234567"], "message": "Hello from the EZ Texting API! Reply to this message."},
    timeout=30,
).json()
message_id = sent["id"]
const credentials = Buffer.from(
  `${process.env.EZTEXTING_USERNAME}:${process.env.EZTEXTING_PASSWORD}`
).toString("base64");
const headers = { Authorization: `Basic ${credentials}`, "Content-Type": "application/json" };

const sent = await (await fetch("https://a.eztexting.com/v1/messages", {
  method: "POST", headers,
  body: JSON.stringify({ toNumbers: ["15551234567"], message: "Hello from the EZ Texting API! Reply to this message." }),
})).json();
const messageId = sent.id;
<?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([
        "toNumbers" => ["15551234567"],
        "message" => "Hello from the EZ Texting API! Reply to this message.",
    ]),
]);
$messageId = json_decode(curl_exec($ch), true)['id'];
curl_close($ch);
require "net/http"
require "json"

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: ["15551234567"], message: "Hello from the EZ Texting API! Reply to this message." }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
message_id = JSON.parse(res.body)["id"]
String basicAuth = Base64.getEncoder().encodeToString(
    (System.getenv("EZTEXTING_USERNAME") + ":" + System.getenv("EZTEXTING_PASSWORD")).getBytes());
HttpClient client = HttpClient.newHttpClient();
// Jackson
ObjectMapper mapper = new ObjectMapper();

String json = """
    {"toNumbers": ["15551234567"], "message": "Hello from the EZ Texting API! Reply to this message."}
    """;
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 messageId = mapper.readTree(response.body()).get("id").asText();
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes(
    $"{Environment.GetEnvironmentVariable("EZTEXTING_USERNAME")}:{Environment.GetEnvironmentVariable("EZTEXTING_PASSWORD")}"));
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var sent = await client.PostAsJsonAsync("https://a.eztexting.com/v1/messages",
    new { toNumbers = new[] { "15551234567" }, message = "Hello from the EZ Texting API! Reply to this message." });
sent.EnsureSuccessStatusCode();
var messageId = (await sent.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("id").GetString();
body := []byte(`{"toNumbers": ["15551234567"], "message": "Hello from the EZ Texting API! Reply to this message."}`)
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 {
	panic(err)
}
defer resp.Body.Close()
var sent struct{ ID string `json:"id"` }
json.NewDecoder(resp.Body).Decode(&sent)
messageID := sent.ID

The 201 means accepted, not delivered. The carrier hasn't weighed in yet. That's what step 2 is for.


2. Track delivery

Request the message report for your ID:

curl https://a.eztexting.com/v1/message-reports/128443910003 \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD"
report = requests.get(f"https://a.eztexting.com/v1/message-reports/{message_id}", auth=auth, timeout=30).json()
print(report["delivery"])
const report = await (await fetch(`https://a.eztexting.com/v1/message-reports/${messageId}`, { headers })).json();
console.log(report.delivery);
<?php
$ch = curl_init("https://a.eztexting.com/v1/message-reports/$messageId");
curl_setopt($ch, CURLOPT_USERPWD, getenv("EZTEXTING_USERNAME") . ":" . getenv("EZTEXTING_PASSWORD"));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$report = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($report['delivery']);
uri = URI("https://a.eztexting.com/v1/message-reports/#{message_id}")
req = Net::HTTP::Get.new(uri)
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body)["delivery"]
HttpRequest reportRequest = HttpRequest.newBuilder()
    .uri(URI.create("https://a.eztexting.com/v1/message-reports/" + messageId))
    .header("Authorization", "Basic " + basicAuth)
    .GET().build();
HttpResponse<String> report = client.send(reportRequest, HttpResponse.BodyHandlers.ofString());
System.out.println(mapper.readTree(report.body()).get("delivery"));
var report = await client.GetFromJsonAsync<JsonElement>($"https://a.eztexting.com/v1/message-reports/{messageId}");
Console.WriteLine(report.GetProperty("delivery"));
req, _ = http.NewRequest("GET", "https://a.eztexting.com/v1/message-reports/"+messageID, nil)
req.SetBasicAuth(os.Getenv("EZTEXTING_USERNAME"), os.Getenv("EZTEXTING_PASSWORD"))
resp, err = http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer resp.Body.Close()
var report map[string]any
json.NewDecoder(resp.Body).Decode(&report)
fmt.Println(report["delivery"])

The report breaks the send down by delivery outcome and recipient engagement:

{
  "delivery": {
    "total_delivered": { "label": "Delivered", "data": 1, "percentage": 100.0 },
    "bounced":   { "label": "Bounced",   "data": 0, "percentage": 0.0 },
    "queued":    { "label": "Queued",    "data": 0, "percentage": 0.0 },
    "total_not_sent":  { "label": "Not Sent",  "data": 0, "percentage": 0.0 }
  },
  "engagement": {
    "replied":   { "label": "Replied",   "data": 0, "percentage": 0.0 },
    "opted_out": { "label": "Opted Out", "data": 0, "percentage": 0.0 },
    "no_action": { "label": "No Action", "data": 1, "percentage": 100.0 }
  },
  "links": []
}
Outcome (responses/delivery status filter)Meaning
deliveredThe message was delivered to the handset. In rare cases where the handset confirmation isn't available, it means at least that the carrier accepted it.
queuedStill in flight. Not final. Check again.
bouncedIt was rejected downstream, for example by the carrier. Common reasons include a landline, a disconnected number, or filtered content.
not_sentEZ Texting didn't attempt it: the contact is opted out (in a group send; a direct send to an opted-out number is rejected with a 400 instead), or the account ran out of credits before a scheduled message went out.

Delivery usually completes in seconds, but it can take longer: carrier throughput limits on your number type, carrier congestion, large sends working through the queue, or a message held for review. Poll with backoff (a few seconds, then 30 s, then a minute) until queued is zero.

For a per-recipient breakdown (who bounced, who replied), use GET /v1/message-reports/{id}/responses/delivery and its siblings. For what you sent (type, from number, credits used), use GET /v1/message-details/{id}.


3. Receive the reply

To receive the reply, you could poll GET /v1/conversations, but the right tool is a webhook: EZ Texting POSTs the inbound message to a URL you choose, the moment it arrives.

1. Run a handler

Every inbound text to your number arrives as a POST with this body:

{
  "id": "128443910003",
  "type": "inbound_text.received",
  "fromNumber": "15551234567",
  "toNumber": "18885550199",
  "message": "Thanks, got it!",
  "received": "2026-11-05T18:26:42.117+00:00",
  "optIn": false,
  "optOut": false
}

id is the message ID of the send this text replies to, here the one you just sent. Several replies to the same send carry the same id, and a text that isn't a reply to a recent send has no id, so don't treat id as unique when you deduplicate. Webhooks has the details.

A minimal handler verifies the signature, logs the message, and acknowledges with a 2xx. Start it now:

import hmac, hashlib, base64
from flask import Flask, request, abort

app = Flask(__name__)
# from an env var in real code
SECRET = b"a-long-random-string"

@app.post("/webhooks/eztexting")
def inbound():
    expected = base64.b64encode(hmac.new(SECRET, request.get_data(), hashlib.sha256).digest()).decode()
    if not hmac.compare_digest(expected, request.headers.get("X-Signature-256", "")):
        abort(401)
    event = request.get_json()
    print(f"{event['fromNumber']} said: {event['message']}")
    return "", 204

app.run(port=3000)
import express from "express";
import crypto from "node:crypto";

const app = express();
// from an env var in real code
const SECRET = "a-long-random-string";

app.post("/webhooks/eztexting", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("base64");
  const given = req.get("X-Signature-256") || "";
  if (expected.length !== given.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  console.log(`${event.fromNumber} said: ${event.message}`);
  res.sendStatus(204);
});

app.listen(3000);
<?php
// Run with: php -S localhost:3000 webhook.php
// from an env var in real code
$secret = "a-long-random-string";
$rawBody = file_get_contents("php://input");
$expected = base64_encode(hash_hmac("sha256", $rawBody, $secret, true));
if (!hash_equals($expected, $_SERVER["HTTP_X_SIGNATURE_256"] ?? "")) {
    http_response_code(401);
    exit;
}
$event = json_decode($rawBody, true);
error_log("{$event['fromNumber']} said: {$event['message']}");
http_response_code(204);
class EzTextingWebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token
  # from an env var in real code
  SECRET = "a-long-random-string"

  def create
    raw = request.raw_post
    expected = Base64.strict_encode64(OpenSSL::HMAC.digest("SHA256", SECRET, raw))
    given = request.headers["X-Signature-256"].to_s
    return head :unauthorized unless ActiveSupport::SecurityUtils.secure_compare(expected, given)

    event = JSON.parse(raw)
    Rails.logger.info("#{event['fromNumber']} said: #{event['message']}")
    head :no_content
  end
end
// from an env var in real code
private static final byte[] SECRET = "a-long-random-string".getBytes(StandardCharsets.UTF_8);

@PostMapping("/webhooks/eztexting")
public ResponseEntity<Void> inbound(@RequestBody byte[] rawBody,
                                    @RequestHeader(value = "X-Signature-256", required = false) String given) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(SECRET, "HmacSHA256"));
    String expected = Base64.getEncoder().encodeToString(mac.doFinal(rawBody));
    if (given == null || !MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), given.getBytes(StandardCharsets.UTF_8))) {
        return ResponseEntity.status(401).build();
    }
    JsonNode event = mapper.readTree(rawBody);
    System.out.println(event.get("fromNumber").asText() + " said: " + event.get("message").asText());
    return ResponseEntity.noContent().build();
}
var app = WebApplication.Create();
// from an env var in real code
var secret = Encoding.UTF8.GetBytes("a-long-random-string");

app.MapPost("/webhooks/eztexting", async (HttpRequest req) =>
{
    using var ms = new MemoryStream();
    await req.Body.CopyToAsync(ms);
    var rawBody = ms.ToArray();

    var expected = Convert.ToBase64String(HMACSHA256.HashData(secret, rawBody));
    var given = req.Headers["X-Signature-256"].ToString();
    if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(given)))
        return Results.Unauthorized();

    var evt = JsonDocument.Parse(rawBody).RootElement;
    Console.WriteLine($"{evt.GetProperty("fromNumber")} said: {evt.GetProperty("message")}");
    return Results.NoContent();
});

app.Run("http://localhost:3000");
// from an env var in real code
var secret = []byte("a-long-random-string")

func inbound(w http.ResponseWriter, r *http.Request) {
	rawBody, _ := io.ReadAll(io.LimitReader(r.Body, 1<<20))
	mac := hmac.New(sha256.New, secret)
	mac.Write(rawBody)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
	if !hmac.Equal([]byte(expected), []byte(r.Header.Get("X-Signature-256"))) {
		http.Error(w, "invalid signature", http.StatusUnauthorized)
		return
	}
	var event struct {
		FromNumber string `json:"fromNumber"`
		Message    string `json:"message"`
	}
	json.Unmarshal(rawBody, &event)
	fmt.Printf("%s said: %s\n", event.FromNumber, event.Message)
	w.WriteHeader(http.StatusNoContent)
}

func main() {
	http.HandleFunc("/webhooks/eztexting", inbound)
	http.ListenAndServe(":3000", nil)
}

2. Get a public URL

Webhooks need an HTTPS endpoint reachable from the internet. For development, keep the handler running and expose it with a tunnel:

ngrok http 3000
# Forwarding  https://a1b2c3d4.ngrok.app -> http://localhost:3000

3. Subscribe

Use your tunnel's URL. A successful subscription returns 201 with its ID, for example {"id": "3ec32644cd7f4a5624ebf31068f3f0f55f08dc3a667b11705d5d0f68f3f4f1e1"}. Anything else means the subscription wasn't created; the response body says why.

curl -X POST https://a.eztexting.com/v1/webhooks/subscriptions \
  -u "$EZTEXTING_USERNAME:$EZTEXTING_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inbound_text.received",
    "callbackUrl": "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
    "secret": "a-long-random-string"
  }'
sub = requests.post(
    "https://a.eztexting.com/v1/webhooks/subscriptions",
    auth=auth,
    json={
        "type": "inbound_text.received",
        "callbackUrl": "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
        "secret": "a-long-random-string",
    },
    timeout=30,
)
# 201 {"id": "..."}, or the status and the reason it failed
print(sub.status_code, sub.text)
const sub = await fetch("https://a.eztexting.com/v1/webhooks/subscriptions", {
  method: "POST", headers,
  body: JSON.stringify({
    type: "inbound_text.received",
    callbackUrl: "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
    secret: "a-long-random-string",
  }),
});
// 201 {"id": "..."}, or the status and the reason it failed
console.log(sub.status, await sub.text());
<?php
$ch = curl_init("https://a.eztexting.com/v1/webhooks/subscriptions");
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([
        "type" => "inbound_text.received",
        "callbackUrl" => "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
        "secret" => "a-long-random-string",
    ]),
]);
$body = curl_exec($ch);
// 201 {"id": "..."}, or the status and the reason it failed
echo curl_getinfo($ch, CURLINFO_HTTP_CODE) . " $body\n";
curl_close($ch);
uri = URI("https://a.eztexting.com/v1/webhooks/subscriptions")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req.basic_auth(ENV.fetch("EZTEXTING_USERNAME"), ENV.fetch("EZTEXTING_PASSWORD"))
req.body = {
  type: "inbound_text.received",
  callbackUrl: "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
  secret: "a-long-random-string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
# 201 {"id": "..."}, or the status and the reason it failed
puts "#{res.code} #{res.body}"
String subscription = """
    {
      "type": "inbound_text.received",
      "callbackUrl": "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
      "secret": "a-long-random-string"
    }
    """;
HttpRequest subscribe = HttpRequest.newBuilder()
    .uri(URI.create("https://a.eztexting.com/v1/webhooks/subscriptions"))
    .header("Authorization", "Basic " + basicAuth)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(subscription))
    .build();
HttpResponse<String> subResponse = client.send(subscribe, HttpResponse.BodyHandlers.ofString());
// 201 {"id": "..."}, or the status and the reason it failed
System.out.println(subResponse.statusCode() + " " + subResponse.body());
var sub = await client.PostAsJsonAsync("https://a.eztexting.com/v1/webhooks/subscriptions", new
{
    type = "inbound_text.received",
    callbackUrl = "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
    secret = "a-long-random-string"
});
// 201 {"id": "..."}, or the status and the reason it failed
Console.WriteLine($"{(int)sub.StatusCode} {await sub.Content.ReadAsStringAsync()}");
subBody, _ := json.Marshal(map[string]string{
	"type":        "inbound_text.received",
	"callbackUrl": "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
	"secret":      "a-long-random-string",
})
req, _ = http.NewRequest("POST", "https://a.eztexting.com/v1/webhooks/subscriptions", bytes.NewReader(subBody))
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 {
	panic(err)
}
subResp, _ := io.ReadAll(resp.Body)
resp.Body.Close()
// 201 {"id": "..."}, or the status and the reason it failed
fmt.Println(resp.StatusCode, string(subResp))

4. Reply from your phone

Reply to the text from your phone and watch the handler print it. That's a two-way integration.

The signature matters

With a secret set, every callback carries X-Signature-256: Base64 of an HMAC-SHA256 over the raw body. Verifying it is how you know the request came from EZ Texting and not from anyone who found your URL. Don't rely on IP allowlists; outbound addresses change. Webhooks has verification code in seven languages and a test vector.


Next steps


Did this page help you?