JSON Post API

To retrieve the list of messages sent to your short code in JSON format using the HTTP POST method, follow the instructions below.

A shared short code (7889) is used so that you can offer your recipients an opt-out channel. The recipient sends a message such as EMARKA RET to this number. In that message, EMARKA is your keyword and identifies which customer the message belongs to; RET is the command and determines what will be done. You define your commands in your iletiMerkezi panel.

If no command is defined, or if the word written by the recipient is not one of your defined commands, the opt-out scenario runs by default: the number is added to your blocked number list and a confirmation SMS is sent to the recipient. If you define a word as "record only" (RECORD_ONLY) in the panel, no opt-out is performed for that word and the message is only recorded.

The keyword does not have to be at the beginning of the message; it is enough for it to appear anywhere in the message. Every message received by the short code is billed to your account as 0.80 TRY, regardless of the command. This endpoint lets you pull the messages received by the short code into your own system.

Request URL

POSThttps://api.iletimerkezi.com/v1/get-inbox/json

Warning

The format suffix in the URL must match the format of the body you send. If you send a JSON body, you must use the /json suffix at the end of the URL. Without this suffix the server tries to parse the body as XML, fails, and rejects the request with 401.

Request Body

{
  "request": {
    "authentication": {
      "key": "",
      "hash": ""
    },
    "inbox": {
      "page": "",
      "rowCount": "",
      "filter": {
        "start": "",
        "end": "",
        "gsm": ""
      }
    }
  }
}

Definitions

The request sent to the server must be wrapped with the request tag. The definitions of its child tags are as follows:

authentication

Contains information about the transaction status. The values returned with this tag can also be obtained by looking at the header information of the HTTP response. This tag is returned as standard in every request made. Its subtags are as follows

key: After logging into your iletimerkezi.com panel, the API Key that you can create from the settings section should be written in this field. It is mandatory to send it when making a request.
hash: After logging into your iletimerkezi.com panel, the hash created using the API Key and Secret Key, which you can create from the settings section, should be written in this field. It is mandatory to send it when making a request.

inbox

Contains the pagination and filter parameters required for the inbox message list.

page: Indicates the result page. It is not required. Its default value is 1. It must be at least 1.
rowCount: Indicates the number of messages per result page. It is not required. Its default value is 30. It must be between 1 and 1000; if you send a greater value it is capped at 1000. If there are more records, a new request must be made by increasing the value of the page tag.
filter: Used to filter the results. It is not required.
- start: Indicates the start date of the messages to be listed. It must be in Y-m-d H:i:s format (2026-08-01 00:00:00). It must be sent together with the end tag.
- end: Indicates the end date of the messages to be listed. It must be in Y-m-d H:i:s format (2026-08-17 23:59:59). It must be sent together with the start tag and cannot be earlier than start.
- gsm: Filters the results by a single sender number. It is not required. It can be sent in a free format (05354101234, +905354101234).

Note

The start and end tags must be sent together. If only one of them is sent, the request is rejected with the 458 error. If neither is sent, no date filter is applied.

Server Response

{
  "response": {
    "status": {
      "code": "",
      "message": ""
    },
    "inbox": {
      "count": "",
      "messages": [
        {
          "id": "",
          "shortCode": "",
          "from": "",
          "keyword": "",
          "command": "",
          "action": "",
          "message": "",
          "price": "",
          "receivedAt": ""
        }
      ]
    }
  }
}

Definitions

The response returned from the server is always wrapped with the response tag. The definitions of its child tags are as follows:

status

code: It is a numeric value indicating the process status.
message: Contains information message about the process status.

inbox

Represents the list of messages received by your short code. Its child tags are as follows.

count: Indicates the total number of records matching your filter. It is not the number of records on the page you queried.

messages: The list containing the received message records. It contains as many items as there are messages on the queried page.

messages

id: The unique value that identifies the message record.
shortCode: The short code the message was sent to (7889).
from: The mobile phone number of the recipient who sent the message. It is returned in E.164 format (+905354101234).
keyword: The keyword matched in the message (for example EMARKA).
command: The command matched in the message (for example BILGI). If no command matched, it is returned as null. Since it is null and not an empty string (""), your client must perform a null check when reading this field.

action: Indicates the scenario that was executed for the message. Its possible values are as follows:

Value	Description
UNSUBSCRIBE	The opt-out scenario was executed. The number was added to your blocked number list and a confirmation SMS was sent to the recipient.
RECORD_ONLY	Only the record scenario was executed. The message was recorded and no opt-out was performed.

message: The full text of the message sent by the recipient.
price: The charge deducted from your account for this message. It is returned as a decimal number (0.8). If your balance is insufficient, it is returned as 0.
receivedAt: The date and time the message was received. It is returned in Y-m-d H:i:s format (2026-08-16 20:20:20).

Note

The command and action fields are returned empty for old messages recorded before this feature went live.

Error Codes

The following table lists the error codes that the API can return.

Error Code	Message	Description
400	İstek çözümlenemedi	POST ettiğiniz JSON'in yapısındaki hatadan kaynaklanır. Bu hatalar genellikle, yanlış yazılan JSON etiketi, düzgün kapatılmayan XML etiketi veya CDATA kullanılmadan JSON'in yapısını bozabilecek bir karakterin kullanımından kaynaklanır.
401	Üyelik bilgileri hatalı	POST ettiğiniz JSON'in authentication etiketi içerisinde göndermiş olduğunuz bilgileri doğrulayamadığımızda bu hatayı veriyoruz, eğer hesabınızda sabit IP tanımladıysanız ve farklı bir IP üzerinden istek yapıyorsanız yine bu hatayı alırsınız.
458	Tarih aralığı hatalı.	Gönderdiğiniz tarih formatı veya tarih aralığınız 10 günden daha fazla.
466	Hatalı numara	İstek içeriğindeki numara hatalı ise bu hatayı alırsınız.

Sample Request

{
  "request": {
    "authentication": {
      "key": "507caf2e1fcdb5eea9786332ca2d8785",
      "hash": "0db4e316db72c519ba08121985f6ddf479809053d555c"
    },
    "inbox": {
      "page": 1,
      "rowCount": 30,
      "filter": {
        "start": "2026-08-01 00:00:00",
        "end": "2026-08-17 23:59:59",
        "gsm": "05354101234"
      }
    }
  }
}

Sample Request (Without Filter)

{
  "request": {
    "authentication": {
      "key": "507caf2e1fcdb5eea9786332ca2d8785",
      "hash": "0db4e316db72c519ba08121985f6ddf479809053d555c"
    },
    "inbox": {
      "page": 1,
      "rowCount": 30
    }
  }
}

Sample Successful Response

{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "inbox": {
      "count": 2,
      "messages": [
        {
          "id": 25,
          "shortCode": "7889",
          "from": "+90505702xxxx",
          "keyword": "TESTPRX",
          "command": null,
          "action": "UNSUBSCRIBE",
          "message": "TESTPRX RET",
          "price": 0.8,
          "receivedAt": "2026-08-16 20:20:20"
        },
        {
          "id": 26,
          "shortCode": "7889",
          "from": "+90505702xxxx",
          "keyword": "TESTPRX",
          "command": null,
          "action": "RECORD_ONLY",
          "message": "TESTPRX BILGI",
          "price": 0.8,
          "receivedAt": "2026-08-16 20:20:20"
        }
      ]
    }
  }
}

Sample Error Response

{
  "response": {
    "status": {
      "code": 458,
      "message": "Tarih aralığı hatalı."
    }
  }
}

Common Mistakes

Forgetting the format suffix: When sending a JSON body, the /json suffix must be appended to the URL. Without it the server tries to parse the body as XML and rejects the request with 401.
Sending an incomplete date filter: start and end must be sent together; if only one is sent, or if end is earlier than start, the 458 error is returned.
Mistaking the from field for the short code: from is the number of the recipient who sent the message. The short code is returned in the shortCode field.
Assuming a price of 0 means free: A price of 0 does not mean the message was free; it indicates that your account balance was insufficient at the time the message was received.
Treating command as an empty string: When no command matches, this field is returned as null, not as an empty string (""). Clients that process the field directly as text must perform a null check.
Not expecting empty fields in old records: The command and action fields are returned empty for messages recorded before the feature went live.
Mistaking count for the number of records on the page: count is the total number of records matching your filter; evaluate it together with rowCount for pagination.

Request URL​

Request Body​

Definitions​

authentication​

inbox​

Server Response​

Definitions​

status​

inbox​

messages​

Error Codes​

Sample Request​

Sample Request (Without Filter)​

Sample Successful Response​

Sample Error Response​

Common Mistakes​

Request URL

Request Body

Definitions

authentication

inbox

Server Response

Definitions

status

inbox

messages

Error Codes

Sample Request

Sample Request (Without Filter)

Sample Successful Response

Sample Error Response

Common Mistakes