# Partner SMS gateway

Server-to-server SMS via Meshkee → Gama (گاما). Use this when a **non-Meshkee** (or partner) backend needs to send SMS through the shared Meshkee account.

**Not for browser/storefront JavaScript.** Never put the API key in frontend code.

Hub: https://api.meshkee.com/docs/website  
Endpoint docs also in OpenAPI / Postman under **Partner SMS**.

---

## Endpoint

```http
POST https://api.meshkee.com/api/v1/public/sms/send
Content-Type: application/json
X-Api-Key: <partner-secret>
```

### Body

| Field | Required | Description |
|-------|----------|-------------|
| `domain` | yes | Allowlisted partner apex, e.g. `baloutpastry.com` (`www.` is stripped) |
| `to` | yes | Mobile: `09…`, `9…`, `+989…`, or `989…` |
| `message` | yes | Free text, max 700 characters |

### Example (Balout)

```bash
curl -sS -X POST 'https://api.meshkee.com/api/v1/public/sms/send' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <YOUR_PARTNER_KEY>' \
  -d '{
    "domain": "baloutpastry.com",
    "to": "09127004945",
    "message": "سفارش شما به شماره ی ۱۲۱۱۳۲۲ اماده می باشد."
  }'
```

### Success (200)

```json
{
  "success": true,
  "serverId": "1136923081051406337"
}
```

`serverId` is the Gama message id (delivery tracking).

### Errors

| HTTP | Meaning |
|------|---------|
| 400 | Invalid phone or empty/too-long message |
| 401 | Missing/invalid `X-Api-Key` or domain not allowlisted |
| 429 | Rate limit: **30**/partner/minute or **5**/destination/minute |
| 503 | SMS disabled, missing provider config, or Gama unreachable |

---

## Auth model

1. Meshkee configures `SMS_PARTNERS=domain:apiKey,...` on the API server.
2. Partner backend sends `X-Api-Key` + matching `domain` in the JSON body.
3. Key must match that domain (timing-safe compare). `www.baloutpastry.com` normalizes to `baloutpastry.com`.

First allowlisted partner: **baloutpastry.com**.

---

## Sender line (v1)

Uses the **service** shortcode only (`SendQuick`). Advertising / bulk / OTP pattern APIs are not exposed yet.

---

## Rules for partner backends

1. Call from your **server** only (Balout API → Meshkee API).
2. Keep the API key in server env / secrets — never in the website frontend.
3. Prefer short transactional messages (order ready, OTP-style text, etc.).
4. Respect rate limits; backoff on `429`.
5. Meshkee websites that already use customer auth OTP go through Meshkee’s own auth/SMS path — they do **not** need this partner endpoint.