To send an SMS from C#, make one HTTPS POST to an SMS provider's REST endpoint with HttpClient, put your API key in a header, and send the recipient and message as JSON. You don't need an SDK, a NuGet package or a vendor library for that. The rest of the work is handling failures without texting a customer twice.
We use the Ready API for the worked example because we make Ready and can vouch for every request shape in this post. The pattern carries over to any REST SMS provider: one long-lived client, an idempotency key per message, careful retries and batches for bulk. The code targets .NET 8 or later and uses only the standard library.
What you need before the first request
- An API key. Ready authenticates with an
X-API-Keyheader. Keep the key in an environment variable, user secrets or a vault, never in source control. - A card on file and a number of your own. Ready requires both to send, from the first text. The number is $2 a month.
- A registration plan. An account can send up to 500 texts a month before it registers, at its normal per-text rate. After that it has to register. Most approvals take 2 to 7 days. If you build for customers of your own, each one usually needs its own registration.
- Consent you can point to. The
consent_attestedfield is your promise that the recipient agreed to texts. Ready records that attestation per send. It does not store a per-contact consent record, so keep the opt-in in your own form or database.
Send one text with HttpClient
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.
Create one HttpClient for the life of the app. Creating a new one per request is a classic .NET mistake that exhausts sockets under load. In an ASP.NET Core app, register a typed client with AddHttpClient and let the factory manage it.
using System.Net.Http;
using System.Net.Http.Json;
public sealed class ReadySms
{
private readonly HttpClient _http;
public ReadySms(HttpClient http, string apiKey)
{
_http = http;
_http.BaseAddress = new Uri("https://api.tryready.com");
_http.Timeout = TimeSpan.FromSeconds(15);
_http.DefaultRequestHeaders.Add("X-API-Key", apiKey);
}
public async Task<HttpResponseMessage> SendAsync(
string to, string body, Guid idempotencyKey, CancellationToken ct = default)
{
var req = new HttpRequestMessage(HttpMethod.Post, "/v1/messages")
{
Content = JsonContent.Create(new
{
to,
body,
consent_attested = true
})
};
req.Headers.Add("Idempotency-Key", idempotencyKey.ToString());
return await _http.SendAsync(req, ct);
}
} Calling it looks like this:
var sms = new ReadySms(new HttpClient(), Environment.GetEnvironmentVariable("READY_API_KEY")!);
var key = Guid.NewGuid();
var res = await sms.SendAsync("+12125550199", "Your order #1042 has shipped.", key);
Console.WriteLine($"{(int)res.StatusCode} {await res.Content.ReadAsStringAsync()}"); JsonContent.Create serializes an anonymous object, so you never hand-build JSON and never break a payload because a customer's name contained a quote. Leave from out and Ready picks the number: the one this contact already texts with, otherwise your number closest to their area code. Two optional fields exist: from, one of your own numbers, and media_url, which sends a picture as MMS.
Retries without double-sending
Networks fail. If a request times out you don't know whether the text went out, and a blind retry can send it twice. Duplicate texts are one of the quickest ways to collect STOP replies.
The fix is the Idempotency-Key header. Generate one GUID per logical message, store it with the message row, and send the same key on every retry of that message. A retried request with the same key never sends twice. The full pattern is in idempotency keys and duplicate texts.
public async Task<HttpResponseMessage> SendWithRetryAsync(
string to, string body, Guid key, CancellationToken ct = default)
{
var delay = TimeSpan.FromMilliseconds(500);
for (var attempt = 1; ; attempt++)
{
try
{
var res = await SendAsync(to, body, key, ct);
var retryable = (int)res.StatusCode == 429
|| ((int)res.StatusCode == 409 && (await res.Content.ReadAsStringAsync(ct)).Contains("idempotency_in_progress"));
if (!retryable || attempt == 4) return res;
}
catch (Exception e) when (e is HttpRequestException or TaskCanceledException)
{
if (attempt == 4) throw;
}
var jitter = TimeSpan.FromMilliseconds(Random.Shared.Next(250));
await Task.Delay(delay + jitter, ct);
delay *= 2;
}
} A short rule set for that loop:
- Retry with the same key on timeouts, dropped connections, HTTP 429 and a 409
idempotency_in_progress(your first attempt is still running, so the same key returns its result once it finishes). - Keep the key constant across attempts. A fresh GUID per attempt defeats the point.
- Don't retry other 4xx answers. A malformed number or a bad key fails the same way on attempt four. Log the body and fix the input.
- Back off with jitter, so a fleet of workers doesn't hit the API in lockstep after an outage.
- Treat refusals as final. Ready refuses opted-out numbers, numbers on your Ban list and known landlines up front, and those aren't charged.
One refusal deserves its own branch. An API text is held only if the quiet-hours window opens within 6 hours. Otherwise it isn't sent, the API answers 409 QUIET_HOURS_BLOCK, and your code sends it again once the window opens. Don't loop on it. Park the message and schedule a retry after the window, or use POST /sms/schedule for a text meant for later. The error codes post and the API error reference list the rest.
Send to many numbers
For the same text to many recipients, use POST /v1/messages/bulk with to as an array. A call takes at most 100 recipients, so split larger lists. LINQ's Chunk does it in one line:
public async Task SendBulkAsync(string jobId, IEnumerable<string> numbers, string body, CancellationToken ct = default)
{
var i = 0;
foreach (var batch in numbers.Chunk(100))
{
var req = new HttpRequestMessage(HttpMethod.Post, "/v1/messages/bulk")
{
Content = JsonContent.Create(new { to = batch, body, consent_attested = true })
};
// Same job and batch number give the same key, so a re-run of the job does not text a batch twice.
req.Headers.Add("Idempotency-Key", $"{jobId}-{i++}");
var res = await _http.SendAsync(req, ct);
res.EnsureSuccessStatusCode();
}
} In real code, store each batch's key before you send it so a crash and restart reuses the key instead of creating a new one. The bulk messages reference has the response shape.
What a send costs
Ready bills per segment, and a segment isn't a message. A single SMS segment holds 160 GSM-7 characters. Longer texts split into 153-character segments. One emoji or other non-GSM character drops the limit to 70 characters (67 per segment on a multipart text), so a 140-character text with one emoji is 3 segments, not 1.
| Text | Characters | Encoding | Segments |
|---|---|---|---|
| "Your order #1042 has shipped." | 29 | GSM-7 | 1 |
| A 175-character reminder | 175 | GSM-7 | 2 |
| The same 140-character text plus one emoji | 140 | Unicode | 3 |
Each segment is billed at $0.0075 plus a $0.0045 carrier fee, which is passed through at cost. That's $0.012 per segment all-in, not including screening (the Scrub lists and Number validation switches, each $0.003 extra per segment when on). Replies you receive bill the same way. Accounts opened before November 12, 2026 keep their signup prices, shown under Billing. The pricing page has the full list.
Ready's all-in prices per segment include the carrier fee but not screening: Scrub lists and Number validation, the two switches in Settings under Compliance, each add $0.003 per segment when switched on, shown as screening on your bill, and both are off by default. Unless you turn the opt-out footer off, the first text to each contact, and one again from time to time, also gets "Reply STOP to opt out" and your business name if the message does not already have them, so a text close to the segment limit can bill one more segment.
Count segments in your own code before you send if you show users a cost estimate. A text that crosses a segment boundary by two characters costs a second segment. Keep PHI out of texts: Ready isn't HIPAA compliant and doesn't sign BAAs.
Test it, then read the replies
Run the first sends against your own phone. Check that the message arrives, then reply STOP and confirm a second send to that number is refused. Inbound STOP is honored automatically and the opt-out carries across campaigns, so your code doesn't need a handler for it.
To read replies and delivery results as they happen, run a small ASP.NET Core minimal API endpoint that Ready calls, and acknowledge fast. Hand the real work to a background queue. Receiving inbound texts with webhooks walks through that design, and the API quickstart covers key, first send and webhook in order.
The practical takeaway
Sending SMS from .NET is a typed HttpClient, one JSON body and two headers. The part that deserves your time is the retry rule: one idempotency key per logical message, retries only on failures that mean "try again", and a separate path for 409 quiet-hours answers. If you're building texting into a product, the guide to adding SMS to your app covers the design choices around this code. When you're ready to try it, sign up, buy a number and send the first text from the code above.