# TurkeySMS

> SMS, OTP and bulk messaging API for Turkey. BTK-licensed SMS infrastructure, operating since 2016.

TurkeySMS provides a JSON/REST API for transactional SMS, one-time passwords (OTP), and bulk campaigns, with delivery webhooks and reporting. This file is a compact factual snapshot for automated agents. The authoritative contract is openapi.json.

## API basics

- Base URL: https://api.turkeysms.com.tr
- Version: V4
- Transport: HTTPS, JSON request and response bodies
- Method: every endpoint uses POST
- Auth: include the `api_key` field in the JSON body (no Authorization header); `Content-Type: application/json` is required
- Phone format: international without `+` (e.g. 905xxxxxxxxx)

## Endpoints

- POST /auth/check — validate an API key, return permissions and balance
- POST /sms/send — send a single SMS (supports scheduled delivery)
- POST /otp/send — send a standard OTP (auto-generated code)
- POST /otp/detailed — send a custom-template OTP (text must contain TS-CODE)
- POST /group/send — send the same text to many recipients
- POST /group/sendMixed — send personalized messages to many recipients
- POST /balance/ — query account balance
- POST /senderid/check — list approved SenderIDs
- POST /sms/status — query delivery status by sms_id
- POST /reports/basic — campaign summary report
- POST /reports/detailed — recipient-level report (paginated, 500/page)

## Delivery lifecycle

queued -> sent -> delivered
queued -> failed
sent -> failed
sent -> expired

## Response codes (most common)

- TS-1000 (200) — authentication check successful
- TS-1024 (200) — SMS dispatched successfully
- TS-1027 (403) — insufficient balance
- TS-1028 (403) — SenderID not active
- TS-1031 (401) — invalid API key
- TS-1033 (400) — invalid JSON body
- TS-1040 (200) — balance / SenderID query successful
- TS-1060 (403) — per-minute rate limit exceeded
- TS-1061 (403) — POST permission not enabled
- TS-1065 (403) — API key permissions insufficient

## Webhooks

Delivery events are pushed to a per-key webhook URL. Events: sms.sent, sms.delivered, sms.failed, otp.verified, key.test. Requests are signed with HMAC (header `X-TurkeySMS-Signature: <algo>=<hmac>`, plus `X-TurkeySMS-Timestamp`). Failed deliveries are retried with configurable backoff.

## Idempotency

The API includes duplicate-request protection designed to reduce accidental re-submission during client retries and network interruptions. A repeated identical send request made within a short window is detected and does not trigger a second send or charge.

## Documentation

- Developer documentation: https://turkeysms.com.tr/docs
- OpenAPI specification: https://turkeysms.com.tr/openapi.json
- SDKs: PHP and Node.js — see https://turkeysms.com.tr/docs

## Contact

- Support: https://turkeysms.com.tr/Support
- Terms: https://turkeysms.com.tr/terms-of-use