# SimpleSMS REST API – Integration Guide for AI Coding Agents

> Source: the supplied SimpleSMS Postman Collection (`simpleSMS.postman_collection.json`).
>
> **Important:** this guide only documents information that can be established from the supplied collection. The collection contains no example responses, so exact response JSON structures, status codes, error codes, and undocumented behavior must not be invented.

## 1. Overview

Base URL:

```text
https://api.simplesms.hu/rest/SMSapi
```

Endpoints present in the collection:

| Function | Method | Endpoint |
|---|---|---|
| Authentication / obtain token | POST | `/connect` |
| Send SMS | POST | `/sendSMS` |
| Get SMS history | POST | `/getHistory` |
| Get SMS status | POST* | see discrepancy below |
| Get credit/balance | GET | `/getCreditNumber` |
| Get monthly statistics | GET | `/getMonthlyStat` |

The collection defines Bearer authentication globally. The `connect` request explicitly uses `noauth`, indicating that it is the authentication endpoint.

## 2. Authentication

### POST `/connect`

Full URL:

```text
https://api.simplesms.hu/rest/SMSapi/connect
```

Authentication: none.

Body type:

```text
multipart/form-data
```

Parameters:

| Parameter | Meaning |
|---|---|
| `username` | username configured in the SimpleSMS portal |
| `password` | password configured in the SimpleSMS portal |
| `domain` | domain configured in the SimpleSMS portal |

Example:

```bash
curl -X POST \
  'https://api.simplesms.hu/rest/SMSapi/connect' \
  -F 'username=USERNAME' \
  -F 'password=PASSWORD' \
  -F 'domain=HOST'
```

### Using the token

Global collection authentication is:

```http
Authorization: Bearer <TOKEN>
```

Requests other than `connect` inherit the collection-level Bearer authentication.

**Implementation rule for AI agents:** obtain the authentication token from the `/connect` response and use it for subsequent requests. The supplied collection contains no response example, therefore the exact JSON property containing the token must not be guessed. Determine it from a real response or make response parsing configurable until confirmed.

## 3. Sending an SMS

### POST `/sendSMS`

Full URL:

```text
https://api.simplesms.hu/rest/SMSapi/sendSMS
```

Authentication:

```http
Authorization: Bearer <TOKEN>
```

Body:

```text
multipart/form-data
```

Enabled fields:

| Parameter | Example | Meaning |
|---|---|---|
| `message` | `Teszt8` | SMS message text |
| `phone_number` | `36303539369` | complete phone number |

The following fields exist but are **disabled** in the collection:

| Parameter | Example | Meaning |
|---|---|---|
| `country_code` | `36` | country calling code |
| `area_code` | `30` | operator/area code |
| `number` | `3539369` | remaining number |

Therefore, the supplied collection demonstrates `phone_number` as the active phone-number input.

Example:

```bash
curl -X POST \
  'https://api.simplesms.hu/rest/SMSapi/sendSMS' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'phone_number=36303539369' \
  -F 'message=Test message'
```

The example represents the number with country code and without a leading `+`. This is an observed example, not a documented universal validation rule.

Comments elsewhere in the collection state that an `sms_id` is received when sending an SMS and is used by later requests. The exact response structure is not included.

## 4. SMS history

### POST `/getHistory`

Full URL:

```text
https://api.simplesms.hu/rest/SMSapi/getHistory
```

Authentication:

```http
Authorization: Bearer <TOKEN>
```

Body:

```text
multipart/form-data
```

Parameter:

| Parameter | Meaning |
|---|---|
| `sms_id` | SMS ID received from the send response |

Example:

```bash
curl -X POST \
  'https://api.simplesms.hu/rest/SMSapi/getHistory' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'sms_id=SMS_ID'
```

## 5. SMS status – IMPORTANT COLLECTION DISCREPANCY

The collection contains a request named `getStatus` with an `sms_id` form-data field.

However, its configured URL is:

```text
https://api.simplesms.hu/rest/SMSapi/getMonthlyStat
```

rather than an obvious `/getStatus` endpoint.

This appears likely to be a collection configuration/naming discrepancy, but the supplied source does **not** establish that `/getStatus` is the correct URL.

**AI implementation rule:** do not implement a production status endpoint by guessing `/getStatus`. Verify the correct endpoint with the SimpleSMS API/provider first. The only safe conclusion from the collection is that the request named `getStatus` expects an `sms_id` field.

## 6. Credit / balance

### GET `/getCreditNumber`

Full URL:

```text
https://api.simplesms.hu/rest/SMSapi/getCreditNumber
```

Authentication:

```http
Authorization: Bearer <TOKEN>
```

No body parameters are defined.

Example:

```bash
curl \
  'https://api.simplesms.hu/rest/SMSapi/getCreditNumber' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

The response structure is not documented in the collection.

## 7. Monthly statistics

### GET `/getMonthlyStat`

Full URL:

```text
https://api.simplesms.hu/rest/SMSapi/getMonthlyStat
```

Authentication:

```http
Authorization: Bearer <TOKEN>
```

No body parameters or date-range query parameters are defined.

Example:

```bash
curl \
  'https://api.simplesms.hu/rest/SMSapi/getMonthlyStat' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

## 8. Recommended integration flow

```text
1. POST /connect
      |
      v
2. Extract token
      |
      v
3. Authorization: Bearer TOKEN
      |
      +--> POST /sendSMS
      |       |
      |       +--> store sms_id
      |
      +--> POST /getHistory
      |
      +--> GET /getCreditNumber
      |
      +--> GET /getMonthlyStat
```

Add status lookup only after its endpoint has been verified.

## 9. Instructions for AI coding agents

When implementing a SimpleSMS client from this document:

1. Create a dedicated `SimpleSMSClient` or service class.
2. Make the base URL configurable; default to `https://api.simplesms.hu/rest/SMSapi`.
3. Never hard-code `username`, `password`, or `domain`.
4. Read credentials from environment variables or a secret store.
5. Never log passwords or Bearer tokens.
6. Call `/connect` without Bearer authentication.
7. Use Bearer authentication for the other documented requests.
8. Encode POST bodies as `multipart/form-data`, matching the collection.
9. Treat phone numbers as strings, never integers.
10. Treat `sms_id` as a string until the real API type is confirmed.
11. Do not invent response JSON property names.
12. Do not invent API error/status codes.
13. Handle transport/network errors separately from API/business errors.
14. Configure sensible connection and request timeouts.
15. Do not blindly retry `sendSMS`: without idempotency protection, a retry may send duplicate SMS messages.
16. Verify the status endpoint before implementing `getStatus`.
17. Structure response parsing so it can easily be adjusted when actual response examples become available.

Recommended public client interface:

```text
connect(username, password, domain)
sendSMS(phoneNumber, message)
getHistory(smsId)
getCreditNumber()
getMonthlyStat()
```

Only add:

```text
getStatus(smsId)
```

to the stable interface after verifying its URL.

## 10. Security

Never commit:

```text
SimpleSMS username
SimpleSMS password
SimpleSMS domain/host if sensitive
Bearer token
```

Example `.env`:

```dotenv
SIMPLESMS_BASE_URL=https://api.simplesms.hu/rest/SMSapi
SIMPLESMS_USERNAME=
SIMPLESMS_PASSWORD=
SIMPLESMS_DOMAIN=
```

Do not commit the `.env` file.

## 11. Information NOT provided by the collection

Do not assume any of the following:

- exact response JSON structures;
- authentication token property name;
- token lifetime;
- HTTP status-code semantics;
- API-specific error codes;
- rate limits;
- timeout requirements;
- maximum SMS length;
- GSM-7 vs Unicode behavior;
- SMS segment/billing rules;
- complete phone-number validation rules;
- bulk sending support;
- callback/webhook support;
- actual `getStatus` URL;
- token refresh behavior.

These require real API responses or additional official documentation.

## 12. Quick reference

```text
BASE URL
https://api.simplesms.hu/rest/SMSapi

AUTH
POST /connect
form-data:
  username
  password
  domain

SEND SMS
POST /sendSMS
Bearer token
form-data:
  phone_number
  message

HISTORY
POST /getHistory
Bearer token
form-data:
  sms_id

CREDIT
GET /getCreditNumber
Bearer token

MONTHLY STAT
GET /getMonthlyStat
Bearer token

STATUS
Ambiguous in supplied collection; verification required.
```