A RabbitMQ consumer that sends texts needs four settings. Turn off auto-ack and acknowledge only after the SMS API answers, use the message id as the Idempotency-Key, route failures to a dead-letter exchange, and set prefetch to cap how many sends are in flight. Together they turn RabbitMQ's at-least-once delivery into one text per message.
We make Ready, so the example calls our REST API with the one request shape we document. The consumer uses amqplib on Node 18 or later as a familiar example. The same logic applies in any client library.
Why manual acks are the whole point
With auto-ack on, RabbitMQ treats a message as done the moment it hands it to you. If your process crashes during the HTTP call, the text is gone and nobody knows. With manual acks, the broker keeps the message until you confirm it, and if your channel closes first it goes back to the queue.
That gives you at-least-once delivery. The cost is that a message can arrive twice: you send the text, the process dies before the ack, and the broker redelivers. That window is small, but at any real volume you'll hit it. The next section closes it.
Set the message id once, at publish time
The idempotency key must be the same on every attempt for the same text. AMQP already has a field for this: the messageId property. Set it when you publish and never change it.
channel.sendToQueue(
'sms.send',
Buffer.from(JSON.stringify({
to: '+12125550199',
body: 'Your order #1042 has shipped.',
})),
{ persistent: true, messageId: crypto.randomUUID(), contentType: 'application/json' },
); Mark the message persistent and declare the queue durable, or a broker restart loses your texts. If the text comes from a business event, such as an order id plus a message type, you can derive the id instead of generating a random one. Our post on deterministic idempotency keys for SMS covers when that's the better choice, and duplicate texts and idempotency covers why the header matters.
The consumer: ack after the send
Declare the queue with a dead-letter exchange, set prefetch, and consume with noAck: false.
await channel.assertExchange('sms.dead', 'direct', { durable: true });
await channel.assertQueue('sms.dead.queue', { durable: true });
await channel.bindQueue('sms.dead.queue', 'sms.dead', 'sms.send');
await channel.assertQueue('sms.send', {
durable: true,
arguments: {
'x-dead-letter-exchange': 'sms.dead',
'x-dead-letter-routing-key': 'sms.send',
},
});
// A message waits here for 30 s, then its dead-letter settings send it back to sms.send.
await channel.assertQueue('sms.retry', {
durable: true,
arguments: {
'x-message-ttl': 30000,
'x-dead-letter-exchange': '',
'x-dead-letter-routing-key': 'sms.send',
},
});
const MAX_ATTEMPTS = 5;
await channel.prefetch(5);
await channel.consume('sms.send', async (msg) => {
const id = msg.properties.messageId;
const { to, body } = JSON.parse(msg.content.toString());
const outcome = await send(id, to, body);
if (outcome === 'done') channel.ack(msg);
else if (outcome === 'retry') {
const attempts = (msg.properties.headers?.['x-attempts'] ?? 0) + 1;
if (attempts >= MAX_ATTEMPTS) {
channel.nack(msg, false, false); // out of attempts: dead-letter it
} else {
// Same messageId, so the same Idempotency-Key on the next try. A crash between
// these two calls only leaves a duplicate message, and the key makes that harmless.
channel.sendToQueue('sms.retry', msg.content, {
persistent: true,
messageId: id,
headers: { 'x-attempts': attempts },
});
channel.ack(msg);
}
}
else channel.nack(msg, false, false); // dead-letter it
}, { noAck: false }); The second argument to nack is "all up to this one" and should stay false. The third is requeue. Requeue puts the message straight back with no delay and no count, which is why the retry branch above publishes to the sms.retry queue with an attempts header instead. Leaving requeue false sends the message to the dead-letter exchange, because the queue has one configured.
The send function
async function send(id, to, body) {
try {
const res = await fetch('https://api.tryready.com/v1/messages', {
method: 'POST',
headers: {
'X-API-Key': process.env.READY_API_KEY,
'Content-Type': 'application/json',
'Idempotency-Key': id,
},
body: JSON.stringify({ to, body, consent_attested: true }),
signal: AbortSignal.timeout(35000), // the API may take up to 30 s to answer
});
if (res.ok) return 'done';
if (res.status === 429) return 'retry';
// The first try under this key is still running: try again later with the same key.
if (res.status === 409 && (await res.text()).includes('idempotency_in_progress')) return 'retry';
return 'dead';
} catch {
return 'retry';
}
} Read consent_attested from your consent record for that contact rather than hardcoding it. Until January 20, 2027 (UTC) a send without it still goes out with a warning and no attestation; from that date the API refuses it with 403 api_consent_attested_required.
Sort failures instead of looping on them
Plain requeueing has a trap: a rejected message goes straight back to the front of the queue, and a message that will never succeed spins forever. Decide per failure what happens.
| Outcome | What it means | Action |
|---|---|---|
| 2xx | Text accepted | ack |
429, timeout, 409 idempotency_in_progress | Transient | Retry with the same id, with a ceiling |
| 503 | Nothing was sent or charged, and the same id would replay the stored error | nack without requeue; a replay job republishes it with a new id |
| 500, 504 | The message may have gone out | nack without requeue, then check GET /v1/messages and republish only if it is missing |
| Other 4xx | The request is wrong and will fail every time | nack without requeue, to the dead-letter exchange |
409 QUIET_HOURS_BLOCK | Outside the sending window | Delay, then retry after the window opens |
For the ceiling, count attempts. Quorum queues track redeliveries and support a delivery-limit argument that dead-letters a message after that many. On classic queues, keep a counter in a header and publish the message again with it incremented. For a delay, send the message to a retry queue with an x-message-ttl and a dead-letter exchange pointing back at the main queue, so it returns on its own after the wait.
A quiet hours refusal belongs in the delayed path, not the dead-letter queue. The API holds a text only if the window opens soon; otherwise it refuses and the sender resends once the window opens. See handling the quiet hours 409 and the API error reference for the codes.
Someone should own the dead-letter queue. Alert on its depth, and decide in advance whether a human replays those messages or discards them.
Size prefetch to your rate
Prefetch is the number of unacknowledged messages RabbitMQ lets a consumer hold. It limits concurrency, not messages per second, but concurrency and latency set the rate.
A worked example, with assumed numbers: if each API call takes about 200 ms and prefetch is 5, one consumer completes at most about 25 sends a second. Two consumers double that. Pick a prefetch that keeps you under the rate you plan to send at, not the highest one your hardware allows.
Carrier throughput is its own ceiling. A fresh standard 10DLC campaign carries only a few segments per second, and higher tiers reach roughly tens. Check the limits in the messages API docs and read our notes on SMS API rate limits. A deep queue is fine here. It's the buffer doing its job.
Don't set prefetch to zero. That means unlimited, and a backlog of a hundred thousand messages would land in one consumer's memory.
Takeaways
Ack after the send, set messageId at publish and reuse it as the Idempotency-Key, dead-letter what can't succeed, and keep prefetch low enough to match your rate. If your texts start as database writes, put an outbox in front of the publisher so a text isn't lost between the commit and the publish. Our SMS queue design for platforms post covers that and per-tenant fairness. When you're ready to wire a consumer to a real number, sign up and send a first message.