# Otipi: full reference > One API for login codes, SMS and email to recipients in Israel. Base URL: https://otipi.co.il/v1 Auth: `Authorization: Bearer sk_test_...` (test mode, nothing is delivered) or `sk_live_...`. Server side only; the API sends no CORS headers. ## Login codes POST /v1/otp/send { "to": "+972501234567", "app": "MyApp", "channel": "sms" | "whatsapp" | "email" | "auto", "language": "he" | "ar" | "ru" | "en", "length": 4-8, "ttl_minutes": 1-30 } -> 201 { id, status: "pending", to, channel, message_id, expires_at, test_code (test mode only) } POST /v1/otp/verify { "to": "+972501234567", "code": "482917" } -> { valid: true } or { valid: false, reason: "wrong_code" | "expired_or_missing" | "too_many_attempts" } Only "to" and "app" are required. When channel is "auto", Otipi tries WhatsApp first and automatically falls back to SMS on provider error. A code is valid for 5 minutes by default and can be tried 5 times. ## Ready integrations (Supabase Auth, Lovable, Cursor, Base44) - Supabase Auth (Send SMS Hook): in Auth -> Hooks -> Send SMS Hook, paste URL `https://otipi.co.il/v1/integrations/supabase-sms-hook?channel=auto` with `Authorization: Bearer sk_live_...` (or Standard Webhooks signature). Accepts `{ "user": { "phone": "+972501234567" }, "sms": { "otp": "123456" } }` and returns `200 {}`. - Lovable and Cursor: use the one-click system prompt below to wire phone OTP and transactional emails. - Base44: connect via OpenAPI 3.1 specification at `https://otipi.co.il/openapi.json` (`https://otipi.co.il/openapi.json`). ## Send a message POST /v1/messages { "channel": "sms" | "email" | "whatsapp", "to": "+972501234567" | "user@example.com", "from": optional, "subject": email only, "text": "...", "html": optional, "template": optional, "variables": {}, "language": "he" | "ar" | "ru" | "en" } Returns 202 with { id, channel, to, status: "queued", mode, segments, created_at }. Optional header: Idempotency-Key. With a live key, WhatsApp carries login codes only: use /v1/otp/send for them. ## Read GET /v1/messages/:id -> the message with its events GET /v1/messages?limit=20&channel=sms&status=delivered -> { data: [...], has_more } Statuses: queued, sent, delivered, opened (email), failed, bounced (email). ## Node.js client One file without dependencies: https://otipi.co.il/sdk/otipi.js import { Otipi } from './otipi.js'; const otipi = new Otipi(process.env.OTIPI_KEY); otipi.otp.send({ to, app }); otipi.otp.verify({ to, code }); otipi.send(message); otipi.messages.get(id); Otipi.verifyWebhook(rawBody, signatureHeader, secret) ## Built-in templates login-code (code, app, minutes), order-confirmed (name, order, app), receipt (name, amount, app). Each exists in he, ar, ru and en; "language" picks one, he by default. ## Webhooks Events: message.sent, message.delivered, message.opened, message.failed, message.bounced. Header Otipi-Signature: t=,v1=. ## Limits SMS and WhatsApp go to Israeli mobile numbers only. 600 requests a minute per key. 5 codes an hour per recipient. An SMS is at most 10 parts and 1,005 characters. ## Errors { "error": { "code": "...", "message": "..." } } with a fitting HTTP status. Common codes: unauthorized, invalid_recipient, missing_variables, domain_not_verified, identity_not_verified, live_unavailable, whatsapp_codes_only, rate_limited, too_many_codes, monthly_limit_reached. ## For an AI builder Paste this into the builder to connect the service: Add Otipi to this project. Otipi is an API for login codes, SMS and email to recipients in Israel. Rules: - Call Otipi from server code only (an API route, a server action or an edge function). The key is a secret: read it from the environment variable OTIPI_KEY and never send it to the browser. - Base URL: https://otipi.co.il/v1. Every request carries the header "Authorization: Bearer " and a JSON body. - A key that starts with sk_test_ delivers nothing and returns the code in "test_code". Use it while building. Phone login in two calls: 1. POST /v1/otp/send {"to": "+972501234567", "app": ""} -> 201 {"id", "status": "pending", "expires_at"} Optional: "channel": "sms" | "whatsapp" | "email" | "auto", "language": "he" | "ar" | "ru" | "en". 2. POST /v1/otp/verify {"to": "+972501234567", "code": ""} -> {"valid": true} or {"valid": false, "reason": "wrong_code" | "expired_or_missing" | "too_many_attempts"} Sign the person in only when "valid" is true. Supabase Auth (Send SMS Hook): - In Supabase Dashboard -> Auth -> Hooks -> Send SMS Hook, set URL to https://otipi.co.il/v1/integrations/supabase-sms-hook?channel=auto with Authorization: Bearer (or Standard Webhooks secret). Base44: - Connect using OpenAPI specification at https://otipi.co.il/openapi.json (https://otipi.co.il/openapi.json). Other messages: POST /v1/messages {"channel": "sms" | "email", "to": "...", "text": "..."} -> 202 {"id", "status": "queued"}. An email also needs "subject" and, with a live key, "from" on a verified domain. Phone numbers are Israeli mobiles written as +9725XXXXXXXX. An error comes as {"error": {"code", "message"}} with a fitting HTTP status: show the person a short message and log the code. Full reference: https://otipi.co.il/llms-full.txt OpenAPI: https://otipi.co.il/openapi.json --- # Documentation ยท Otipi One API for email, SMS and WhatsApp. Every request goes to `https://otipi.co.il/v1`, in JSON. ## Quick start Create a key in the dashboard and send one request: ```bash curl https://otipi.co.il/v1/messages \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "channel": "sms", "to": "+972501234567", "template": "login-code", "variables": { "code": "482917", "app": "MyApp", "minutes": 5 } }' ``` The answer comes right away, even before the message goes out: ```json { "id": "msg_7Qk2LxWb9RtY3nPd5sAe", "channel": "sms", "to": "+972501234567", "status": "queued", "mode": "test", "segments": 1, "created_at": "2026-11-10T08:15:02.000Z" } ``` ## Keys Send the key with every request, in the `Authorization: Bearer` header. It's a secret: use it only on your server, never in a browser or a mobile app. A key that starts with `sk_test_` works in test mode and doesn't send anything to anyone. A key that starts with `sk_live_` sends for real. ## Node.js library One file, no dependencies, for Node 18 and newer. [Download otipi.js](https://otipi.co.il/sdk/otipi.js), put it in your project and import it: ```js import { Otipi } from './otipi.js'; const otipi = new Otipi(process.env.OTIPI_KEY); // A login code: send it, then check what the person typed await otipi.otp.send({ to: '+972501234567', app: 'MyApp' }); const { valid } = await otipi.otp.verify({ to: '+972501234567', code: '482917' }); // A plain message const message = await otipi.send({ channel: 'sms', to: '+972501234567', text: 'Your order is on its way.', }); // What happened to the message const { status } = await otipi.messages.get(message.id); ``` If the API returns an error, the library throws an `OtipiError` with `code` and `status`. Without the library everything works the same with `fetch` or `curl`: see the examples below. ## Sending a message `POST /v1/messages` | Field | What to put | | --- | --- | | `channel` | email, sms or whatsapp. Required. | | `to` | An email address or an Israeli mobile number, like +972501234567. Required. | | `from` | For email: an address on a verified domain. For SMS: an approved sender name. Leave it out and we'll use your first approved name. | | `subject` | The email subject. Required for email, unless you use a template. | | `text` | The message text. | | `html` | An HTML version of the email. If you don't send one, we'll build it from the text, right to left where needed. | | `template` | A template name, instead of text. | | `variables` | The values to fill into the template. | | `language` | he, ar, ru or en, for the ready-made templates. If you leave it out, it's he. | An example in Node.js: ```js const response = await fetch('https://otipi.co.il/v1/messages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.OTIPI_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ channel: 'email', from: 'MyApp ', to: 'dana@example.com', subject: 'Welcome', text: 'Hi Dana, your account is ready.', }), }); const message = await response.json(); ``` So a repeated request doesn't send twice, add an `Idempotency-Key` header with a value of your own. A second request with the same value just returns the first message. ## What happened to a message `GET /v1/messages/:id` returns the message and everything that happened to it. `GET /v1/messages` returns the latest ones; you can narrow them down with `limit`, `channel` and `status`. | Status | What it means | | --- | --- | | `queued` | We've got it and will send it shortly. | | `sent` | We handed it to the carrier. | | `delivered` | It reached the recipient. | | `opened` | The email was opened. | | `failed` | We couldn't send it. The reason is in the error field. | | `bounced` | The email came back: the address doesn't exist or didn't accept it. | ## Login codes Just two requests: one sends a code, the other checks what the person typed. We create the code, store it and count the attempts. ```bash # 1. Send a code curl https://otipi.co.il/v1/otp/send \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "to": "+972501234567", "app": "MyApp" }' # 2. Check what the person typed curl https://otipi.co.il/v1/otp/verify \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{ "to": "+972501234567", "code": "482917" }' ``` In `/v1/otp/send` you can add `channel` (sms, whatsapp or email), `language` (he, ar, ru or en), `length` (4 to 8 digits) and `ttl_minutes` (how many minutes the code works, up to 30). The answer looks like `{ "id": "otp_...", "status": "pending", ... }`. `/v1/otp/verify` answers `{ "valid": true }` or `{ "valid": false, "reason": "wrong_code" }`. A code works for 5 minutes and can be typed in 5 times. One recipient gets at most 5 codes an hour. On WhatsApp the wording is always the same: a 6-digit code, good for 5 minutes, in Hebrew or English. Other WhatsApp messages can't be sent yet. ## Templates Every account has three ready-made templates, in Hebrew, Arabic, Russian and English: | Name | Values | | --- | --- | | `login-code` | code, app, minutes | | `order-confirmed` | name, order, app | | `receipt` | name, amount, app | You create your own templates in the dashboard. A spot for a value looks like this: `{{name}}`. ## Webhooks Add an address on your server in the dashboard, and on every status change we'll send it a POST request: `message.sent`, `message.delivered`, `message.opened`, `message.failed`, `message.bounced`. ```json { "id": "evt_Hc91VdKq2mZx8LpT4rNb", "type": "message.delivered", "created_at": "2026-11-10T08:15:04.000Z", "data": { "id": "msg_7Qk2LxWb9RtY3nPd5sAe", "channel": "sms", "to": "+972501234567", "status": "delivered" } } ``` Answer with a 2xx code within 8 seconds. If you don't, we'll try again after 10 seconds and after a minute. Every request has an `Otipi-Signature` header. With the library, checking it takes one line: ```js // body is the request body exactly as it arrived, before JSON.parse if (!Otipi.verifyWebhook(body, request.headers['otipi-signature'], secret)) { return response.writeHead(400).end(); } ``` And without the library: ```js import crypto from 'node:crypto'; // body is the request body exactly as it arrived, before JSON.parse function isFromOtipi(body, header, secret) { const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('='))); if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex'); return v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected)); } ``` ## Test mode With a test key nothing goes to anyone, but in the log the messages look real. What happens to them depends on the recipient: | Recipient | What happens | | --- | --- | | `+972500000000` | The SMS won't be sent. | | `bounce@example.com` | The email bounces. Works for any address that starts with bounce. | | `open@example.com` | The email is delivered, then marked as opened. Works for any address that starts with open. | | Anyone else | The message is delivered. | In test mode `/v1/otp/send` also returns the code itself, in the `test_code` field. You can send up to 500 test messages a day. ## Errors and limits When something goes wrong, you get a fitting HTTP code and a body like this: `{ "error": { "code": "invalid_recipient", "message": "..." } }`. | Code | What happened | | --- | --- | | `unauthorized` | No key, a wrong key, or a deleted one. | | `invalid_recipient` | The recipient doesn't fit the channel. For now SMS and WhatsApp go to Israeli numbers only. | | `missing_variables` | Some values for the template are missing. | | `domain_not_verified` | The sender address is on a domain that isn't verified yet. | | `identity_not_verified` | To send real SMS, you need a one-time ID check. | | `live_unavailable` | Real sending isn't open on this channel yet. | | `whatsapp_codes_only` | With a live key, WhatsApp carries login codes only. Use `/v1/otp/send`. | | `rate_limited` | More than 600 requests a minute from one key. | | `monthly_limit_reached` | Your plan's emails for this month have run out. | ## For AI tools Building with Lovable, Cursor, Base44, Supabase or another AI tool? Here are ready-made instructions and text you can just copy. ### Supabase Auth (Send SMS Hook) In Supabase, open `Auth -> Hooks -> Send SMS Hook`, choose HTTP Request, paste `https://otipi.co.il/v1/integrations/supabase-sms-hook?channel=auto` and add the `Authorization: Bearer sk_live_...` header (or a Standard Webhooks secret). Otipi will send the login code on WhatsApp, and by SMS if that doesn't work. ### Lovable and Cursor Copy this text into Lovable or Cursor: it explains how to set up phone sign-in and email sending through Otipi. ```text Add Otipi to this project. Otipi is an API for login codes, SMS and email to recipients in Israel. Rules: - Call Otipi from server code only (an API route, a server action or an edge function). The key is a secret: read it from the environment variable OTIPI_KEY and never send it to the browser. - Base URL: https://otipi.co.il/v1. Every request carries the header "Authorization: Bearer " and a JSON body. - A key that starts with sk_test_ delivers nothing and returns the code in "test_code". Use it while building. Phone login in two calls: 1. POST /v1/otp/send {"to": "+972501234567", "app": ""} -> 201 {"id", "status": "pending", "expires_at"} Optional: "channel": "sms" | "whatsapp" | "email" | "auto", "language": "he" | "ar" | "ru" | "en". 2. POST /v1/otp/verify {"to": "+972501234567", "code": ""} -> {"valid": true} or {"valid": false, "reason": "wrong_code" | "expired_or_missing" | "too_many_attempts"} Sign the person in only when "valid" is true. Supabase Auth (Send SMS Hook): - In Supabase Dashboard -> Auth -> Hooks -> Send SMS Hook, set URL to https://otipi.co.il/v1/integrations/supabase-sms-hook?channel=auto with Authorization: Bearer (or Standard Webhooks secret). Base44: - Connect using OpenAPI specification at https://otipi.co.il/openapi.json (https://otipi.co.il/openapi.json). Other messages: POST /v1/messages {"channel": "sms" | "email", "to": "...", "text": "..."} -> 202 {"id", "status": "queued"}. An email also needs "subject" and, with a live key, "from" on a verified domain. Phone numbers are Israeli mobiles written as +9725XXXXXXXX. An error comes as {"error": {"code", "message"}} with a fitting HTTP status: show the person a short message and log the code. Full reference: https://otipi.co.il/llms-full.txt OpenAPI: https://otipi.co.il/openapi.json ``` ### Base44 In Base44, add an external API from an OpenAPI description: address `https://otipi.co.il/openapi.json`, key `Bearer sk_live_...`. The same docs as plain text, so AI tools can read them on their own: - [llms.txt](https://otipi.co.il/llms.txt) - [llms-full.txt](https://otipi.co.il/llms-full.txt) - [openapi.json](https://otipi.co.il/openapi.json) - [docs.md](https://otipi.co.il/en/docs.md)