# 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 <hello@myapp.co.il>',
    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 <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:

- [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)
