📱 SMSGate Rust Client

An async-first Rust client for the SMSGate API: send and track SMS messages through your Android devices with full type safety, JWT or Basic authentication, and optional encryption. Built on tokio, reqwest, and serde with rustls by default. See the client libraries overview for the full ecosystem.

📖 About

android-sms-gateway is a typed Rust crate for the SMSGate 3rd-party API. It covers messages, inbox, devices, settings, webhooks, health, logs, and the JWT token lifecycle with comprehensive client-side validation, plus webhook payload signature verification (HMAC-SHA256) and optional end-to-end encryption (AES-256-CBC + PBKDF2) behind feature flags. Async-only with tokio.

📚 Table of Contents

• 📱 SMSGate Rust Client
  • 📖 About
  • 📚 Table of Contents
  • ⭐ Features
  • 📦 Installation
  • 🔑 Authentication
    • Basic Authentication
    • JWT Authentication
  • 🚀 Quickstart
  • 💻 Usage
  • 📖 API Reference
  • 🤝 Contributing
  • 📄 License

⭐ Features

• Async-first with tokio and reqwest
• Basic and JWT authentication; token generate, refresh, and revoke
• Full API coverage: messages, inbox, devices, settings, webhooks, health, logs
• Webhook payload signature verification (HMAC-SHA256)
• End-to-end encryption (AES-256-CBC + PBKDF2) behind the encryption feature
• rustls TLS by default, no OpenSSL dependency (native-tls feature available)
• Comprehensive client-side validation and typed domain models

📦 Installation

cargo add android-sms-gateway

Optional: cargo add android-sms-gateway --features encryption to enable message encryption. TLS backend defaults to rustls-tls; switch with the native-tls feature.

🔑 Authentication

Two methods are supported: Basic authentication with account credentials, and JWT bearer tokens with scoped permissions. JWT is recommended for production.

Basic Authentication

let client = Client::new(
    ClientConfig::new().with_basic_auth("your_login", "your_password"),
)?;

JWT Authentication

use android_sms_gateway::{
    Client, ClientConfig,
    types::{JwtScope, TokenRequest},
};

// Create a client with Basic auth to generate a token
let client = Client::new(
    ClientConfig::new().with_basic_auth("your_login", "your_password"),
)?;

let token = client.generate_token(&TokenRequest {
    scopes: vec![JwtScope::new(JwtScope::MESSAGES_SEND), JwtScope::new(JwtScope::MESSAGES_READ)],
    ttl: Some(3600),
}).await?;

// Use the generated token for subsequent requests
let jwt_client = Client::new(ClientConfig::new().with_token(token.access_token))?;

🚀 Quickstart

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 message = Message {
        phone_numbers: vec!["+12025550123".into()],
        text_message: Some(TextMessage { text: "Hello from Rust".into() }),
        ..Default::default()
    };
    let state = client.send(&message, &SendOptions::new()).await?;
    println!("Message ID: {}", state.id);
    Ok(())
}

💻 Usage

Beyond sending, the client covers message listing and cancellation, inbox listing and refresh, device management, settings, webhooks, logs, and the token lifecycle. See src/client.rs for the complete method list with signatures and src/types for the domain models. Webhook signature verification lives in src/webhook.rs, encryption in src/encryption.rs.

📖 API Reference

• Official API Reference - endpoints, payloads, and error codes
• Authentication Guide - scopes and token management
• Client libraries overview
• Client source - full method reference and examples

🤝 Contributing

Contributions are welcome. Open an issue to discuss major changes before submitting a pull request; PRs target the master branch.

📄 License

Distributed under the Apache License 2.0. See LICENSE.