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:

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:

[dependencies]
esteria-api-client = "0.1.0"  # Replace with the latest version

To install the CLI globally:

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:

git clone https://github.com/yourusername/esteria-api-client.git
cd esteria-api-client

Build the Rust library and CLI:

cargo build --features cli

For Python bindings, ensure you have maturin installed (for building wheels):

pip install maturin
maturin develop  # Builds and installs locally for development

To build a PyPI wheel:

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:

esteria-api-client \
  --api-url https://api.esteria.eu \
  --api-key YOUR_API_KEY \
  --sender "MySender" \
  --number "+1234567890" \
  --text "Hello, world!"

Full options:

esteria-api-client --help

Output:

Send SMS via Esteria API

Usage: esteria-api-client [OPTIONS] --api-url <API_URL> --api-key <API_KEY> --sender <SENDER> --number <NUMBER> --text <TEXT>

Options:
  -u, --api-url <API_URL>      API base URL (e.g., https://api.esteria.eu)
  -k, --api-key <API_KEY>      API key for authentication
  -s, --sender <SENDER>        Sender name or number
  -n, --number <NUMBER>        Recipient phone number (with or without +)
  -t, --text <TEXT>            Message text to send
      --time <TIME>            Schedule time (RFC3339 format, e.g., 2024-12-31T23:59:59Z)
      --dlr-url <DLR_URL>      Delivery report URL
      --expired <EXPIRED>      Expiration time in minutes
      --user-key <USER_KEY>    User key for tracking
      --debug                  Enable debug mode
      --nolog                  Disable logging
      --flash                  Send as flash SMS
      --test                   Test mode (don't actually send)
      --nobl                   No blacklist check
      --convert                Convert characters
      --encoding <ENCODING>    Encoding: default, 8bit, or udh [default: 8bit]
  -h, --help                   Print help
  -V, --version                Print version

On success, it prints the message ID (e.g., Message ID: 12345).

Python Usage

Import and use the SmsClient class:

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:

use esteria_api_client::{SmsClient, SmsRequest, SmsFlags, Encoding};
use chrono::Utc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    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.

esteria-api-client 0.0.16