---
title: "sms-relay: SMS backend with retrying delivery · Lázaro Santana"
description: "Cloudflare Workers and D1 backend that receives SMS from an Android app and forwards them to Telegram and a signed webhook, with retries. 300+ tests, MIT."
url: https://lazarosantana.dev/en/projects/sms-relay/
---

personal project · open source · Cloudflare Workers

# A backend that delivers every *SMS*

sms-relay receives the SMS sent by the sms-forwarder app, stores each one once and forwards it to Telegram and a signed webhook. If a destination fails, it retries with a growing wait until it delivers or leaves a visible final state. I wrote all of it.

[Deploy to Cloudflare](https://deploy.workers.cloudflare.com/?url=https://github.com/Lacho00/sms-relay) [View the code](https://github.com/Lacho00/sms-relay)

*github.com/Lacho00/sms-relay*

Animated diagram: an SMS comes in through /ingest and is stored in the D1 outbox table; the Worker answers 200. It is then sent to two destinations, Telegram and a webhook signed with HMAC. The webhook fails once, waits one minute and delivers on the second attempt; Telegram delivers on the first. In the end, both deliveries are in the delivered state.

**300 +** automated tests

**≥ 95 %** coverage

**MIT** open source

What it is

A serverless backend that receives SMS and forwards them to Telegram and a webhook

My role

Idea, design and code, all on my own

Stack

TypeScript, Cloudflare Workers and D1, Hono, Zod, Drizzle

Partner

The Android app [sms-forwarder](https://lazarosantana.dev/en/projects/sms-forwarder/), which sends it the SMS

// the problem

## Never lose an SMS

A phone that forwards SMS retries when something fails. If the server is not ready for that, the same message arrives twice, or a Telegram error takes the SMS down with it.

sms-relay stores first and delivers after. Each destination has its own status, its own retry and a visible end: delivered or failed.

01

### One SMS, one copy

Each message gets a sha256 key built from the sender, the time and the text. If the phone retries, the answer is "duplicate" and nothing new is created.

02

### Transactional outbox

The message and one pending delivery per destination are saved together in a single D1 batch. The Worker answers 200 once everything is stored, not before.

03

### At-least-once delivery

If a destination answers with a temporary error, the retry follows a wait that grows from 1 minute to 1 hour and honors the Retry-After header when it asks for more.

04

### 60-second leases

Each delivery is claimed with a 60-second lease. The immediate attempt and the cron that runs every minute never send the same row at the same time.

// the contract

## Every code has an effect

The app and the backend agree through the status code. A phone-side error is not retried; a server-side one is, so fixing the configuration costs no SMS.

// what the backend answers

- `200`*stored or duplicate*
- `400 · 401`*error, manual retry*
- `429`*retry*
- `503`*retry, the SMS is kept*
- `500`*retry*

An oversized body returns 400, not 413, because the app retries a 413 and that request can never succeed.

// guarantees

## What never leaks

A backend that handles SMS sees verification codes and personal data. Each decision below is there to keep that from leaking.

**Logs without data** Logs never contain the SMS text, the sender, the tokens or the chat IDs. Even internal errors are logged without their message.

**Constant-time tokens** Tokens are compared in constant time. There is one to send and a different one to read: a token leaked from the phone does not open the archive.

**Signed webhook** The webhook carries an HMAC-SHA256 signature over the timestamp and the body. The signed timestamp lets you reject a captured request that is replayed later.

**Per-IP limit** Ingest and the read API have a request limit per IP address. Going over it returns a 429 that the app knows how to retry.

**Alerts without content** When a delivery fails for good, a single Telegram alert arrives with the id, the destination and the error. It never includes the SMS.

**Long SMS, in parts** A text over 4,096 characters is sent to Telegram in numbered parts. If it fails halfway, the retry resumes at the first part that was not sent.

**Retention with purge** Messages are deleted after a configurable period. A cron applies it every minute, and a message with a pending delivery is kept until it ends.

// the E2E

## The real test found the bug

`sms-forwarder v2.1.3` fixed

### A regex Android rejected

Before calling the system done I tested it end to end against production: the app on a phone, the backend on Cloudflare. The test uncovered a crash in the Android app: a regular expression that Android's ICU engine did not accept and that no test on the computer could have caught. I fixed it in sms-forwarder v2.1.3.

// in numbers

## Project in numbers

**300 +** automated tests, run against a real local D1 database

**≥ 95 %** coverage on lines, statements and functions, and ≥90% on branches

**~ 1,700** lines of source code

**3** runtime dependencies: Hono, Zod and Drizzle

sms-relay is a personal tool, not client work: there are no business results to report. The numbers come from the repository.

TypeScript Cloudflare Workers D1 Hono Zod Drizzle ORM Vitest Wrangler GitHub Actions

// try it

[Deploy to Cloudflare](https://deploy.workers.cloudflare.com/?url=https://github.com/Lacho00/sms-relay) [View the code](https://github.com/Lacho00/sms-relay)

[← all tools](https://lazarosantana.dev/en/#p-tools) personal project

// your project

## Got a project in mind?

Tell me what you need. I reply within 24 hours and, if it is a fit, you get a fixed written proposal.

[Request a quote](https://lazarosantana.dev/en/contact/#form) [See services](https://lazarosantana.dev/en/services/)
