← Tutte le guide

Inviare SMS da Cursor: codici OTP e messaggi nella tua app

Cursor è un editor di codice: l'SMS parte dal codice server della tua app, non da Cursor. Metti una chiave Telmian nel file .env del progetto, chiama POST https://app.telmian.com/v1/verify da una route server e controlla il codice con /v1/verify/check. Se vuoi, collega a Cursor il server MCP di Telmian per farti aiutare mentre sviluppi.

Dove va ogni pezzo in un progetto Cursor
CosaDove
Chiave sandbox (sk_test_)Il file .env del progetto, ignorato da Cursor per impostazione predefinita
Chiave live (sk_live_)Le variabili d'ambiente dell'host che fa girare la tua app
Chiave per i Cloud Agents di CursorDashboard, Cloud Agents, Secrets, come Runtime Secret
Server MCP di TelmianSolo l'URL in .cursor/mcp.json; l'accesso avviene nel browser
Chiamate all'API TelmianSolo codice lato server, mai componenti client
  1. Prendi una chiave sandbox gratuita

    Apri il terminale di Cursor nel tuo progetto e lancia il comando qui sotto. Scrive una chiave sandbox (sk_test_) nel file .env. Non serve la carta e gli SMS in sandbox sono simulati.

    npx telmian@1 init
  2. Tieni la chiave fuori dalla chat e da git

    Cursor ignora i file .env per impostazione predefinita, quindi le funzioni dell'Agent e le @-menzioni non leggono la chiave. Il terminale e gli strumenti MCP usati dall'Agent però non sono bloccati dai file di esclusione, quindi non è una garanzia. Controlla che .env sia nel tuo .gitignore. Non incollare mai la chiave in chat o nel codice client.

  3. Facoltativo: collega il server MCP di Telmian

    Cursor supporta i server MCP remoti. Aggiungi questo file come .cursor/mcp.json (un progetto) o ~/.cursor/mcp.json (tutti i progetti), poi attiva il server da Customize nella barra laterale. Se Cursor apre il browser, accedi a Telmian; il file non contiene chiavi, e gli invii reali a pagamento dall'AI restano spenti finché non li spunti al consenso.

    {
      "mcpServers": {
        "telmian": { "url": "https://app.telmian.com/mcp" }
      }
    }
  4. Aggiungi una regola di progetto

    Una regola dice all'Agent come usare Telmian ogni volta. Salvala come .cursor/rules/telmian.mdc, oppure metti le stesse righe in AGENTS.md nella cartella principale del progetto.

    ---
    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. Scrivi il codice server

    È il tuo progetto a decidere dove gira il codice server: una route handler di Next.js, un server Express o una Supabase Edge Function. Lì metti un endpoint che invia il codice e uno che lo controlla, mai nel 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. Prova con i numeri della sandbox

    Invia un codice a +393000000001 e controllalo con 000000: devi ricevere {"valid":true}. Poi prova +393000000002 per vedere come la tua app gestisce un invio fallito.

  7. Passa al live

    Ricarica con carta da 5 € nel pannello su https://app.telmian.com, crea lì una chiave sk_live_ e impostala come TELMIAN_API_KEY sull'host che fa girare la tua app. Per i codici di verifica reali serve anche un nome aziendale approvato, da impostare nel pannello o con lo strumento MCP set_sender_profile. Se usi i Cloud Agents di Cursor, salva la chiave come Runtime Secret, non come Environment Variable.

Domande

Mi serve un telefono o una SIM mia, e quanto costa?

No, non ti serve un telefono né una SIM. Telmian invia dai propri numeri mobili europei. Costa 0,05 € per segmento SMS verso numeri mobili in 44 Paesi europei, più IVA, con ricarica prepagata da 5 € e nessun canone mensile. Gli SMS rifiutati dalla rete o non consegnati vengono rimborsati in automatico.

L'Agent di Cursor può vedere la mia chiave API?

Cursor ignora i file .env per impostazione predefinita, quindi l'Agent e le @-menzioni non li leggono. La documentazione di Cursor dice però che il terminale e gli strumenti MCP usati dall'Agent non sono bloccati dai file di esclusione, quindi la protezione non è garantita. Non incollare la chiave in chat.

Devo mettere la chiave API di Telmian in mcp.json?

No. Il server MCP di Telmian usa l'accesso dal browser, quindi in .cursor/mcp.json basta l'URL. Per questo puoi anche fare commit del file e condividere la configurazione con il tuo team.

La mia app usa Supabase Auth. Funziona lo stesso?

Sì. Telmian funziona come Send SMS hook di Supabase via HTTPS, e Supabase continua a creare e controllare i codici. Lo strumento MCP setup_supabase_sms ti restituisce URL e secret dell'hook. L'hook lo imposti in Supabase; Cursor modifica solo il tuo codice.

Dove arrivano le conferme di consegna e le risposte?

A un endpoint webhook nel tuo backend pubblicato, perché Cursor non ospita app. I webhook sono firmati: controllali con verifyWebhook dell'SDK telmian prima di fidarti.

Aggiornata il