{"id":47769579,"url":"https://github.com/bixority/esteria-api-client","last_synced_at":"2026-04-03T08:45:23.982Z","repository":{"id":318976918,"uuid":"1077101908","full_name":"bixority/esteria-api-client","owner":"bixority","description":"Esteria API client","archived":false,"fork":false,"pushed_at":"2026-03-24T08:12:16.000Z","size":293,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T10:09:42.052Z","etag":null,"topics":["api","client","esteria","python","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bixority.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-15T19:25:14.000Z","updated_at":"2026-03-24T08:12:14.000Z","dependencies_parsed_at":"2025-10-17T14:26:32.899Z","dependency_job_id":"aad6c191-7428-49bc-b7a6-8a7a7cfc4106","html_url":"https://github.com/bixority/esteria-api-client","commit_stats":null,"previous_names":["bixority/esteria-api-client"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/bixority/esteria-api-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bixority%2Festeria-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bixority%2Festeria-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bixority%2Festeria-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bixority%2Festeria-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bixority","download_url":"https://codeload.github.com/bixority/esteria-api-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bixority%2Festeria-api-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31343575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T08:03:20.796Z","status":"ssl_error","status_checked_at":"2026-04-03T08:00:37.834Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","esteria","python","rust"],"created_at":"2026-04-03T08:45:23.200Z","updated_at":"2026-04-03T08:45:23.977Z","avatar_url":"https://github.com/bixority.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Esteria API Client\n\nA Rust-based client library for sending SMS messages via the Esteria API (https://esteria.eu). This project provides:\n\n- A core Rust library for programmatic SMS sending.\n- A command-line interface (CLI) for quick SMS dispatch.\n- Python bindings for easy integration into Python applications.\n\nThe client supports advanced features like scheduled sending, delivery reports, flash SMS, test mode, and custom encodings.\n\n## Features\n\n- **Authentication**: Secure API key-based access.\n- **SMS Options**:\n  - Scheduled delivery.\n  - Delivery report (DLR) callbacks.\n  - Expiration timeouts.\n  - Flags for debug, no-log, flash, test, no-blacklist, and character conversion.\n- **Encodings**: Default, 8-bit, or UDH (User Data Header).\n- **Error Handling**: Detailed error codes and messages from the API.\n- **Cross-Platform**: Works on Linux, macOS, and Windows.\n- **Python Integration**: Seamless Python API via PyO3 bindings.\n- **CLI Tool**: Simple command-line usage with environment variable support.\n\n## Installation\n\n### For Python Users (via PyPI)\n\nInstall the Python package directly:\n\n```bash\npip install esteria-api-client\n```\n\nThis installs the Python bindings, which include the underlying Rust library.\n\n### For Rust Users (via crates.io)\n\nAdd the library to your `Cargo.toml`:\n\n```toml\n[dependencies]\nesteria-api-client = \"0.1.0\"  # Replace with the latest version\n```\n\nTo install the CLI globally:\n\n```bash\ncargo install esteria-api-client --features cli\n```\n\nNote: The `cli` feature enables the command-line tool, and `python` enables Python bindings (used for building wheels).\n\n### Building from Source\n\nClone the repository:\n\n```bash\ngit clone https://github.com/yourusername/esteria-api-client.git\ncd esteria-api-client\n```\n\nBuild the Rust library and CLI:\n\n```bash\ncargo build --features cli\n```\n\nFor Python bindings, ensure you have `maturin` installed (for building wheels):\n\n```bash\npip install maturin\nmaturin develop  # Builds and installs locally for development\n```\n\nTo build a PyPI wheel:\n\n```bash\nmaturin build --release\n```\n\n## Usage\n\n### Environment Variables\n\nThe client supports these env vars for convenience:\n\n- `ESTERIA_API_BASE_URL`: API endpoint (default: `https://api.esteria.eu`).\n- `ESTERIA_API_KEY`: Your API key.\n\n### CLI Usage\n\nThe CLI tool (`esteria-api-client`) allows sending SMS from the terminal.\n\nBasic example:\n\n```bash\nesteria-api-client \\\n  --api-url https://api.esteria.eu \\\n  --api-key YOUR_API_KEY \\\n  --sender \"MySender\" \\\n  --number \"+1234567890\" \\\n  --text \"Hello, world!\"\n```\n\nFull options:\n\n```bash\nesteria-api-client --help\n```\n\nOutput:\n\n```\nSend SMS via Esteria API\n\nUsage: esteria-api-client [OPTIONS] --api-url \u003cAPI_URL\u003e --api-key \u003cAPI_KEY\u003e --sender \u003cSENDER\u003e --number \u003cNUMBER\u003e --text \u003cTEXT\u003e\n\nOptions:\n  -u, --api-url \u003cAPI_URL\u003e      API base URL (e.g., https://api.esteria.eu)\n  -k, --api-key \u003cAPI_KEY\u003e      API key for authentication\n  -s, --sender \u003cSENDER\u003e        Sender name or number\n  -n, --number \u003cNUMBER\u003e        Recipient phone number (with or without +)\n  -t, --text \u003cTEXT\u003e            Message text to send\n      --time \u003cTIME\u003e            Schedule time (RFC3339 format, e.g., 2024-12-31T23:59:59Z)\n      --dlr-url \u003cDLR_URL\u003e      Delivery report URL\n      --expired \u003cEXPIRED\u003e      Expiration time in minutes\n      --user-key \u003cUSER_KEY\u003e    User key for tracking\n      --debug                  Enable debug mode\n      --nolog                  Disable logging\n      --flash                  Send as flash SMS\n      --test                   Test mode (don't actually send)\n      --nobl                   No blacklist check\n      --convert                Convert characters\n      --encoding \u003cENCODING\u003e    Encoding: default, 8bit, or udh [default: 8bit]\n  -h, --help                   Print help\n  -V, --version                Print version\n```\n\nOn success, it prints the message ID (e.g., `Message ID: 12345`).\n\n### Python Usage\n\nImport and use the `SmsClient` class:\n\n```python\nimport asyncio\nfrom esteria_api_client import SmsClient, SmsFlags, PyEncoding\n\nasync def main():\n    client = SmsClient(\"https://api.esteria.eu\")\n\n    # Basic send\n    result = await client.send_sms(\n        api_key=\"YOUR_API_KEY\",\n        sender=\"MySender\",\n        number=\"+1234567890\",\n        text=\"Hello from Python!\"\n    )\n    print(result)  # Message ID on success\n\n    # With options\n    flags = SmsFlags.debug() | SmsFlags.flash()\n    result = await client.send_sms(\n        api_key=\"YOUR_API_KEY\",\n        sender=\"MySender\",\n        number=\"+1234567890\",\n        text=\"Scheduled flash SMS\",\n        time=1735689599,  # Unix timestamp\n        dlr_url=\"https://your-callback-url.com\",\n        expired=60,  # Expires in 60 minutes\n        flag_debug=True,\n        flag_flash=True,\n        user_key=\"my-tracking-key\",\n        use_8bit=False,  # Use default encoding\n        udh=True  # UDH encoding\n    )\n    print(result)\n\n# Run the async function\nasyncio.run(main())\n```\n\n- `SmsFlags`: Bitflags for options (e.g., `SmsFlags.debug()`, `SmsFlags.flash()`). Combine with `|`.\n- `PyEncoding`: Constants like `PyEncoding.DEFAULT`, `PyEncoding.EIGHT_BIT`, `PyEncoding.UDH`.\n- Errors: Raises `RuntimeError` on failure with details.\n\nNote: The `time` parameter is a Unix timestamp (seconds since epoch).\n\n### Rust Usage (Library)\n\nUse the `SmsClient` and `SmsRequest` structs:\n\n```rust\nuse esteria_api_client::{SmsClient, SmsRequest, SmsFlags, Encoding};\nuse chrono::Utc;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let client = SmsClient::new(\"https://api.esteria.eu\".to_string());\n\n    let request = SmsRequest::new(\n        \"YOUR_API_KEY\",\n        \"MySender\",\n        \"+1234567890\",\n        \"Hello from Rust!\"\n    )\n    .with_flags(SmsFlags::DEBUG | SmsFlags::FLASH)\n    .with_encoding(Encoding::Udh)\n    .with_time(Utc::now())  // Schedule for now (or future)\n    .with_dlr_url(\"https://your-callback-url.com\")\n    .with_expired(60)\n    .with_user_key(\"my-tracking-key\");\n\n    match client.send_sms(request).await {\n        Ok(code) =\u003e println!(\"Message ID: {}\", code),\n        Err(e) =\u003e eprintln!(\"Error: {}\", e),\n    }\n\n    Ok(())\n}\n```\n\n- `SmsFlags`: Bitflags (e.g., `SmsFlags::DEBUG`).\n- `Encoding`: Enum for `Default`, `EightBit`, `Udh`.\n- Errors: `SmsError` variants for handling.\n\n## API Error Codes\n\nIf sending fails, the client returns detailed errors based on Esteria's response codes:\n\n- 1: System internal error\n- 2: Missing parameter\n- 3: Unable to authenticate\n- ... (see full list in `esteria.rs`)\n\n## Developer Notes\n\n- **Features**: Enable `cli` for the command-line tool or `python` for bindings via Cargo.\n- **Dependencies**: Uses `reqwest` for HTTP, `chrono` for dates, `clap` for CLI, `pyo3` for Python, and `bitflags` for flags.\n- **Logging**: Uses `env_logger` (init in CLI).\n- **Testing**: Run `cargo test`. Use `--flag-test` for API test mode.\n- **Contributing**: Pull requests welcome! Focus on bug fixes, features, or docs.\n- **License**: GPLv3.\n\nFor issues or suggestions, open a GitHub issue.\n\n---\n\nThis project is not affiliated with Esteria.eu. Ensure you have an active Esteria account and API key.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbixority%2Festeria-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbixority%2Festeria-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbixority%2Festeria-api-client/lists"}