To send a text from plain PHP, call curl_init() on https://api.tryready.com/v1/messages, set a POST body of JSON, and pass your key in an X-API-Key header. That's the whole job. You don't need Composer, a framework or an SDK, because the cURL extension ships with almost every PHP build.
We make Ready, so the example uses Ready's REST API and only the request shape we document. The habits carry to any provider: build the payload with json_encode, set a timeout on every call, and send a stable idempotency key so a retry never texts someone twice. The code runs on PHP 8.0 or later.
What you need before the first request
Four things stand between you and a delivered text.
- An API key. Ready authenticates with an
X-API-Keyheader. Read it from the environment withgetenv('READY_API_KEY')and keep it out of version control. - A card and a number. A card on file and a number of your own are required to send. The number is $2 a month. To build first, create a test key (Settings, Developers, Environment: Test). It simulates every send with no card, number or charge.
- Consent. Each request carries
consent_attested: true, which is your statement that the recipient agreed to receive texts. Only set it when that's true. - A plan for registration. An account can send up to 500 texts a month until its 10DLC registration is approved. After that it has to register, and most approvals take 2 to 7 days. Our 10DLC explainer covers why carriers require it.
Every text is charged from the first one: $0.0075 per segment plus a $0.0045 carrier fee. Screening, the optional scrub and validation checks, is extra when you switch it on.
Send a text with cURL in PHP
The endpoint is POST https://api.tryready.com/v1/messages. The body takes to in E.164 format (a 10-digit US number is treated as +1), body, and consent_attested. Here's a complete script:
<?php
declare(strict_types=1);
function uuid4(): string {
$b = random_bytes(16);
$b[6] = chr((ord($b[6]) & 0x0f) | 0x40);
$b[8] = chr((ord($b[8]) & 0x3f) | 0x80);
return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($b), 4));
}
function send_text(string $to, string $body, string $idempotencyKey): array {
$ch = curl_init('https://api.tryready.com/v1/messages');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([
'to' => $to,
'body' => $body,
'consent_attested' => true,
], JSON_THROW_ON_ERROR),
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('READY_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: ' . $idempotencyKey,
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 20,
]);
$raw = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$error = $raw === false ? curl_error($ch) : null;
curl_close($ch);
return [$status, $raw === false ? '' : $raw, $error];
}
[$status, $raw, $error] = send_text('+12125550199', 'Your order #1042 has shipped.', uuid4());
echo $error ?? "$status $raw", PHP_EOL; Three choices are worth explaining. json_encode builds the payload, so a name with a quote or a newline can't produce broken JSON, which hand-built strings get wrong. CURLOPT_RETURNTRANSFER hands the body back instead of printing it. And the two timeouts stop a stalled connection from holding a PHP worker until the web server kills it.
The script prints the status and the raw body. For exact response fields and error bodies, use the messages API reference and the error codes page rather than a blog post's summary.
Why PHP needs the timeout
PHP's cURL has no default total timeout. If you leave CURLOPT_TIMEOUT out, a hung network call waits until max_execution_time ends the script, and under PHP-FPM that can pin a worker for 30 seconds or more. Set both timeouts on every call. Five seconds to connect and 20 to finish is a sensible start for a text.
Retries without double-sending
Networks fail. When a request times out you don't know whether the text went out, and retrying blindly can text a customer twice. Duplicate texts are a reliable way to collect opt-outs.
The fix is the Idempotency-Key header. Generate one UUID per logical message, store it with the message record, and send the same key on every attempt. A retried request with the same key doesn't send twice. This wrapper retries only the failures that are safe to retry:
function send_with_retry(string $to, string $body, string $key): array {
$delayMs = 500;
for ($attempt = 1; $attempt <= 4; $attempt++) {
[$status, $raw, $error] = send_text($to, $body, $key);
$retryable = $error !== null || $status === 429 ||
($status === 409 && str_contains((string) $raw, 'idempotency_in_progress'));
if (!$retryable) {
return [$status, $raw, null];
}
if ($attempt < 4) {
usleep($delayMs * 1000);
$delayMs *= 2;
}
}
return [$status, $raw, $error];
} The key is created once by the caller and passed in, never inside the loop. That's the detail people miss. For more on key design, see idempotency keys and duplicate texts and deterministic idempotency keys.
What the status code tells you
| Outcome | What to do |
|---|---|
| 2xx | Store the response body against your message record. |
| 4xx other than 429 and the 409 below | Don't retry. Fix the request or the account, then send again. |
| 429 | Retry with backoff and the same key. |
409 idempotency_in_progress | The first try is still running. Wait and retry with the same key. |
| cURL error or timeout | Retry with backoff and the same key. |
| 503 | Nothing was sent or charged, and the same key would replay the stored error. Send again with a new key. |
| 500 or 504 | Check GET /v1/messages before sending again. The message may have gone out. |
One case deserves a special mention. An API text to someone in quiet hours is held only if the window opens soon. Otherwise it isn't sent and the API answers 409 QUIET_HOURS_BLOCK, so your code should send it again once the window opens. Our post on handling the quiet hours 409 shows how.
Keep the key out of your code
Never paste the key into a PHP file in your web root. Set READY_API_KEY in the environment of PHP-FPM or your cron wrapper, and rotate it when someone leaves. If a log line prints request headers, scrub that header first. Our guide to API key security and rotation covers the checklist.
Next step
Start with a test key and the script above, and confirm you get a 2xx and a message record. Then add the card and number, flip to a live key, and let your retry wrapper reuse the same idempotency key. If you'd rather see the same flow in another language, the Go example uses the same request shape. The API quickstart walks through the key, a first send and a webhook.
Accounts opened before November 12, 2026 keep their signup prices, shown under Billing.