SMSTunnel for Directus

A text from a Directus flow, sent by your own phone and number

Flows operation · Marketplace and npm · Directus 11 and 12 · MIT
Send a text with SMSTunnel

One operation, one text per run

A flow hands the text to your SMSTunnel account, and your own Android phone sends it from its own SIM, so people see a number they know and can reply to. No SMS provider account and no sender registration: the phone runs the SMSTunnel app and is linked to your account. You can cut Directus off at any time by deleting its API key in your dashboard.

What it does

A Flows operation
Send a text with SMSTunnel: after an Event Hook, a Webhook, a Schedule (CRON), a Manual trigger or another operation. Every field takes {{ … }}.
The key stays out of your flows
The API key field reads {{ $env.SMSTUNNEL_API_KEY }}, and Directus redacts it in the flow logs.
Sandboxed
It runs in Directus' extension sandbox, which lets it call only https://smstunnel.io/api/v1/*.
Safe re-runs
An idempotency key per text: running it again with the same key within 24 hours sends nothing new.
Sign-in codes
Type Sign-in code: a code of 4 to 10 digits, on its own allowance.
Tested with
Directus 12.6.0 and 11.17.4.

1. Install

From the Marketplace (Directus 11 and 12): Settings → Marketplace, search for SMSTunnel, open it and click Install. The operation runs in Directus' extension sandbox, so the Marketplace installs it with its default trust setting (MARKETPLACE_TRUST=sandbox). The sandbox lets it call only https://smstunnel.io/api/v1/*.

By hand (self-hosted): put the package in your extensions folder and restart Directus:

cd extensions
npm pack @narcisbodea/smstunnel-directus
mkdir smstunnel-directus && tar -xzf narcisbodea-smstunnel-directus-*.tgz -C smstunnel-directus --strip-components=1

Tested with Directus 12.6.0 and 11.17.4.

2. Get your key

  1. 1. Install the SMSTunnel app from Google Play on your Android phone and sign in.
  2. 2. In your dashboard, open Apps → Add an app, pick Script or server, name it (for example "My Directus") and click Create the key.
  3. 3. Copy the key right away: it's shown only once. You can stop or delete the app there anytime, and My Directus can't send texts anymore.

Get the steps with your key in them

It opens Add an app with Script or server picked. Once the key is made, the dashboard shows every step and command with the key already filled in, ready to copy.

3. Give the key to Directus

Give it to Directus as an environment variable, and let flows read it:

SMSTUNNEL_API_KEY=sk_live_...
FLOWS_ENV_ALLOW_LIST=SMSTUNNEL_API_KEY

Restart Directus. The operation's API key field is already {{ $env.SMSTUNNEL_API_KEY }}: the key stays out of your flows, and Directus shows it as --redacted:SMSTUNNEL_API_KEY-- in the flow logs. (Pasting the key into the field works too, but then it is stored with the flow and appears in its logs; keep that for a quick test.)

4. Text each new item

For example a leads collection with name and phone fields:

  1. 1. Settings → Flows → Create Flow. Name it, choose the trigger Event Hook, type Action (Non-Blocking), scope items.create, collection leads.
  2. 2. Click + after the trigger and choose Send a text with SMSTunnel:
    To
    {{ $trigger.payload.phone }}
    Message
    Thanks {{ $trigger.payload.name }}, we got your request and will call you back today.
    Idempotency key
    lead-{{ $trigger.key }}
  3. 3. Save, then add a lead with your own number.

The same operation fits after a Webhook, a Schedule (CRON), a Manual trigger or another operation: every field takes {{ … }}.

API key
{{ $env.SMSTUNNEL_API_KEY }} (see above).
To
One number, in international format (+14155550123).
Type
Text, or Sign-in code: the text must then contain the code, 4 to 10 digits on their own (482913, or 123-456), 320 characters at most, and it counts against your sign-in code allowance.
Message
Up to 1600 characters.
Phone ID
Optional: the phone that sends, when your account has several (its ID is under Phones, with a Copy button). Empty: your phone that is online.
Country code
Optional, e.g. +40: completes numbers written without + or 00.
Idempotency key
Optional: one key per text. Running it again with the same key within 24 hours sends nothing new (the run reports replayed: true). Make it unique for good: a key used for another text in the last 24 hours is refused.

A {{ … }} that finds nothing (Directus then writes undefined) counts as empty for the optional fields, and as missing for To and Message.

What the next operations get

When the text is handed over, the operation resolves with:

{ "messageId": "6ae9952f7f9ac207c547af90", "to": "+14155550123", "status": "pending", "queued": false, "replayed": false }

status is queued when your phone is offline: the text waits in the queue on your account and goes out as soon as the phone is back online (up to 3 days). Read it later as {{ $last.messageId }} or {{ <operation key>.messageId }}.

When it isn't, the flow takes the operation's reject path, with:

{ "message": "SMSTunnel refused the API key: …", "status": 401, "mayHaveSent": false }
401
The API key is wrong, deactivated or deleted. Create a new one under Apps → Add an app.
403
The key lacks a permission, or your plan doesn't include what was asked.
429
Too many requests (30 sends a minute per key), or today's allowance of your plan is used up.
5xx, or none
SMSTunnel had a problem or didn't answer. mayHaveSent is true: check the Messages page in your dashboard before you send it again, or run it again with the same idempotency key.
400
SMSTunnel refused a field, such as a number it can't read or a code text without a code.
404
The phone ID isn't one of your phones.
422
The idempotency key was already used for a different text in the last 24 hours.

A number that isn't one, a list of numbers, an empty text or one over 1600 characters is refused before anything is sent (no status). Inside Directus' sandbox only SMSTunnel's status code reaches the extension, so the reasons above are worded from the status. The operation never resends a text by itself.

Several people

One run sends one text. To text a list, put the operation in its own flow (trigger Another Flow, To {{ $trigger.phone }}), and call that flow from a Trigger Flow operation whose payload is the list, for example {{ $last }} from a Read Data operation. Directus runs the flow once per item; choose Serial as the iteration mode to keep within 30 texts a minute.

Build it with an AI assistant

Copy this prompt into Claude, ChatGPT, Cursor or Copilot and replace the part in [brackets]. Don't paste your API key into the chat: the prompt doesn't need it.

Help me send texts from Directus with SMSTunnel.

About SMSTunnel (https://smstunnel.io): my own apps and tools hand text messages (SMS) to my SMSTunnel account, and my own Android phone sends them from my own number, on my own SIM and plan. The phone runs the SMSTunnel app from Google Play (https://play.google.com/store/apps/details?id=io.smstunnel.app), signed in to my account.

What I want: [describe what should send a text, to whom, and when]

How it works:
- Use the Directus extension @narcisbodea/smstunnel-directus (Marketplace: "SMSTunnel"; Directus 11 and 12). It adds the Flows operation "Send a text with SMSTunnel" (type id smstunnel-send-text) and runs in Directus' extension sandbox, which lets it call only https://smstunnel.io/api/v1/*.
- Its options: apiKey (keep "{{ $env.SMSTUNNEL_API_KEY }}"; Directus has SMSTUNNEL_API_KEY and FLOWS_ENV_ALLOW_LIST=SMSTUNNEL_API_KEY in its environment), to (one number in international format, e.g. "{{ $trigger.payload.phone }}"), kind ("text" or "code"; a code text must contain a code of 4 to 10 digits standing on its own, at most 320 characters), message (up to 1600 characters), deviceId (optional: which phone sends), defaultCountryCode (optional, e.g. "+40", completes numbers written without + or 00), idempotencyKey (optional, one per text: a re-run with the same key within 24 h sends nothing new).
- It resolves with { messageId, to, status: "pending" | "queued", queued, replayed } and rejects with { message, status, code?, retryAfter?, mayHaveSent }. One text per run: for a list, a Trigger Flow operation (iteration mode Serial) calls a flow that holds this operation once per item.
- Errors: 401 wrong key, 403 missing permission or plan, 429 too many requests or today's allowance used up, 5xx SMSTunnel problem (mayHaveSent: the text may have gone out: never resend without the same idempotency key), 404 a phone ID that isn't one of mine, 422 an idempotency key already used for a different text. If the phone is offline, the text waits in the queue (status "queued") and goes out when the phone is back online. 30 send requests a minute per key.
- Give me the flow step by step (trigger, its options, each operation and its options), plus the collection fields it needs. Skip the text with a Condition operation when there is no number, and handle the reject path (log it or notify an admin; don't loop back into the same operation).
- The API key comes from my SMSTunnel dashboard (https://dashboard.smstunnel.io): Apps → Add an app → Create the key. It is shown only once and can send texts and check whether they went out.

Rules for your answer:
- Keep the API key in an environment variable or the platform's secret store (for example SMSTUNNEL_API_KEY). Never put it in source code, in a repository, or in code that runs in a browser or a mobile app: call SMSTunnel from a server. I will not paste my key in this chat; use a placeholder.
- Validate phone numbers before sending (international format, like +14155550123) and skip or report the invalid ones.
- Handle errors: log or show what went wrong, retry only after 429, 5xx or network errors and only a few times, and never send the same text twice.
- Only send texts people expect from me: alerts to myself, reminders, sign-in codes, updates they asked for. No unsolicited texts.

Responsible use

Built for alerts to yourself and your team, and texts people expect from you. One text goes to one number. Sending unsolicited messages from a consumer SIM generally breaches mobile carrier terms of service.

Directus is a trademark of its owner. SMSTunnel is a third-party integration and is not affiliated with, endorsed by, or sponsored by Monospace Inc. or the Directus project.

No phone paired yet?

Install the Android app and sign in with your account, and you're ready in about a minute.

Get it on Google Play