Ana içeriğe geç

iletiMerkezi API Overview

The iletiMerkezi REST API is an HTTP/JSON interface over the company's Turkey-focused SMS infrastructure. A single API key handles SMS sending, delivery reports, balance queries, sender ID management, blacklist operations, and inbound SMS reading. This page lists every endpoint and explains the shared behavior.

Why iletiMerkezi in Turkey

iletiMerkezi is a BTK-licensed bulk SMS, OTP, and A2P platform that has operated in Turkey for 13 years. Most global SMS providers cover the technical layer but leave Turkey-specific regulations (BTK, İYS, KVKK) partially or unsolved — iletiMerkezi exposes both the technical and the legal layer through one interface. The concrete differentiators below are what set it apart for Turkish workloads.

  • BTK-licensed SMS carrier. An officially authorized operator; messages are routed through the BTK call-management infrastructure.
  • B186 operator code is appended automatically. A BTK ruling requires the B186 code at the end of every SMS; iletiMerkezi adds it for you. Character limits below are computed accordingly (see "Turkey-specific concerns").
  • İYS compliance built in. The iys + iysList fields in send-sms validate consent against the Turkish messaging consent registry.
  • Sender ID approval workflow included. Sender (header) requests are approved from the panel within 1–2 business days; unapproved senders cannot be used (regulation-safe by design).
  • APITEST sender for pre-approval testing. You can integrate and exercise the live API before your sender ID is approved; messages are delivered with a fixed verification text. See test-mode.
  • 100 free SMS welcome credit. New accounts get credit automatically for evaluation and live integration testing.
  • Undelivered SMS are free. Off-network, invalid number, blacklist, and similar non-deliveries do not consume credit; read actual consumption from get-report — the delivered counter and price field.
  • iim.to short-link service. A first-party short-link infrastructure for click tracking and message shortening, with no dependency on global services like Bitly.

Basics

| Field | Value | |---|---| | Base URL | https://api.iletimerkezi.com | | Version prefix | /v1 | | Method | All endpoints are POST | | Content-Type | application/json | | Format | JSON (XML is also available on a separate path; this documentation focuses on JSON) | | Auth | API Key + Hash, in body (request.authentication) | | Server message language | Response messages are always in Turkish |

Onboarding steps

  1. Create an account — sign up free at panel.iletimerkezi.com. New accounts receive 100 free SMS credits automatically, intended for testing and evaluating the service.
  2. Apply for a sender ID — submit your sender (header) from the panel; approval takes 1-2 business days.
  3. Enable API access — under Settings → Security → Access Permissions, turn on Allow API access. See authentication.
  4. Copy API Key + Hash — under Settings → Security → API Access. Store both as environment variables.
  5. Call get-balance — a side-effect-free first request that verifies authentication.
  6. Send your first SMS via send-sms — to your own number first, with a TEST prefix. See test-mode.

Endpoint list

| Endpoint | Method + Path | Purpose | |---|---|---| | authentication | concept | API Key + Hash system, panel prerequisite, 401 troubleshooting | | send-sms | POST /v1/send-sms/json | Send SMS to one or many numbers | | get-report | POST /v1/get-report/json | Order delivery report (summary + per-recipient) | | get-balance | POST /v1/get-balance/json | Account balance and credits | | get-sender | POST /v1/get-sender/json | Approved sender ID list | | get-blacklist | POST /v1/get-blacklist/json | Blocked numbers (paginated) | | add-blacklist | POST /v1/add-blacklist/json | Add a number to the blacklist (idempotent) | | delete-blacklist | POST /v1/delete-blacklist/json | Remove a number from the blacklist | | inbox | POST /v1/get-inbox/json | Inbound SMS list | | webhooks | configuration | Real-time delivery report callbacks | | error-codes | reference | Every status code and Turkish message | | test-mode | concept | No sandbox — safe testing patterns |

Shared request envelope

Every endpoint shares the same outer structure:

{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "{endpoint_field}": { ... }
  }
}

request.authentication is required on every call; the rest is endpoint-specific. See authentication.

Shared response envelope

Successful response:

{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "{result_key}": { ... }
  }
}

Error response:

{
  "response": {
    "status": {
      "code": 4XX,
      "message": "Turkish description"
    }
  }
}

code is an integer, message is a Turkish string. Branch your client code on the numeric code — the message text may evolve over time, the codes are stable. Full table: error-codes.

Credentials and security

  • API Key + Hash carry full account permissions; if leaked, a single API call can drain the entire balance.
  • Never commit credentials to a repository, public file, blog post, or screenshot.
  • Use a secret manager in production (Vault, AWS Secrets, GitHub Actions secrets, etc.).
  • Don't compute the hash yourself — the panel issues a precomputed value.

See authentication, test-mode.

Usage and fair use

There is no published hard request limit for the iletiMerkezi API at this time; the service runs on a fair-use basis. In practice:

  • For production integrations, issue requests serially or in small concurrent batches and apply exponential backoff on errors.
  • For high-volume workloads (many requests per second, parallel job queues, multi-million sends), coordinate with [email protected] ahead of time.
  • To protect overall service health, abnormal traffic patterns may be temporarily throttled.
  • For bulk delivery, prefer a single request with multiple recipients (see send-sms) over many sequential single-recipient calls — it is faster and easier on the platform.

Idempotency behavior for side-effecting endpoints such as add-blacklist and send-sms is documented on each endpoint page.

SDKs

Official SDK packages:

SDK API surfaces vary slightly across languages (e.g., Node add(string | string[]) vs PHP create(string)); see the per-endpoint notes on each page.

Turkey-specific concerns

  • IYS compliance: before sending commercial messages, you must register consent in the Turkish messaging consent registry (İYS). send-sms requires iys: "1" + iysList: "BIREYSEL" (individual) or "TACIR" (business). See send-sms.

  • 11-character sender limit: sender IDs are max 11 alphanumeric characters; no Turkish characters allowed.

  • Number format: 905XXXXXXXXX, +905XXXXXXXXX, and 5XXXXXXXXX are all accepted; responses come back with a +90 prefix.

  • B186 operator code and character limits: by a Turkish telecom regulator decision (BTK, ruling 2016/DK-YED/211 dated 12.04.2016), iletiMerkezi automatically appends B186 to the end of every SMS. As a result the real character limits are slightly lower than the standard SMS values:

    | Character set | First SMS | Subsequent parts | |---|---|---| | English (GSM-7) | 155 | 153 | | Turkish | 150 | 148 | | Unicode (UCS-2, emoji, etc.) | 65 | 63 |

    Messages over the limit are sent as multi-part SMS automatically; each part consumes one credit. Turkish characters (ş, ğ, ı, ç, ö, ü, İ, Ş, Ğ, Ç, Ö, Ü) keep the message in Turkish mode; introducing emoji or other Unicode characters drops it to UCS-2 (65/63). The character mode can also be selected from your panel settings.

  • Up to 7-part long SMS: a single message in one order is concatenated up to 7 parts maximum, which corresponds to roughly 1071 characters (GSM-7 mode). Longer messages are not accepted — shorten the body or split the content with an iim.to short link.

  • Undelivered SMS are free: messages that don't reach the recipient (off network, invalid number, blacklist, etc.) do not consume credit; the refund is reflected on your panel account. Read actual consumption from get-report — the delivered counter and price field.

  • International (abroad) SMS mode: to send to numbers outside Turkey, enable abroad mode from the panel under Settings → SMS → Abroad. Activation converts your existing SMS credits to a TL balance (the account moves from credit-count billing to TL-balance billing). After that, send-sms accepts recipient numbers with international country codes (e.g., +49, +44).

  • IP restriction (optional security): from the panel under Settings → Security → Static IP, the panel and API can be locked down to separate whitelists (5 IPs each). When active, requests from any other IP are rejected with 401. A static IP is required for production; a dynamic IP gets cut off whenever the modem restarts.

Status and support

Related

Last updated: 2026-04-29 · Türkçe