XML Post API

To retrieve the list of messages sent to your short code in XML 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

Warning

The format suffix in the URL must match the format of the body you send. This URL expects an XML body. If you want to send a JSON body, use the JSON Post API URL instead. Otherwise the server tries to parse the body as XML, fails, and rejects the request with 401.

Request Body

<request>
  <authentication>
    <key></key>
    <hash></hash>
  </authentication>
  <inbox>
    <page></page>
    <rowCount></rowCount>
    <filter>
      <start></start>
      <end></end>
      <gsm></gsm>
    </filter>
  </inbox>
</request>

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

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <code></code>
    <message></message>
  </status>
  <inbox>
    <count></count>
    <messages>
      <id></id>
      <shortCode></shortCode>
      <from></from>
      <keyword></keyword>
      <command></command>
      <action></action>
      <message></message>
      <price></price>
      <receivedAt></receivedAt>
    </messages>
    <messages>
      <id></id>
      <shortCode></shortCode>
      <from></from>
      <keyword></keyword>
      <command></command>
      <action></action>
      <message></message>
      <price></price>
      <receivedAt></receivedAt>
    </messages>
  </inbox>
</response>

Definitions

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

status

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

• 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: Contains the details of a received message record. It is repeated as many times as there are messages on the queried page. Its child tags are as follows:

  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, the value is empty; in the XML response the tag is returned empty in that case.

  • 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 tags 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 XML'in yapısındaki hatadan kaynaklanır. Bu hatalar genellikle, yanlış yazılan XML etiketi, düzgün kapatılmayan XML etiketi veya CDATA kullanılmadan XML'in yapısını bozabilecek bir karakterin kullanımından kaynaklanır.
401	Üyelik bilgileri hatalı	POST ettiğiniz XML'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

<?xml version="1.0" encoding="UTF-8"?>
<request>
  <authentication>
    <key>507caf2e1fcdb5eea9786332ca2d8785</key>
    <hash>0db4e316db72c519ba08121985f6ddf479809053d555c</hash>
  </authentication>
  <inbox>
    <page>1</page>
    <rowCount>30</rowCount>
    <filter>
      <start>2026-08-01 00:00:00</start>
      <end>2026-08-17 23:59:59</end>
      <gsm>05354101234</gsm>
    </filter>
  </inbox>
</request>

Sample Request (Without Filter)

<?xml version="1.0" encoding="UTF-8"?>
<request>
  <authentication>
    <key>507caf2e1fcdb5eea9786332ca2d8785</key>
    <hash>0db4e316db72c519ba08121985f6ddf479809053d555c</hash>
  </authentication>
  <inbox>
    <page>1</page>
    <rowCount>30</rowCount>
  </inbox>
</request>

Sample Successful Response

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <code>200</code>
    <message>İşlem başarılı</message>
  </status>
  <inbox>
    <count>2</count>
    <messages>
      <id>25</id>
      <shortCode>7889</shortCode>
      <from>+90505702xxxx</from>
      <keyword>TESTPRX</keyword>
      <command></command>
      <action>UNSUBSCRIBE</action>
      <message>TESTPRX RET</message>
      <price>0.8</price>
      <receivedAt>2026-08-16 20:20:20</receivedAt>
    </messages>
    <messages>
      <id>26</id>
      <shortCode>7889</shortCode>
      <from>+90505702xxxx</from>
      <keyword>TESTPRX</keyword>
      <command></command>
      <action>RECORD_ONLY</action>
      <message>TESTPRX BILGI</message>
      <price>0.8</price>
      <receivedAt>2026-08-16 20:20:20</receivedAt>
    </messages>
  </inbox>
</response>

Sample Error Response

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <code>458</code>
    <message>Tarih aralığı hatalı.</message>
  </status>
</response>

Common Mistakes

• Mixing up the format suffix and the body format: This URL expects an XML body. If you send a JSON body, the server tries to parse it as XML and rejects the request with 401. If you are going to use JSON, use the /v1/get-inbox/json URL.
• 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 tag for the short code: from is the number of the recipient who sent the message. The short code is returned in the shortCode tag.
• 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.
• Not expecting empty fields in old records: The command and action tags 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.