Otipi

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

FieldWhat to put
channelemail, sms or whatsapp. Required.
toAn email address or an Israeli mobile number, like +972501234567. Required.
fromFor email: an address on a verified domain. For SMS: an approved sender name. Leave it out and we'll use your first approved name.
subjectThe email subject. Required for email, unless you use a template.
textThe message text.
htmlAn HTML version of the email. If you don't send one, we'll build it from the text, right to left where needed.
templateA template name, instead of text.
variablesThe values to fill into the template.
languagehe, 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.

StatusWhat it means
queuedWe've got it and will send it shortly.
sentWe handed it to the carrier.
deliveredIt reached the recipient.
openedThe email was opened.
failedWe couldn't send it. The reason is in the error field.
bouncedThe 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:

NameValues
login-codecode, app, minutes
order-confirmedname, order, app
receiptname, 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:

RecipientWhat happens
+972500000000The 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 elseThe 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": "..." } }.

CodeWhat happened
unauthorizedNo key, a wrong key, or a deleted one.
invalid_recipientThe recipient doesn't fit the channel. For now SMS and WhatsApp go to Israeli numbers only.
missing_variablesSome values for the template are missing.
domain_not_verifiedThe sender address is on a domain that isn't verified yet.
identity_not_verifiedTo send real SMS, you need a one-time ID check.
live_unavailableReal sending isn't open on this channel yet.
whatsapp_codes_onlyWith a live key, WhatsApp carries login codes only. Use /v1/otp/send.
rate_limitedMore than 600 requests a minute from one key.
monthly_limit_reachedYour 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: