https://github.com/bixority/esteria-api-client
Esteria API client
https://github.com/bixority/esteria-api-client
api client esteria python rust
Last synced: 3 months ago
JSON representation
Esteria API client
- Host: GitHub
- URL: https://github.com/bixority/esteria-api-client
- Owner: bixority
- License: gpl-3.0
- Created: 2025-10-15T19:25:14.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-03-24T08:12:16.000Z (3 months ago)
- Last Synced: 2026-03-25T10:09:42.052Z (3 months ago)
- Topics: api, client, esteria, python, rust
- Language: Rust
- Homepage:
- Size: 286 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Esteria API Client
A Rust-based client library for sending SMS messages via the Esteria API (https://esteria.eu). This project provides:
- A core Rust library for programmatic SMS sending.
- A command-line interface (CLI) for quick SMS dispatch.
- Python bindings for easy integration into Python applications.
The client supports advanced features like scheduled sending, delivery reports, flash SMS, test mode, and custom encodings.
## Features
- **Authentication**: Secure API key-based access.
- **SMS Options**:
- Scheduled delivery.
- Delivery report (DLR) callbacks.
- Expiration timeouts.
- Flags for debug, no-log, flash, test, no-blacklist, and character conversion.
- **Encodings**: Default, 8-bit, or UDH (User Data Header).
- **Error Handling**: Detailed error codes and messages from the API.
- **Cross-Platform**: Works on Linux, macOS, and Windows.
- **Python Integration**: Seamless Python API via PyO3 bindings.
- **CLI Tool**: Simple command-line usage with environment variable support.
## Installation
### For Python Users (via PyPI)
Install the Python package directly:
```bash
pip install esteria-api-client
```
This installs the Python bindings, which include the underlying Rust library.
### For Rust Users (via crates.io)
Add the library to your `Cargo.toml`:
```toml
[dependencies]
esteria-api-client = "0.1.0" # Replace with the latest version
```
To install the CLI globally:
```bash
cargo install esteria-api-client --features cli
```
Note: The `cli` feature enables the command-line tool, and `python` enables Python bindings (used for building wheels).
### Building from Source
Clone the repository:
```bash
git clone https://github.com/yourusername/esteria-api-client.git
cd esteria-api-client
```
Build the Rust library and CLI:
```bash
cargo build --features cli
```
For Python bindings, ensure you have `maturin` installed (for building wheels):
```bash
pip install maturin
maturin develop # Builds and installs locally for development
```
To build a PyPI wheel:
```bash
maturin build --release
```
## Usage
### Environment Variables
The client supports these env vars for convenience:
- `ESTERIA_API_BASE_URL`: API endpoint (default: `https://api.esteria.eu`).
- `ESTERIA_API_KEY`: Your API key.
### CLI Usage
The CLI tool (`esteria-api-client`) allows sending SMS from the terminal.
Basic example:
```bash
esteria-api-client \
--api-url https://api.esteria.eu \
--api-key YOUR_API_KEY \
--sender "MySender" \
--number "+1234567890" \
--text "Hello, world!"
```
Full options:
```bash
esteria-api-client --help
```
Output:
```
Send SMS via Esteria API
Usage: esteria-api-client [OPTIONS] --api-url --api-key --sender --number --text
Options:
-u, --api-url API base URL (e.g., https://api.esteria.eu)
-k, --api-key API key for authentication
-s, --sender Sender name or number
-n, --number Recipient phone number (with or without +)
-t, --text Message text to send
--time
On success, it prints the message ID (e.g., `Message ID: 12345`).
### Python Usage
Import and use the `SmsClient` class:
```python
import asyncio
from esteria_api_client import SmsClient, SmsFlags, PyEncoding
async def main():
client = SmsClient("https://api.esteria.eu")
# Basic send
result = await client.send_sms(
api_key="YOUR_API_KEY",
sender="MySender",
number="+1234567890",
text="Hello from Python!"
)
print(result) # Message ID on success
# With options
flags = SmsFlags.debug() | SmsFlags.flash()
result = await client.send_sms(
api_key="YOUR_API_KEY",
sender="MySender",
number="+1234567890",
text="Scheduled flash SMS",
time=1735689599, # Unix timestamp
dlr_url="https://your-callback-url.com",
expired=60, # Expires in 60 minutes
flag_debug=True,
flag_flash=True,
user_key="my-tracking-key",
use_8bit=False, # Use default encoding
udh=True # UDH encoding
)
print(result)
# Run the async function
asyncio.run(main())
```
- `SmsFlags`: Bitflags for options (e.g., `SmsFlags.debug()`, `SmsFlags.flash()`). Combine with `|`.
- `PyEncoding`: Constants like `PyEncoding.DEFAULT`, `PyEncoding.EIGHT_BIT`, `PyEncoding.UDH`.
- Errors: Raises `RuntimeError` on failure with details.
Note: The `time` parameter is a Unix timestamp (seconds since epoch).
### Rust Usage (Library)
Use the `SmsClient` and `SmsRequest` structs:
```rust
use esteria_api_client::{SmsClient, SmsRequest, SmsFlags, Encoding};
use chrono::Utc;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = SmsClient::new("https://api.esteria.eu".to_string());
let request = SmsRequest::new(
"YOUR_API_KEY",
"MySender",
"+1234567890",
"Hello from Rust!"
)
.with_flags(SmsFlags::DEBUG | SmsFlags::FLASH)
.with_encoding(Encoding::Udh)
.with_time(Utc::now()) // Schedule for now (or future)
.with_dlr_url("https://your-callback-url.com")
.with_expired(60)
.with_user_key("my-tracking-key");
match client.send_sms(request).await {
Ok(code) => println!("Message ID: {}", code),
Err(e) => eprintln!("Error: {}", e),
}
Ok(())
}
```
- `SmsFlags`: Bitflags (e.g., `SmsFlags::DEBUG`).
- `Encoding`: Enum for `Default`, `EightBit`, `Udh`.
- Errors: `SmsError` variants for handling.
## API Error Codes
If sending fails, the client returns detailed errors based on Esteria's response codes:
- 1: System internal error
- 2: Missing parameter
- 3: Unable to authenticate
- ... (see full list in `esteria.rs`)
## Developer Notes
- **Features**: Enable `cli` for the command-line tool or `python` for bindings via Cargo.
- **Dependencies**: Uses `reqwest` for HTTP, `chrono` for dates, `clap` for CLI, `pyo3` for Python, and `bitflags` for flags.
- **Logging**: Uses `env_logger` (init in CLI).
- **Testing**: Run `cargo test`. Use `--flag-test` for API test mode.
- **Contributing**: Pull requests welcome! Focus on bug fixes, features, or docs.
- **License**: GPLv3.
For issues or suggestions, open a GitHub issue.
---
This project is not affiliated with Esteria.eu. Ensure you have an active Esteria account and API key.