Have Codex put the Telmian calls in your app's server code, never in the browser. Keep TELMIAN_API_KEY in an uncommitted .env file or your host's settings. Codex writes a route that posts to /v1/verify and /v1/verify/check. In the Codex CLI or IDE you can also add Telmian's MCP server in ~/.codex/config.toml.
Get a sandbox key
Run the Telmian CLI in your project. It writes a sandbox key (sk_test_) to .env, so you can test for free with no card. Check that .env is listed in .gitignore so the key is never committed.
npx telmian@1 initPut the SMS rules in AGENTS.md
Codex reads AGENTS.md files from the repo root down to the folder it works in. Add the Telmian rules to the AGENTS.md at the repo root so Codex follows them on every task.
## SMS - SMS uses Telmian. Call it only from server-side code (npm package 'telmian' or REST). - new Telmian() reads TELMIAN_API_KEY from env. Never expose the key to the client or commit it. - REST base https://app.telmian.com/v1, header Authorization: Bearer <key>. - For login codes use Telmian's /v1/verify and /v1/verify/check. Do not build our own OTP. - In tests use the sandbox numbers +393000000001 and +393000000002.Optional: add the MCP server (CLI and IDE)
If you use the Codex CLI or IDE extension, you can add Telmian's MCP server so Codex can look up your sandbox details while it builds. The login command opens your browser to sign in, and real charged sends stay off unless you tick that option at consent. Codex cloud has no direct MCP configuration, so skip this step there.
codex mcp add telmian --url https://app.telmian.com/mcp codex mcp login telmian # same thing in ~/.codex/config.toml [mcp_servers.telmian] url = "https://app.telmian.com/mcp"Ask Codex for a server route
Prompt something like: "Add phone OTP login using Telmian per AGENTS.md; put the send and verify calls in a server route." The route should look like this. Use one Idempotency-Key per signup attempt and reuse the same key if you retry.
const res = await fetch('https://app.telmian.com/v1/verify', { method: 'POST', headers: { Authorization: `Bearer ${TELMIAN_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': signupAttemptId }, body: JSON.stringify({ phone }) }); const check = await fetch('https://app.telmian.com/v1/verify/check', { method: 'POST', headers: { Authorization: `Bearer ${TELMIAN_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ phone, code }) }); const { valid } = await check.json();Let Codex reach the API during tests
In the CLI and IDE, the default workspace-write sandbox has network access off, so Codex cannot call app.telmian.com. Turn it on in config.toml. In Codex cloud, choose limited internet access and add app.telmian.com, and store the test key as an environment variable, because secrets are removed before the agent phase.
[sandbox_workspace_write] network_access = trueTest with the sandbox numbers
With an sk_test_ key, SMS are simulated and nothing is charged. +393000000001 always receives code 000000, and +393000000002 always fails, so you can test both paths.
Go live
In the panel at https://app.telmian.com, create an sk_live_ key, set your approved business name and make your first top-up (from €5). Put the live key in your host's environment settings, not in Codex. Real sends cost €0.05 per SMS segment plus VAT.
Questions
Does the Telmian MCP server work in Codex cloud?
Codex docs say cloud tasks reach remote MCP tools only through installed plugins, with no direct configuration. Use the MCP server from the Codex CLI or IDE extension. Cloud tasks can still write the server code that calls the Telmian API.
Why can't Codex call app.telmian.com when it runs my tests?
Network access is off by default. In the CLI and IDE, set network_access = true under [sandbox_workspace_write] in config.toml. In Codex cloud, allow app.telmian.com in the environment's internet access settings.
Where do I keep the API key in Codex cloud?
In Codex settings > Environments. Use an environment variable, not a secret: secrets are removed before the agent phase, so only the setup script can use them. Put only a sandbox sk_test_ key there, and keep the live key in your host's settings.
Can Codex receive delivery reports and replies?
No. Codex writes code but does not give your app a public URL. Point Telmian's webhooks at your deployed app and check the signature with verifyWebhook from the SDK.
How much does it cost to send SMS from a Codex-built app?
The sandbox is free and needs no card. Real SMS cost €0.05 per segment to mobile numbers in 44 European countries, plus VAT, prepaid by card from €5. There is no monthly fee, and SMS refused by the network or not delivered are refunded automatically.
Updated