Testing your integration
How to test your integration safely.
Use your own numbers
The simplest, safest test harness is a phone (or a few) that you control.
- Send single tests to yourself. Most transactional sends (a reminder, a passcode, an order update) go to one number. Point
toNumbersat your own phone while you develop. - Create a test group (for example,
API Test) containing only your team's numbers. Point every campaign-style test at thatgroupId. You can't accidentally blast customers from a group that doesn't contain any. - Keep test contacts obviously named (
firstName: "TEST") so they're easy to find and exclude:GET /v1/contacts?filters[firstName][like]=TEST. - Put the environment in the message during development:
[DEV] Your code is 123456.
Test without delivering
Several calls are useful for exercising your code paths without actually sending:
| Want to test… | Do this |
|---|---|
| Authentication | GET /v1/credits: cheap, read-only, and fails with 401 if your credentials are wrong. |
| Request validation | Send to a deliberately bad number. strictValidation is on by default, so you get the 400 and nothing goes out. |
| Scheduling logic | Send with a sendAt an hour from now, confirm it appears in GET /v1/campaign-info, then cancel it with DELETE /v1/messages ({"ids": ["<id>"]}). No message, no credits. |
| Templates | POST /v1/message-templates and GET /v1/message-templates/{id} are free. Verify the variable names before you send with one. |
| Contact sync | POST /v1/contacts/batch then GET /v1/contacts/{phoneNumber}. The requests are free, but they can trigger a Workflow that sends a text (see below). |
| Reporting code | Use the message ID from any earlier real send; reports are read-only. |
Use a test contact and a group you control. Before updating group membership or a date field, check whether an active Workflow uses it. Your sync can trigger a message even if your code never calls POST /v1/messages. See Automation workflows.
Testing webhooks locally
Webhook callbacks need a public HTTPS URL, which your laptop doesn't have. A tunnelling tool gives you one for the duration of a dev session:
- Start your webhook handler locally, for example on port 3000.
- Run a tunnel (
ngrok http 3000, or Cloudflare Tunnel, localtunnel, etc.) and copy thehttps://…URL it prints. - Create a subscription pointing at it:
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": "dev-secret"
}'import os, requests
auth = (os.environ["EZTEXTING_USERNAME"], os.environ["EZTEXTING_PASSWORD"])
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": "dev-secret",
},
timeout=30,
).json()
# keep it so you can delete the subscription later
print(sub["id"])const credentials = Buffer.from(
`${process.env.EZTEXTING_USERNAME}:${process.env.EZTEXTING_PASSWORD}`
).toString("base64");
const sub = await (await fetch("https://a.eztexting.com/v1/webhooks/subscriptions", {
method: "POST",
headers: { Authorization: `Basic ${credentials}`, "Content-Type": "application/json" },
body: JSON.stringify({
type: "inbound_text.received",
callbackUrl: "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
secret: "dev-secret",
}),
})).json();
// keep it so you can delete the subscription later
console.log(sub.id);<?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" => "dev-secret",
]),
]);
$sub = json_decode(curl_exec($ch), true);
curl_close($ch);
// keep it so you can delete the subscription later
echo $sub['id'], "\n";require "net/http"
require "json"
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: "dev-secret"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
# keep it so you can delete the subscription later
puts JSON.parse(res.body)["id"]String basicAuth = Base64.getEncoder().encodeToString(
(System.getenv("EZTEXTING_USERNAME") + ":" + System.getenv("EZTEXTING_PASSWORD")).getBytes());
String json = """
{
"type": "inbound_text.received",
"callbackUrl": "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
"secret": "dev-secret"
}
""";
HttpRequest request = 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(json))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
// keep the id so you can delete the subscription later
System.out.println(response.body());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 res = await client.PostAsJsonAsync("https://a.eztexting.com/v1/webhooks/subscriptions", new
{
type = "inbound_text.received",
callbackUrl = "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
secret = "dev-secret"
});
var sub = await res.Content.ReadFromJsonAsync<JsonElement>();
// keep it so you can delete the subscription later
Console.WriteLine(sub.GetProperty("id"));body, _ := json.Marshal(map[string]string{
"type": "inbound_text.received",
"callbackUrl": "https://a1b2c3d4.ngrok.app/webhooks/eztexting",
"secret": "dev-secret",
})
req, _ := http.NewRequest("POST", "https://a.eztexting.com/v1/webhooks/subscriptions", 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 sub struct{ ID string `json:"id"` }
json.NewDecoder(resp.Body).Decode(&sub)
// keep it so you can delete the subscription later
fmt.Println(sub.ID)- Text your EZ Texting number from your phone. The payload should hit your handler within seconds.
- Delete the subscription when you're done (
DELETE /v1/webhooks/subscriptions/{id}). Tunnel URLs are ephemeral; a dead callback URL will accumulate failures.
Keep your dev and production subscriptions separate. They're independent objects with independent secrets. List what's registered with GET /v1/webhooks/subscriptions whenever something looks off.
Pre-launch checklist
Before pointing production traffic at the API:
- Credentials come from environment variables or a secrets manager, never source control.
- If you use OAuth 2.0 tokens, refresh is handled before the 90-minute expiry. → Authentication
- Every number is normalized to 11 digits at the edge. → Phone number formatting
- Nothing sets
strictValidation: falseunless skipping bad numbers is intended. -
429responses are retried after theX-Rate-Limit-Retry-After-Millisecondsdelay, with a cap. → Rate limits - Reads and other idempotent operations are retried with backoff. If
POST /v1/messagestimes out or returns5xx, the code checks whether the send was accepted before submitting it again. → Idempotency & retries - Webhook handlers verify
X-Signature-256, respond2xxfast, and tolerate duplicate deliveries. → Webhooks - Something polls
GET /v1/creditsand alerts before the balance hits zero. - Opt-in is captured and recorded, and your messages include your business name (in the text or with
companyName) and opt-out language such as "Reply STOP to opt out". → Compliance - You've sent a real message to a real phone from the production environment and seen it in the delivery report.
Related
- Quickstart — your first send
- Webhooks — receiving and verifying callbacks
- Idempotency & retries — avoiding duplicate sends
- Troubleshooting
Try Troubleshooting, check status.eztexting.com, or contact support.
Updated about 18 hours ago