Forward SMS codes

Forward selected text messages from your own phone into a Lumbox inbox. The messages are stored as SMS, parsed for authentication codes, and available through the existing /otp and /wait endpoints. SMS is receive-only in Lumbox.

The forwarding URL is a secret credential. Anyone who has it can inject messages into that inbox. Share it only with your phone, forward only messages you need, and rotate or revoke it from the inbox's Forward SMS panel if it is exposed. Rotation immediately invalidates the old URL.

Ingest contract

The phone sends a POST request to the URL shown in the inbox panel. No API key or custom header is required.

POST https://api.lumbox.co/v1/sms/{inbox_id}?token=sms_...

The endpoint accepts application/json, application/x-www-form-urlencoded, and text-only multipart/form-data. The maximum request body is 16 KiB. The message text is limited to 8 KiB and the sender to 128 characters. Requests are limited to 60 per minute per IP and 30 per minute per inbox.

If no receive time is supplied, Lumbox uses the request time. A receive time more than five minutes in the future is rejected. sentStamp is used for freshness filtering and duplicate detection; the Android app calculates receivedStamp when preparing its request. Forwarders without a stable original timestamp may produce duplicates if they retry.

A successful new message returns 201 with an acknowledgement and message ID. A recognized retry returns 200 with the same message ID. Codes are never returned to the URL credential.

iPhone setup (iOS 26, Shortcuts)

Apple documents personal automations triggered by messages, sender and message-content conditions, API requests with JSON or Form bodies, and automatic execution for Message automations. Labels can differ by iOS version. This sequence uses Apple's iOS 26 guide. The message-content variable choice depends on the device and has not been verified on a physical iPhone, so check the selected variable before enabling it.

1. Open the inbox in Lumbox and copy the URL from Forward SMS.
2. In Shortcuts, open Automation. Tap the add button if you already have automations, then choose Create Personal Automation.
3. Select Message. Choose a sender, a message phrase, or both to limit which messages are forwarded. Tap Next.
4. Add the Get Contents of URL action and paste the Lumbox URL. Expand the action, set the method to POST, and set Request Body to JSON.
5. Add from with the sender number or name shown by your Messages app. Add text using the incoming message content variable supplied by the Message automation. Confirm on-device that it is the message body, not the sender or the automation metadata.
6. Save the automation. In its settings, enable Enable This Automation. To run without a confirmation prompt, turn off Ask Before Running, confirm Don’t Ask, then tap Done. Apple notes that individual actions may also have automatic execution settings.
7. Test using a harmless message containing Your verification code is 482913 from the selected sender.
8. Confirm the inbox shows an SMS badge, then call /v1/inboxes/{id}/otp with your normal API key and verify it returns 482913.

References: Apple's Message trigger options, create a personal automation for iOS 26, automatic execution in iOS 26, Get Contents of URL request bodies, Shortcuts variables.

Android setup (Incoming SMS to URL forwarder)

Install Incoming SMS to URL forwarder by bogkonstantin from its GitHub releases or F-Droid. Grant its receive-SMS permission. On Android 13 and later, notification permission controls its status-bar indicator. Some phone makers require an autostart or background-running setting.

1. Create a forwarding configuration for the sender you want. Use the sender value displayed in your Messages app.

2. Paste the URL copied from the Lumbox inbox's Forward SMS panel.

3. Keep the app's JSON POST template and use these fields:

   {
     "from": "%from%",
     "text": "%text%",
     "sentStamp": %sentStamp%,
     "receivedStamp": %receivedStamp%
   }

4. Save the rule and use the app's Test button. Then test with a harmless real SMS.

5. Confirm the message appears with an SMS badge and /v1/inboxes/{id}/otp returns its code. If delivery stops, check the app's error log, network access, and the phone's background or battery restrictions.

The app documents JSON POST requests, retry behavior, and the timestamp placeholders in its README. sentStamp is the SMS's original send time in milliseconds. receivedStamp is computed while building the request.

SmsForwarder form example

pppscn/SmsForwarder documents URL-encoded POST fields named from, content, and timestamp. Its timestamp represents request time, not the original SMS time, so Lumbox does not use it for freshness filtering or deduplication.

Equivalent form body:

from=%2B14155550123&content=Your+verification+code+is+482913

The + in an international sender must be percent-encoded as %2B in URL-encoded form data.

Retrieve a code

Use your ordinary Lumbox API key for reads. The forwarding URL only grants permission to submit a message to one inbox.

curl "https://api.lumbox.co/v1/inboxes/inb_abc/otp?from=%2B14155550123&timeout=30" \
  -H "X-API-Key: ak_..."

To wait for any new message containing an authentication code:

curl "https://api.lumbox.co/v1/inboxes/inb_abc/wait?has_otp=true&timeout=60" \
  -H "X-API-Key: ak_..."

Responses identify the source with channel: "sms". since filters by receive time and excludes an SMS whose known original send time is older than the requested time. SMS messages cannot be replied to.

Phone automations and background apps can be delayed or stopped by device settings. Sender identity is whatever the phone reports and is not independently authenticated by the mobile carrier.

Kumar