---
title: "Inbox API (get-inbox)"
description: "List inbound SMS messages received on your account. Date, sender, content, and your account number in one response."
slug: /en/docs/api/inbox
locale: en
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/get-inbox/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [send-sms, authentication, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/inbox
  en: https://www.iletimerkezi.com/en/docs/api/inbox
---

# Inbox API (get-inbox)

The `get-inbox` endpoint returns the SMS messages your iletiMerkezi account has received. Inbound traffic from external senders to your account numbers — most often subscription opt-out keywords (`RET`), customer replies, and short-code messages — surfaces here. The call has no side effects and consumes no credits.

## Typical use cases

iletiMerkezi offers a **4-digit short-code service** to receive messages from customers. Common flows:

- **Automatic opt-out:** keywords like "ABC RET, send to 7889". When a customer texts "RET", the panel auto-adds them to your blacklist. The raw message is also available via `get-inbox` for audit or CRM sync.
- **Surveys / response collection:** keyword-driven flows ("ABC SURVEY A") that route customer replies into your application.
- **Reservation / info requests:** customer-initiated self-service flows.
- **iim.to short-link integration:** clicking a shortened opt-out link appended to outbound messages auto-adds the user to your blacklist; this flow is configured in the panel and requires no additional API calls.

The short-code service is provisioned per customer needs; signup and activation happen at `panel.iletimerkezi.com`.

## Prerequisite: enable API access in the panel

> Before calling this endpoint, the **Allow API access** toggle must be on in your iletiMerkezi panel.
>
> Location: `panel.iletimerkezi.com` → **Settings → Security → Access Permissions**
>
> If it is off, every request returns `401 — Üyelik bilgileri hatalı` ("Authentication failed"). See [authentication](./authentication.md).

## Endpoint

| Field | Value |
|---|---|
| Method | `POST` |
| URL | `https://api.iletimerkezi.com/v1/get-inbox/json` |
| Content-Type | `application/json` |
| Auth | API Key + Hash (`request.authentication`) |

## Request

### Schema

```
request
└─ authentication
   ├─ key (string, required)
   └─ hash (string, required)
```

`get-inbox` takes no extra fields beyond the auth block.

### Full example

```json
{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    }
  }
}
```

## Response

### Success (200)

```json
{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "orders": {
      "totalRows": "5",
      "order": [
        {
          "id": "5",
          "date": "2026-04-09 11:18:44",
          "sender": "7889",
          "number": "+905354104818",
          "text": "ILT AHKTEST RET"
        }
      ]
    }
  }
}
```

`İşlem başarılı` means "Request successful" in Turkish.

**Fields:**

- `response.orders.totalRows` (string): total inbound message count for the account.
- `response.orders.order[]` (array): the message list.
  - `id` (string): unique inbound message ID.
  - `date` (string): receive timestamp, format `YYYY-MM-DD HH:MM:SS`.
  - `sender` (string): the source — a mobile number or a carrier short code.
  - `number` (string): your receiving account number with `+90` prefix.
  - `text` (string): message body.

> This endpoint is not in the legacy apidocs-website spec; we treat the live API as ground truth (drift: [`apidocs-website#4`](https://github.com/iletimerkezi/apidocs-website/issues/4)). Response shape verified by live testing on 2026-04-29.

### Error responses

#### 401 — Üyelik bilgileri hatalı ("Authentication failed")

See [authentication](./authentication.md).

#### Other error codes

For `400, 404`: see [error-codes](./error-codes.md).

## Code samples

### cURL

```bash
curl -X POST 'https://api.iletimerkezi.com/v1/get-inbox/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      }
    }
  }'
```

## Common pitfalls

- **`totalRows` is a string, not an integer.** The wire returns `"totalRows": "5"`; cast with `parseInt` / `Number` before doing arithmetic.
- **`sender` is not always a phone number.** Carrier short codes (e.g. `7889`) and alphanumeric senders are also possible; keep your format check liberal.
- **`text` may be carrier-prefixed.** Opt-out keywords like `RET` can arrive with operator-applied prefixes (e.g., `ILT AHKTEST RET`). Trim and lowercase before matching keywords.
- **Pagination is undocumented.** If `totalRows` exceeds 1000, the client may not receive the full list in one call; whether `page` / `rowCount` parameters are accepted should be probed before depending on it in production.
- **`get-inbox` consumes no credits.** Polling is safe; if a webhook is configured, prefer it to save bandwidth.

## Related

- [Authentication](./authentication.md)
- [Send SMS (send-sms)](./send-sms.md)
- [Webhook (webhooks)](./webhooks.md)
- [Error code table](./error-codes.md)