> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beem.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending messages

> Send outbound SMS from your application to the Messaging Platform.

This section describes how to send requests from your Client Application to the Messaging Platform (MP) and interpret the responses.

***

## Request flow

```text theme={null}
Your Application
      │
      │ HTTP GET or POST
      ▼
https://api.blsmsgw.com:8443/bin/send
      │
      ▼
Messaging Platform
      │
      ▼
HTTP 200 + response body
```

The client issues an HTTP GET or POST request to the platform. MP returns either an HTTP error code or **HTTP 200 OK**, in which case the response body contains additional status information.

<Tip>
  Use **POST** rather than GET. GET query strings can exceed size limits and may be truncated by proxies.
</Tip>

***

## Send endpoints

| Endpoint              | Response format      |
| --------------------- | -------------------- |
| `POST /bin/send`      | Plain text (default) |
| `POST /bin/send.json` | JSON                 |
| `POST /bin/send.xml`  | XML                  |

All endpoints accept the same form parameters. See the [Parameters reference](/guides/multicountry-sms/parameters) for the full list.

***

## Required parameters

| Parameter    | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| `USERNAME`   | Provided username                                                            |
| `PASSWORD`   | Provided password                                                            |
| `DESTADDR`   | Destination MSISDN in international format without `+` (e.g. `255650000001`) |
| `SOURCEADDR` | Sender ID — numeric or alphanumeric (max 11 characters)                      |
| `MESSAGE`    | Message content (URL-encoded for text; hex for binary)                       |

***

## Response formats

### Plain text (default)

When HTTP status is `200`, the response body contains two or three lines:

1. **Message ID** (numeric), or `-1` if the request failed
2. **Status code** — `0` for success; otherwise a numeric error code
3. **Status text** (optional) — human-readable error description

**Success example:**

```text theme={null}
124365
0
OK
```

**Failure example:**

```text theme={null}
-1
-2
Recipient (DESTADDR) is missing
```

See [API responses](/guides/multicountry-sms/api-responses) for HTTP-level errors. Platform-level failures may still return **HTTP 200** with a failure status in the body (message ID `-1`).

### Common status codes

| Code | Meaning                                    |
| ---- | ------------------------------------------ |
| `0`  | Success                                    |
| `1`  | Unknown error                              |
| `2`  | Syntax error / missing mandatory parameter |
| `10` | Access denied                              |
| `11` | Invalid message                            |
| `16` | No message credits left                    |

### JSON response

```json theme={null}
{
  "results": [
    {
      "status": "0",
      "msgid": "25593581",
      "statustext": "OK"
    }
  ],
  "balance": "-818.5710"
}
```

### XML response

```xml theme={null}
<response>
  <results>
    <result>
      <status>0</status>
      <msgid>25593582</msgid>
      <statustext>OK</statustext>
    </result>
  </results>
  <balance>-818.6210</balance>
</response>
```

***

## Persistent HTTP connections

The messaging platform allows HTTP connections to remain open to increase throughput. To maintain a persistent connection:

* Do **not** specify `Connection: close` in your HTTP request
* Do **not** close the connection after sending a message
* Read the response data for each submission before sending the next request

Multiple GET or POST requests can be submitted over the same connection.

***

## Sample code

Sample implementations in PHP, C#/.NET, Java, Python, and Node.js are available on GitHub:

[beem-sms-txn-api-sample — send](https://github.com/beemafrica/beem-sms-txn-api-sample/tree/master/send)