android-sms-gateway 0.2.0

Rust client library for SMSGate API
Documentation

Contributors Forks Stargazers Issues Apache-2.0 License Crates.io Docs.rs

Table of Contents

About The Project

A Rust client library for the SMSGate API. Send and receive SMS messages through your Android device with full type safety and async support.

Key features:

  • Full API coverage: messages, devices, settings, webhooks, auth, inbox, logs
  • Async-first with tokio
  • End-to-end message encryption (AES-256-CBC + PBKDF2-SHA1)
  • Webhook payload signature verification (HMAC-SHA256)
  • JWT and HTTP Basic authentication
  • rustls by default — no OpenSSL dependency
  • Comprehensive client-side validation

Built With

Rust tokio reqwest serde

Getting Started

Prerequisites

  • Rust 2021 edition (MSRV 1.75+)
  • An SMSGate app and API credentials

Quick Start

  1. Add the dependency to your Cargo.toml:

    [dependencies]
android-sms-gateway = "0.1"

  2. Create a client and send your first message:

    use android_sms_gateway::{
    Client, ClientConfig,
    types::{Message, SendOptions, TextMessage},
};

#[tokio::main]
async fn main() -> Result<(), android_sms_gateway::Error> {
    let client = Client::new(
        ClientConfig::new().with_token("your-jwt-token"),
    )?;

    let health = client.check_health().await?;
    println!("Status: {:?}", health.status);

    let message = Message {
        phone_numbers: vec!["+1234567890".into()],
        text_message: Some(TextMessage { text: "Hello!".into() }),
        ..Default::default()
    };
    let state = client.send(&message, &SendOptions::new()).await?;
    println!("Message ID: {}", state.id);

    Ok(())
}

Usage

Feature Flags

Feature Description Default
rustls-tls Use rustls for TLS yes
native-tls Use platform-native TLS no
encryption Enable AES-256-CBC encryption/decryption no

API Overview

Method Endpoint Description
check_health() GET /health Service health check
send() POST /messages Send a text or data message
list_messages() GET /messages List messages with filtering
get_message_state() GET /messages/{id} Get message delivery status
cancel_message() DELETE /messages/{id} Cancel a pending message
list_devices() GET /devices List registered devices
delete_device() DELETE /devices/{id} Remove a device
get_settings() GET /settings Get device settings
replace_settings() PUT /settings Replace all settings
update_settings() PATCH /settings Partially update settings
list_webhooks() GET /webhooks List registered webhooks
register_webhook() POST /webhooks Register a new webhook
delete_webhook() DELETE /webhooks/{id} Remove a webhook
generate_token() POST /auth/token Create a JWT token
refresh_token() POST /auth/token/refresh Refresh an existing token
revoke_token() DELETE /auth/token/{jti} Revoke a token
refresh_inbox() POST /inbox/refresh Pull new messages from device
list_inbox_messages() GET /inbox List received messages
get_logs() GET /logs Retrieve device logs
export_inbox() POST /inbox/export Export messages via webhooks

Webhook Verification

Verify incoming webhook payloads signed by the Android device:

use android_sms_gateway::webhook::verify_signature;

let valid = verify_signature(
    "your-signing-key",      // from Settings > Webhooks > Signing Key
    r#"{"event":"sms:received","payload":{}}"#,
    "1700000000",            // X-Timestamp header value
    "abc123def456",          // X-Signature header value
);

Encryption

Encrypt message fields before sending (AES-256-CBC + PBKDF2-SHA1):

android-sms-gateway = { version = "0.1", features = ["encryption"] }

use android_sms_gateway::encryption::Encryptor;

let encryptor = Encryptor::new("my-passphrase");
let encrypted = encryptor.encrypt("Sensitive message");
let decrypted = encryptor.decrypt(&encrypted).unwrap();

For full API documentation, see docs.rs/android-sms-gateway.

Roadmap

  • Core HTTP transport with error mapping
  • All REST API endpoints (messages, devices, settings, webhooks, auth, inbox, logs)
  • Domain types with Serde serialization and client-side validation
  • Webhook payload signature verification (HMAC-SHA256)
  • Message encryption (AES-256-CBC + PBKDF2-SHA1)
  • Documentation and examples
  • Blocking client (blocking feature)
  • Integration tests with wiremock
  • Connection pooling and retry configuration

See the open issues for a full list of proposed features and known issues.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

Distributed under the Apache License, Version 2.0. See LICENSE for more information.

Contact

Project Link: https://github.com/android-sms-gateway/client-rs

Acknowledgments