← All guides

Send SMS from Cursor: add OTP codes and texts to your app

Cursor is a code editor, so the SMS goes out from your app's server code, not from Cursor. Put a Telmian key in your project's .env file, call POST https://app.telmian.com/v1/verify from a server route, and check the code with /v1/verify/check. Optionally, add Telmian's MCP server to Cursor to help while you build.

Where each piece goes in a Cursor project
WhatWhere
Sandbox key (sk_test_)Your project's .env file, ignored by Cursor by default
Live key (sk_live_)Environment variables on the host that runs your app
Key for Cursor Cloud AgentsDashboard, Cloud Agents, Secrets, as a Runtime Secret
Telmian MCP serverURL only in .cursor/mcp.json; sign-in happens in the browser
Calls to the Telmian APIServer-side code only, never client components
  1. Get a free sandbox key

    Open Cursor's terminal in your project and run the command below. It writes a sandbox key (sk_test_) to your .env file. No card is needed, and sandbox SMS are simulated.

    npx telmian@1 init
  2. Keep the key out of chat and git

    Cursor ignores .env files by default, so Agent features and @-mentions cannot read the key. Terminal and MCP tools used by the Agent are not blocked by ignore files, so this is not a guarantee. Check that .env is in your .gitignore. Never paste the key into the chat or into client code.

  3. Optional: connect the Telmian MCP server

    Cursor supports remote MCP servers. Add this file as .cursor/mcp.json (one project) or ~/.cursor/mcp.json (all projects), then enable the server under Customize in the sidebar. If Cursor opens your browser, sign in to Telmian; the file holds no key, and real charged sends from the AI stay off unless you tick that at consent.

    {
      "mcpServers": {
        "telmian": { "url": "https://app.telmian.com/mcp" }
      }
    }
  4. Add a project rule

    A rule tells the Agent how to use Telmian every time. Save it as .cursor/rules/telmian.mdc, or put the same lines in AGENTS.md at the project root.

    ---
    description: Telmian SMS rules
    alwaysApply: true
    ---
    - Call Telmian (https://app.telmian.com/v1 or the telmian npm package) only from server-side code.
    - Read TELMIAN_API_KEY from the environment. Never put it in client code or mcp.json.
    - Use POST /v1/verify and POST /v1/verify/check for login codes. Do not generate codes yourself.
    - Send an Idempotency-Key on every POST that sends. Retry only with the same key.
    - In development use +393000000001 (code 000000) and +393000000002 (always fails).
  5. Write the server code

    Your project decides where server code runs: a Next.js route handler, an Express server or a Supabase Edge Function. Put one endpoint that sends the code and one that checks it there, never in the browser.

    // Server-side only. Never ship this to the browser.
    const TELMIAN_API_KEY = process.env.TELMIAN_API_KEY;
    
    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();
  6. Test with the sandbox numbers

    Send a code to +393000000001 and check it with 000000; you should get {"valid":true}. Then try +393000000002 to see how your app handles a failed send.

  7. Go live

    Top up by card from €5 in the panel at https://app.telmian.com, create an sk_live_ key there and set it as TELMIAN_API_KEY on the host that runs your app. Real verification codes also need an approved business name, set in the panel or with the MCP tool set_sender_profile. If you use Cursor Cloud Agents, store the key as a Runtime Secret, not as an Environment Variable.

Questions

Do I need my own phone or SIM, and what does it cost?

No phone or SIM of your own is needed. Telmian sends from its own European mobile numbers. It costs €0.05 per SMS segment to mobile numbers in 44 European countries, plus VAT, prepaid by card from €5, with no monthly fee. SMS refused by the network or not delivered are refunded automatically.

Can the Cursor Agent see my API key?

Cursor ignores .env files by default, so the Agent and @-mentions cannot read them. Cursor's docs also say terminal and MCP tools used by the Agent are not blocked by ignore files, so this protection is not guaranteed. Do not paste the key into chat.

Do I put my Telmian API key in mcp.json?

No. The Telmian MCP server uses browser sign-in, so .cursor/mcp.json only needs the URL. That also means you can commit the file to share the setup with your team.

My app uses Supabase Auth. Does this still work?

Yes. Telmian works as the Supabase Send SMS hook over HTTPS, and Supabase keeps creating and checking the codes. The MCP tool setup_supabase_sms returns the hook URL and secret. You set the hook in Supabase itself; Cursor only edits your code.

Where do delivery reports and replies arrive?

At a webhook endpoint in your own deployed backend, because Cursor does not host apps. Webhooks are signed, so check them with verifyWebhook from the telmian SDK before you trust them.

Updated