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.
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.IDThe 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 |
|---|---|
delivered | The 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. |
queued | Still in flight. Not final. Check again. |
bounced | It was rejected downstream, for example by the carrier. Common reasons include a landline, a disconnected number, or filtered content. |
not_sent | EZ 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:30003. 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.
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
Try Troubleshooting, check status.eztexting.com, or contact support.
Updated about 19 hours ago