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

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

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; message text may evolve over time, but 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 limits

The send-sms endpoint has two distinct limits:

• Transactional sending: up to 100 SMS per second per account. Typical use: OTP, login codes, order/delivery notifications, appointment reminders, per-user triggered, single-recipient messages.
• Bulk sending: up to 50,000 recipients in a single request (order.message.receipents.number array). Typical use: campaigns, broadcasts, mass alerts. One order is tracked under one orderId.

Practical rules:

• For recipient lists over 50,000, chunk client-side at chunkSize=50000 and issue sequential send-sms calls; each call returns its own orderId.
• For sustained throughput above 100 transactional SMS per second, plan ahead with [email protected] so dedicated capacity can be provisioned.
• Use exponential backoff in production error paths; abnormal traffic may be temporarily throttled to protect overall service health.
• For bulk delivery, prefer a single request with multiple recipients over many sequential single-recipient calls. It is faster and easier on the platform.

Other endpoints (reports, balance, blacklist, İYS check) have no published hard request limit and run on a fair-use basis. Idempotency behavior for side-effecting endpoints such as add-blacklist and send-sms is documented on each endpoint page.

SDKs

Official SDKs published to package registries:

• Node.js / TypeScript: npm @iletimerkezi/iletimerkezi-node (npm, GitHub)
• PHP: Packagist iletimerkezi/iletimerkezi-php (Packagist, GitHub)

Source code for other languages (Python, Go, Java, C#, Ruby, Laravel) is available on GitHub but not yet published to package registries, call the REST API directly or contact [email protected] for help.

For LLM-based development workflows: the MCP server (@iletimerkezi/mcp-server) lets Claude Code, Cursor, Gemini CLI and similar clients drive the 11 SMS tools from a single conversation. See /en/docs/mcp.

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.

  The character mode is configured at the account level from the panel. The default mode is English (GSM-7); to send Turkish characters or Unicode (emoji, other alphabets) you must first enable the corresponding Universal Language Support mode in the panel: panel.iletimerkezi.com/settings/sms/encoding. Without this setting, Turkish or Unicode characters are converted (e.g. ş > s, emoji stripped). Once enabled, the message body is placed automatically into the matching mode: Turkish-only characters > Turkish mode (150/148), emoji or other Unicode > UCS-2 (65/63).

• 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

• API status: production status is announced from the iletiMerkezi panel.
• Spotted a doc/API mismatch? Open an issue at iletimerkezi/apidocs-website. The live API is the ground truth.
• Extra support: [email protected].

Related

• Authentication
• Send SMS (send-sms)
• Testing and development (test-mode)
• Error code table (error-codes)

Last updated: 2026-05-05 · Türkçe