# Messages API

The exchange's internal messaging between buyers and sellers: read your inbox, reply, write to a seller about one of their routes, and, as a seller, list your buyers and message them.

## List buyer messages

`POST https://apiv2.telecomsxchange.com/buyers/messages`

Reference: https://help.telecomsxchange.com/reference/messages/#list-buyer-messages

Returns one page of your messages with sellers, newest first: the inbox (messages from sellers) or the outbox (messages you sent). Pass `id` to read a single message instead; reading an unread inbox message marks it as read. Messages about an anonymous route or DID name the sender as "Anonymous Owner of Route <name>" or "Anonymous Owner of DID Number <number>", leave out the seller ID and logo, and carry `anonymous: 1`. Free.

> Parameters work in the query string or the form body. Outbox rows carry `to_login` instead of `from_login`. `ts` is formatted m/d/y h:mmAM; the same time is also returned as YYYY-MM-DD HH:MM:SS (see the example). Only `inbox` and `outbox` are accepted for `show`; any other value returns an error that is not JSON.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `show` | string | body | no | Which folder to list. One of `inbox`, `outbox`. Default `inbox`. Example `inbox`. |
| `pager` | integer | body | no | Page size. Values below 1 fall back to 30. Default `30`. Example `30`. |
| `off` | integer | body | no | Number of messages to skip, for paging. Default `0`. Example `0`. |
| `id` | integer | body | no | Return only this message, one you sent or received, as `message` instead of a `messages` list. Marks it read if it is an unread message to you. Example `4821`. |

### Errors

| Message | When |
|---|---|
| `Message not found` | `id` is not a message you sent or received |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/messages" \
  -d show=inbox \
  -d pager=30 \
  -d off=0 \
  -d id=4821
```

### Response: Example

```json
{
  "status": "success",
  "messages": [
    {
      "i_message": "4821",
      "from_type": "vendor",
      "to_type": "customer",
      "i_from": "87",
      "i_to": "1042",
      "ts": "03/14/26 9:42AM",
      "status": "unread",
      "reply_to": "4807",
      "message_type": "message",
      "subject": "Low ASR to UK mobile",
      "message": "We rerouted the traffic; please test again.",
      "additional_data": null,
      "i_did": "0",
      "i_connection": "0",
      "thread_id": null,
      "from_login": "NorthwindVoice",
      "mysql_ts": "2026-03-14 09:42:17",
      "seller_logo": "https://apiv2.telecomsxchange.com/profilepics/vendor_87.png"
    }
  ]
}
```

## Reply to a seller message

`POST https://apiv2.telecomsxchange.com/buyers/message/reply/{id}`

Reference: https://help.telecomsxchange.com/reference/messages/#reply-to-a-seller-message

Replies to a message in your inbox. The reply keeps the original subject, is linked to it through `reply_to`, stays anonymous when the original was about an anonymous route or DID, and the seller is notified by email. Returns the new message's ID. Free.

> Send `message` in the form body; it is ignored in the query string. If `message` is empty, nothing is sent and the response returns the original message with status "success"; check for `i_message` in the response to confirm a reply was sent. If `id` is not a message addressed to you, the response is empty.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | ID (`i_message`) of the inbox message you are replying to, from List buyer messages. Example `4821`. |
| `message` | string | body | yes | Reply text. Example `Thanks, test calls now complete normally.`. |

### Errors

| Message | When |
|---|---|
| `error sending customer email` | the notification email cannot be sent; the reply is already saved (plain-text response) |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/message/reply/4821" \
  -d message='Thanks, test calls now complete normally.'
```

### Response: Example

```json
{
  "status": "success",
  "message": "Replied",
  "i_message": 4830
}
```

## Send a message to a seller

`POST https://apiv2.telecomsxchange.com/buyers/message/send`

Reference: https://help.telecomsxchange.com/reference/messages/#send-a-message-to-a-seller

Starts a conversation with a seller. Address the seller by `id`, or by `i_connection` or `i_did` to write to the owner of a route or number; for anonymous routes and DIDs the seller's identity stays hidden. The seller gets the message in their inbox and by email. Returns the new message's ID. Free.

> Send parameters in the form body; they are ignored in the query string. When you write through `i_connection` or `i_did` to an anonymous seller, the confirmation names the recipient as "Anonymous Owner of Route <name>" or "Anonymous Owner of DID Number <number>".

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | body | no | Seller ID (`i_vendor`), from List sellers. Required unless `i_connection` or `i_did` is given. Example `87`. |
| `i_connection` | integer | body | no | Route ID: writes to the owner of this route. Used only when `id` is not given. Example `5531`. |
| `i_did` | integer | body | no | DID ID: writes to the owner of this number. Used only when `id` is not given; `i_connection` takes precedence if both are sent. Example `22014`. |
| `subject` | string | body | yes | Message subject. Example `Low ASR to UK mobile`. |
| `message` | string | body | yes | Message text. Example `ASR on your UK Mobile CLI route dropped to 18% since 09:00 UTC. Can you check?`. |

### Errors

| Message | When |
|---|---|
| `Seller id missing (id=123)` | no `id` is sent and no seller matches `i_connection` or `i_did` |
| `Expecting id parameter` | `subject` or `message` is empty |
| `error sending customer email` | the notification email cannot be sent; the message is already saved (plain-text response) |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/message/send" \
  -d id=87 \
  -d i_connection=5531 \
  -d i_did=22014 \
  -d subject='Low ASR to UK mobile' \
  -d message='ASR on your UK Mobile CLI route dropped to 18% since 09:00 UTC. Can you check?'
```

### Response: Example

```json
{
  "status": "success",
  "message": "Message 4835 sent successfully to seller NorthwindVoice",
  "i_message": 4835
}
```

## List seller messages

`POST https://apiv2.telecomsxchange.com/sellers/messages`

Reference: https://help.telecomsxchange.com/reference/messages/#list-seller-messages

Returns one page of your messages with buyers, newest first: the inbox (messages from buyers) or the outbox (messages you sent). Pass `id` to read a single message; reading an unread inbox message marks it as read. Free.

> Parameters work in the query string or the form body. A non-zero `i_connection` or `i_did` means the buyer wrote to you about that route or number. Outbox rows carry `to_login` instead of `from_login`. Only `inbox` and `outbox` are accepted for `show`; any other value returns an error that is not JSON. To answer a message, use Reply to a buyer message.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `show` | string | body | no | Which folder to list. One of `inbox`, `outbox`. Default `inbox`. Example `inbox`. |
| `pager` | integer | body | no | Page size. Values below 1 fall back to 30. Default `30`. Example `30`. |
| `off` | integer | body | no | Number of messages to skip, for paging. Default `0`. Example `0`. |
| `id` | integer | body | no | Return only this message, one you sent or received, as `message` instead of a list. Marks it read if it is an unread message to you. Example `4835`. |

### Errors

| Message | When |
|---|---|
| `Message not found` | `id` is not a message you sent or received |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/sellers/messages" \
  -d show=inbox \
  -d pager=30 \
  -d off=0 \
  -d id=4835
```

### Response: Example

```json
{
  "status": "success",
  "messages": [
    {
      "i_message": "4835",
      "from_type": "customer",
      "to_type": "vendor",
      "i_from": "1042",
      "i_to": "87",
      "ts": "03/14/26 10:05AM",
      "status": "unread",
      "reply_to": null,
      "message_type": "message",
      "subject": "Low ASR to UK mobile",
      "message": "ASR on your UK Mobile CLI route dropped to 18% since 09:00 UTC. Can you check?",
      "additional_data": null,
      "i_did": "0",
      "i_connection": "5531",
      "thread_id": null,
      "from_login": "AcmeTelecom",
      "buyer_logo": "https://apiv2.telecomsxchange.com/profilepics/customer_1042.png"
    }
  ]
}
```

## List my buyers

`POST https://apiv2.telecomsxchange.com/sellers/buyers/list`

Reference: https://help.telecomsxchange.com/reference/messages/#list-my-buyers

Returns the buyers who use your routes (default) or rent your DIDs, 20 per page, each with the routes or numbers they use from you. Use the buyer IDs with Send a message to a buyer. Free.

> Each `purchases` item starts with a space followed by "Route:" or "DID:".

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `show_type` | string | body | no | `routes` lists buyers of your routes; `dids` lists buyers renting your numbers. One of `routes`, `dids`. Default `routes`. Example `routes`. |
| `login_or_email` | string | body | no | Only return buyers whose login or email contains this text. Example `acme`. |
| `off` | integer | body | no | Number of buyers to skip. Pages hold 20 buyers. Default `0`. Example `0`. |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/sellers/buyers/list" \
  -d show_type=routes \
  -d login_or_email=acme \
  -d off=0
```

### Response: Example

```json
{
  "status": "success",
  "buyers": [
    {
      "i_customer": "1042",
      "login": "AcmeTelecom",
      "purchases": [
        " Route:UK Mobile CLI",
        " Route:Premium A2P"
      ]
    },
    {
      "i_customer": "1188",
      "login": "GlobexComms",
      "purchases": [
        " Route:UK Mobile CLI"
      ]
    }
  ]
}
```

## Message my buyers

`POST https://apiv2.telecomsxchange.com/sellers/buyers/message`

Reference: https://help.telecomsxchange.com/reference/messages/#message-my-buyers

Sends the same message to each buyer on one page of List my buyers: up to 20 buyers, chosen with the same `show_type`, `login_or_email` and `off` filters. Each buyer gets it in their inbox and by email. Free.

> Each call reaches at most 20 buyers; page through with `off` to message all of them. On each page, buyers after the first see the subject prefixed with "TCXC Message: " in their inbox.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `subject` | string | body | yes | Message subject. Example `New coverage: Sudan DIDs`. |
| `message` | string | body | yes | Message text. Example `Sudanese mobile DIDs are now available for immediate activation.`. |
| `show_type` | string | body | no | Message buyers of your routes or renters of your DIDs. One of `routes`, `dids`. Default `routes`. Example `routes`. |
| `login_or_email` | string | body | no | Only message buyers whose login or email contains this text. |
| `off` | integer | body | no | Number of buyers to skip. Each call messages at most 20 buyers; repeat with off=20, 40,... to reach everyone. Default `0`. Example `0`. |

### Errors

| Message | When |
|---|---|
| `Empty subject or message are not allowed` | `subject` or `message` is missing or empty |
| `error sending customer email` | a notification email cannot be sent; buyers earlier in the page have already been messaged (plain-text response) |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/sellers/buyers/message" \
  -d subject='New coverage: Sudan DIDs' \
  -d message='Sudanese mobile DIDs are now available for immediate activation.' \
  -d show_type=routes \
  -d off=0
```

### Response: Example

```json
{
  "status": "success",
  "message": "Messages have been sent successfully to buyers list "
}
```

## Send a message to a buyer

`POST https://apiv2.telecomsxchange.com/sellers/message/send`

Reference: https://help.telecomsxchange.com/reference/messages/#send-a-message-to-a-buyer

Sends a new message from you as a seller to one of your buyers, identified by buyer ID from List my buyers. The buyer gets it in their inbox and by email. Returns the new message's ID. Free.

> Send parameters in the form body; they are ignored in the query string. Send both `subject` and `message`: if either is empty, the response is empty and nothing is sent.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | body | yes | Buyer ID (`i_customer`). Example `1042`. |
| `subject` | string | body | yes | Message subject. Example `Maintenance window`. |
| `message` | string | body | yes | Message text. Example `Our UK Mobile CLI route will be in maintenance on 20 March, 02:00-03:00 UTC.`. |

### Errors

| Message | When |
|---|---|
| `Buyer id missing (id=123)` | `id` is missing or 0 |
| `error sending customer email` | the notification email cannot be sent; the message is already saved (plain-text response) |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/sellers/message/send" \
  -d id=1042 \
  -d subject='Maintenance window' \
  -d message='Our UK Mobile CLI route will be in maintenance on 20 March, 02:00-03:00 UTC.'
```

### Response: Example

```json
{
  "status": "success",
  "message": "Message 4840 sent successfully to buyer AcmeTelecom",
  "i_message": 4840
}
```

## Reply to a buyer message

`POST https://apiv2.telecomsxchange.com/sellers/message/reply/{id}`

Reference: https://help.telecomsxchange.com/reference/messages/#reply-to-a-buyer-message

Replies to a message in your seller inbox. The reply keeps the original subject, is linked through `reply_to`, stays anonymous when the buyer wrote about an anonymous route or DID, and the buyer is notified by email. Returns the new message's ID. Free.

> Send `message` in the form body; it is ignored in the query string. If `message` is empty, nothing is sent and the response returns the original message with status "success"; check for `i_message` to confirm a reply was sent.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `id` | integer | path | yes | ID (`i_message`) of the inbox message you are replying to, from List seller messages. Example `4835`. |
| `message` | string | body | yes | Reply text. Example `We have rerouted UK mobile traffic; ASR is back above 45%.`. |

### Errors

| Message | When |
|---|---|
| `Sorry` | `id` is not a message addressed to you (plain-text response) |
| `error sending customer email` | the notification email cannot be sent; the reply is already saved (plain-text response) |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/sellers/message/reply/4835" \
  -d message='We have rerouted UK mobile traffic; ASR is back above 45%.'
```

### Response: Example

```json
{
  "status": "success",
  "message": "Replied",
  "i_message": 4841
}
```