To test an SMS API in Postman, put the key in an environment variable, send it as an X-API-Key header, generate an Idempotency-Key UUID in a pre-request script, and add a few pm.test assertions on status and body. Use a test key while you build, so nothing is sent or charged. Insomnia works the same way with its own template tags.
A collection is the fastest way to learn how an API behaves before you write code, and it doubles as a shared smoke test your whole team can run. This guide builds one for Ready's POST /v1/messages and POST /v1/messages/bulk, then runs it in bulk with the collection runner. We make Ready, but the structure fits any REST SMS API.
Set up the environment
Create an environment called ready-test with these variables.
| Variable | Value | Type |
|---|---|---|
base_url | https://api.tryready.com | default |
ready_key | your test key | secret |
test_to | +12125550199 | default |
Mark the key as a secret so Postman masks it, and never commit an exported environment file with a real key in it. Make a second environment, ready-live, for real sends, and give it a visibly different name. The commonest mistake with a collection is running a test folder against the live environment. Our API key security and rotation post covers key handling.
The test number is in the reserved 555-01xx range and is fine for a test key. If you later run the collection against a live key, change it to a phone you own, with the owner's agreement. A test text is still a text.
What a test key does
A test key simulates POST /v1/messages and POST /v1/messages/bulk: nothing is sent or charged, and each result has a test-msg- id and its segments. Writes it can't simulate answer 403 test_key_not_allowed. The test keys docs have the full detail. A simulated send proves your request shape and your assertions. It doesn't prove delivery, carrier filtering or quiet hours, as SMS API sandbox and test numbers explains.
Build the send request
Add a request: method POST, URL {{base_url}}/v1/messages. Set the headers.
| Header | Value |
|---|---|
X-API-Key | {{ready_key}} |
Idempotency-Key | {{idem_key}} |
Content-Type | application/json |
The body, in raw JSON mode:
{
"to": "{{test_to}}",
"body": "Postman check: your order #1042 has shipped.",
"consent_attested": true
} Setting consent_attested to true is your promise that the recipient agreed to texts. With a test key and a made-up number the promise costs nothing, but keep the habit. For the first send, the curl version is a useful cross-check.
Generate an Idempotency-Key in a pre-request script
Open the Pre-request Script tab and paste this. Postman's dynamic {{$guid}} variable makes a fresh UUID, and the script stores it so the header and your tests see the same value.
const key = pm.variables.replaceIn("{{$guid}}");
pm.environment.set("idem_key", key); That gives every run its own key, so each run is a new send. To test that a retry doesn't send twice, skip the script on a second request and reuse the stored idem_key. Duplicate the request, remove its pre-request script, and run both back to back: they share a key, so the API should treat the second as the same send. Idempotency keys and duplicate texts explains what to expect.
In Insomnia, use the template tag instead. Type uuid in the header value field, choose the UUID tag and pick version 4. Insomnia has no pre-request script in every version, so the tag is the portable choice. Check your version's docs for scripting support.
Write tests that assert something
The Tests tab runs after the response. Keep each assertion small and named.
pm.test("status is a success", () => {
pm.expect(pm.response.code).to.be.oneOf([200, 201, 202]);
});
pm.test("responds within 3 seconds", () => {
pm.expect(pm.response.responseTime).to.be.below(3000);
});
pm.test("test key returns a simulated id", () => {
pm.expect(pm.response.text()).to.include("test-msg-");
}); Add a negative case in the same folder. Duplicate the request, delete its X-API-Key header and assert the refusal:
pm.test("missing key is refused", () => {
pm.expect(pm.response.code).to.be.oneOf([401, 403]);
}); And another with the to field removed, asserting a 4xx:
pm.test("bad body is a client error", () => {
pm.expect(pm.response.code).to.be.within(400, 499);
}); We assert ranges and not exact codes where the docs don't promise one. A test that is stricter than the contract breaks on a harmless change. The error codes reference lists what the API does promise, and error codes and troubleshooting covers reading failures.
Run bulk checks with the collection runner
The collection runner repeats a request once per row of a data file. Make a CSV with a column per variable:
to,body
+12125550101,Postman check one
+12125550102,Postman check two
+12125550103,Postman check three In the request body, replace the fixed values with {{to}} and {{body}}. Postman fills data-file columns as iteration variables, so they win over environment values of the same name. In the runner, pick the collection and the ready-test environment, upload the file, and run. Every row gets its own pre-request script, so every row has its own idempotency key, and the results table shows each test per row.
For POST /v1/messages/bulk, put the recipients in a JSON array. At most 100 recipients go in one call, so a runner file is a good place to test your batch-splitting too. Bulk chunking and partial failures has the pattern for real code.
Run it in CI with Newman
Postman's command-line runner, Newman, replays a collection without the app. Export the collection and the ready-test environment, with the key value in the template written as ${READY_TEST_KEY}, then:
envsubst < ready-test.template.json > ready-test.json
newman run ready-collection.json -e ready-test.json -d recipients.csv The envsubst step fills the key from an encrypted CI secret, so it never sits in the repository. A failing assertion gives a nonzero exit code, so the pipeline fails on its own. Run it only against a test key. Against a live key, every row is a real text, billed at $0.0075 plus a $0.0045 carrier fee per segment, $0.012 all-in, and a 200-row file at one segment each would cost 200 x $0.012 = $2.40. Accounts opened before November 12, 2026 keep their signup prices, shown under Billing.
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.
A short checklist
- The key lives in a secret environment variable, not in the request.
- Test and live environments have different names and different keys.
- Each run generates its own
Idempotency-Key, and one request reuses a key on purpose. - Assertions cover status, latency, the simulated id and two failure cases.
- The runner file uses made-up numbers.
A collection won't replace code-level tests. It's a fast way to see the API's behavior and a cheap smoke test for a deploy. For code, pair it with mocking the SMS API in unit tests, and start from the API quickstart when you're ready to send for real.