Documentation
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:
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:
{
"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, put it in your project and import it:
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:
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 <[email protected]>',
to: '[email protected]',
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.
# 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.
{
"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:
// 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:
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. |
| [email protected] | The email bounces. Works for any address that starts with bounce. |
| [email protected] | 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.
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 <key>" 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": "<the name of this 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": "<what the person typed>"} -> {"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 <key> (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: