A Flutter app should never call an SMS API directly. Put a small backend between them: the app calls your server, and your server calls https://api.tryready.com/v1/messages with the API key. Anything compiled into an app can be pulled out of the binary, so a key embedded in Dart code is a key you've published.
We make Ready, so the example uses our REST API and only the request shape we document. Since Dart runs on the server too, you can write both halves in one language: a shelf server, and a Flutter function that calls it. The code assumes Dart 3 and the shelf, shelf_router and http packages.
What you need before the first request
- An API key, held only by the server. Ready authenticates with an
X-API-Keyheader. Read it fromPlatform.environment. - 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. For development, 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, your statement that the recipient agreed to receive texts. Your backend should set it only after checking that your own records say so. - Registration. An account can send up to 500 texts a month until its 10DLC registration is approved, and most approvals take 2 to 7 days. Our 10DLC explainer has the background.
Each segment costs $0.0075 plus a $0.0045 carrier fee, with screening extra when switched on.
The architecture in three lines
- The app sends a request to your backend with the user's session token and an idempotency key it made for this tap.
- The backend checks who the user is, whether they may text this contact, and whether consent is on file.
- The backend calls Ready and passes the same idempotency key along.
The app never sees the Ready key, never builds the Ready request, and can't be used to text arbitrary numbers. For the wider pattern, see sending SMS from a mobile app backend.
The Dart server
import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'package:http/http.dart' as http;
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as io;
import 'package:shelf_router/shelf_router.dart';
final readyKey = Platform.environment['READY_API_KEY']!;
Future<bool> userMayText(String? token, String to) async {
// Your own check: valid session, this contact belongs to this user,
// and consent is on record. Return false to refuse.
return token != null && token.isNotEmpty;
}
Future<Response> sendText(Request req) async {
final key = req.headers['idempotency-key'];
final token = req.headers['authorization'];
final data = jsonDecode(await req.readAsString()) as Map<String, dynamic>;
final to = data['to'] as String?;
final body = data['body'] as String?;
if (key == null || to == null || body == null) {
return Response(400, body: '{"error":"to, body and Idempotency-Key required"}');
}
if (!await userMayText(token, to)) return Response(403);
final http.Response upstream;
try {
upstream = await http
.post(
Uri.parse('https://api.tryready.com/v1/messages'),
headers: {
'X-API-Key': readyKey,
'Content-Type': 'application/json',
'Idempotency-Key': key,
},
body: jsonEncode({'to': to, 'body': body, 'consent_attested': true}),
)
.timeout(const Duration(seconds: 20));
} on TimeoutException {
// The text may already be out: answer unknown so the app retries with the same key.
return Response(504,
body: '{"status":"unknown"}', headers: {'content-type': 'application/json'});
}
return Response(upstream.statusCode,
body: upstream.body, headers: {'content-type': 'application/json'});
}
Future<void> main() async {
final router = Router()..post('/texts', sendText);
await io.serve(router.call, InternetAddress.anyIPv4, 8080);
} The userMayText stub is where your product logic goes. It matters more than the HTTP call, because it's the only thing stopping a signed-in user from asking your server to text anyone. The server relays Ready's status and body as they are, so the app can decide what to show. For response fields and error bodies, use the messages API reference and the error codes page.
The Flutter call
import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:uuid/uuid.dart';
class TextAttempt {
final String key = const Uuid().v4(); // one per tap, kept for retries
Future<int> send(String token, String to, String body) async {
final res = await http
.post(
Uri.parse('https://api.yourapp.example/texts'),
headers: {
'Authorization': token,
'Content-Type': 'application/json',
'Idempotency-Key': key,
},
body: jsonEncode({'to': to, 'body': body}),
)
.timeout(const Duration(seconds: 25));
return res.statusCode;
}
} The detail that matters is where the key is created. Make the TextAttempt object when the user taps Send, and call send on it again if the network drops. The same key travels to Ready on every attempt, and a retried request with the same key doesn't send twice. Creating a new key inside send would defeat the point. The idea is covered in depth in idempotency keys and duplicate texts.
What the app should do with each status
| Status from your backend | App behavior |
|---|---|
| 2xx | Show sent. Keep the attempt object until the screen closes. |
| 400 or 403 | Show an error. Retrying won't help. |
| 429, 5xx or a timeout | Retry with the same attempt object, after a short delay. |
409 idempotency_in_progress | The first attempt is still running. Retry the same attempt object after a few seconds. |
409 QUIET_HOURS_BLOCK | The recipient is in quiet hours. Offer to send it later. |
An API text in quiet hours is held only if the window opens soon. Otherwise it isn't sent, and the API answers 409 QUIET_HOURS_BLOCK. See handling the quiet hours 409.
Keep the key rotatable
Store the key in your host's secret manager, not in the repo or the container image. If it leaks, rotate it without shipping a new app build, which is another reason to keep it server-side. The API key security and rotation guide has a checklist.
Next step
Run the server locally with a test key, point a debug build of the app at it, and send to a made-up number like +12125550199. Confirm the same key gives one message when you tap twice. Then add the card and number and switch to a live key. The API quickstart covers the first send and a webhook for replies.
Accounts opened before November 12, 2026 keep their signup prices, shown under Billing.