opensms 0.1.0

Async Rust SDK for the OpenSMS prepaid SMS API (messages, batches, OTP, lookups, contacts, templates, webhooks, numbers, sender IDs, wallet, analytics).
Documentation

opensms (Rust)

Official Rust client for opensms: prepaid SMS for Africa. Send messages and batches, run OTP, look up numbers, manage contacts, templates, webhooks, numbers and sender IDs, and read your wallet and analytics.

Async (built on reqwest and serde, needs a Tokio runtime), edition 2021, four dependencies. One transport layer handles bearer auth, Idempotency-Keys, retries with backoff, and error mapping.

Install

[dependencies]
opensms = "0.1"   # once published; for now: opensms = { path = "../../packages/rust" }
tokio = { version = "1", features = ["full"] }

Not yet published to crates.io. Until then, depend on it by path from elsewhere in this repository, or clone the monorepo and point path at packages/rust.

Usage

use opensms::{Client, SendMessage};

#[tokio::main]
async fn main() -> Result<(), opensms::OpensmsError> {
    let client = Client::new(std::env::var("OPENSMS_API_KEY").unwrap())?;

    let message = client
        .messages()
        .send(&SendMessage::new("+254712345678", "Your order has shipped"))
        .await?;
    println!("{} is {:?}", message.id, message.status);
    Ok(())
}

The key must start with sk_test_ (sandbox) or sk_live_ (live) and have more than 12 characters after the prefix; anything else fails in Client::new with no network call. client.environment() returns "sandbox" or "live". Override the base URL, timeout and retry count with the builder:

use std::time::Duration;
use opensms::Client;

let client = Client::builder("sk_test_...")
    .base_url("https://sandbox.opensms.io")
    .timeout(Duration::from_secs(60))
    .max_retries(4)
    .build()?;
# Ok::<(), opensms::OpensmsError>(())

Request structs use public fields: set the required ones with new(...) or a struct literal and fill the rest with ..Default::default(). Unset optional fields are left out of the request body. Money and prices are decimal strings, timestamps are RFC 3339 strings, and opensms::rfc3339(SystemTime) formats inputs such as scheduled_at.

More

Every resource is an accessor on the client. Methods that send an Idempotency-Key have a _with variant that takes &RequestOptions.

messages

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::{ListMessages, RequestOptions, SendMessage};

let m = client.messages().send(&SendMessage::new("+254712345678", "Your order has shipped")).await?;
client.messages().send_with(
    &SendMessage::new("+254712345678", "Hi"),
    &RequestOptions::idempotency_key("order-1234"),
).await?;
client.messages().list(ListMessages { status: Some("delivered".into()), limit: Some(50), ..Default::default() }).await?;
client.messages().get(&m.id).await?;
client.messages().cancel(&m.id).await?;   // queued or scheduled only, never retried
# Ok(())
# }

batches

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::{BatchItemInput, CreateBatch};

let batch = client.batches().create(&CreateBatch {
    items: vec![BatchItemInput::new("+254712345678", "Hello Ada")],
    dedupe: None,
}).await?;                              // created "ready"; sends nothing until start
client.batches().start(&batch.id).await?;
client.batches().get(&batch.id).await?;
client.batches().stop(&batch.id).await?;
# Ok(())
# }

otp

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::{SendOtp, VerifyOtp};

let sent = client.otp().send(&SendOtp::new("+254712345678")).await?;
let result = client.otp().verify(&VerifyOtp::new(&sent.otp_id, "123456")).await?;
println!("valid={:?}", result.valid);   // verify is never retried
# Ok(())
# }

lookups

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::CreateLookup;

let lookup = client.lookups().create(&CreateLookup { to: "+254712345678".into() }).await?;
client.lookups().get(&lookup.id).await?;
# Ok(())
# }

contacts and contact_groups

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::{CreateContact, CreateContactGroup, ListParams, SendToGroup};

let contact = client.contacts().create(&CreateContact { e164: "+254712345678".into(), ..Default::default() }).await?;
client.contacts().list(ListParams::limit(100)).await?;

let group = client.contact_groups().create(&CreateContactGroup {
    name: "VIP".into(),
    contact_ids: Some(vec![contact.id.clone()]),
}).await?;
client.contact_groups().send(&group.id, &SendToGroup { text: Some("Doors open at 9".into()), ..Default::default() }).await?;
# Ok(())
# }

templates

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::CreateTemplate;

let tpl = client.templates().create(&CreateTemplate {
    name: "welcome".into(),
    body: "Hi {{name}}".into(),
    traffic_type: None,
}).await?;
client.templates().list(Default::default()).await?;
# let _ = tpl;
# Ok(())
# }

webhooks

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::CreateWebhook;

let wh = client.webhooks().create(&CreateWebhook {
    url: "https://example.com/opensms".into(),
    events: vec!["message.delivered".into()],
    enabled: None,
}).await?;
let secret = wh.secret.clone().unwrap();   // whsec_..., shown only once: store it
client.webhooks().test(&wh.id).await?;
# let _ = secret;
# Ok(())
# }

inbound

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::{ListParams, ReplyInbound};

let inbox = client.inbound().list(ListParams::default()).await?;
if let Some(msg) = inbox.items.first() {
    client.inbound().reply(&msg.id, &ReplyInbound { text: "Thanks!".into() }).await?;  // live keys only
}
# Ok(())
# }

numbers

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::NumberQuery;

let query = NumberQuery { country: "KE".into(), kind: "long_code".into() };
client.numbers().available(&query).await?;
let number = client.numbers().assign(&query).await?;   // live keys only, charges the wallet
client.numbers().release(&number.id).await?;
# Ok(())
# }

sender_ids

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::{CheckSenderId, CreateSenderId};

client.sender_ids().check(&CheckSenderId { value: "ACME".into(), country: Some("KE".into()) }).await?;
let sender = client.sender_ids().create(&CreateSenderId {   // never retried: may charge fees
    value: "ACME".into(),
    kind: "alphanumeric".into(),
    countries: vec!["KE".into()],
    documents: vec![],
    ..Default::default()
}).await?;
client.sender_ids().get(&sender.id).await?;
# Ok(())
# }

suppressions

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::CreateSuppression;

let s = client.suppressions().create(&CreateSuppression { e164: "+254712345678".into(), reason: "manual".into() }).await?;
client.suppressions().list(Default::default()).await?;
client.suppressions().delete(s.id).await?;
# Ok(())
# }

compliance

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
client.compliance().get_country("KE").await?;
client.compliance().list_content_rules().await?;
# Ok(())
# }

wallet and pricing

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::PricingParams;

client.wallet().balances().await?;
client.wallet().ledger(Default::default()).await?;   // pages by `before`, not by cursor
client.pricing().get(PricingParams { product: Some("sms".into()), country: Some("KE".into()) }).await?;
# Ok(())
# }

analytics and sandbox

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::AnalyticsQuery;

client.analytics().overview(AnalyticsQuery { range: Some("7d".into()), ..Default::default() }).await?;
client.sandbox().list_messages(Default::default()).await?;   // sandbox keys: rendered text, OTP codes included
# Ok(())
# }

countries

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
client.countries().list().await?;
client.countries().carriers("KE").await?;
# Ok(())
# }

pagination

Cursor lists return Page<T> with items and next_cursor. client.paginate walks every page lazily:

# async fn demo(client: &opensms::Client) -> Result<(), opensms::OpensmsError> {
use opensms::ListMessages;

let mut it = client.paginate(|cursor| {
    client.messages().list(ListMessages { limit: Some(100), cursor, ..Default::default() })
});
while let Some(message) = it.next().await {
    println!("{}", message?.id);
}
# Ok(())
# }

Bare-array endpoints (messages().attempts, numbers().available, compliance(), countries(), the analytics breakdowns) return a plain Vec<T>, and wallet().ledger pages by before instead of a cursor.

Errors and retries

Every method returns Result<T, OpensmsError>. The error carries the RFC 9457 problem fields and the useful headers:

Field Meaning
status HTTP status; 0 means no HTTP response (network failure or timeout)
type, title, detail problem body fields
code machine code, absent on most errors
trace_id, errors optional trace id and field errors
request_id X-Request-ID, set on message and OTP admission rejections
retry_after Retry-After in seconds, when the server sent one
body raw decoded body (text wrapped as a JSON string when it was not JSON)
# async fn demo(client: &opensms::Client) {
use opensms::SendMessage;

match client.messages().send(&SendMessage::new("+254712345678", "hi")).await {
    Ok(m) => println!("sent {}", m.id),
    Err(e) if e.status == 422 => eprintln!("rejected: {} (request {:?})", e.message, e.request_id),
    Err(e) if e.status == 429 => eprintln!("rate limited, retry in {:?} s", e.retry_after),
    Err(e) => eprintln!("error {}: {}", e.status, e.message),
}
# }

Branch on status, not code: most validation errors have no code, and insufficient scope is 401 on messages and otp but 403 everywhere else.

Retries, up to max_retries (default 2, so 3 attempts):

  • Retried on 429, 500, 502, 503, 504, network errors and timeouts.
  • GET, PUT, PATCH and DELETE are always retryable. A POST is retried only when it carries an Idempotency-Key; the SDK generates a UUIDv4 per call and reuses it unchanged on every retry, so a retried send is never duplicated.
  • Never retried: messages().cancel, otp().verify, sender_ids().create, sender_ids().create_draft, suppressions().create, suppressions().import, and any other 4xx.
  • Retry-After (seconds or an HTTP date) is honoured. If it asks for more than 60 s the call fails at once with retry_after set instead of waiting. Otherwise the delay is exponential backoff with full jitter, capped at 8 s: random(0, min(8 s, 0.5 s * 2^(n-1))).

Webhooks

Deliveries carry X-OpenSMS-Signature: t=<unix>,v1=<hex>. Verify the exact raw body bytes before parsing, with the full whsec_... secret. No client or API key is needed:

use opensms::webhook::{construct_event, verify_signature, VerifyOptions, SIGNATURE_HEADER};

fn handle(raw_body: &[u8], signature_header: &str, secret: &str) -> Result<(), opensms::OpensmsError> {
    if !verify_signature(raw_body, signature_header, secret, VerifyOptions::default()) {
        return Ok(()); // reply 400
    }
    // Or verify and parse in one step; fails with code "invalid_signature" or "expired_signature".
    let event = construct_event(raw_body, signature_header, secret, VerifyOptions::default())?;
    println!("{} {:?}", SIGNATURE_HEADER, event.r#type);
    Ok(())
}

The default tolerance is 300 s (VerifyOptions). The same functions are available as client.webhooks().verify_signature(...) and client.webhooks().construct_event(...).

Testing

cargo test                              # unit tests: mock transport, offline
cargo test --test live -- --nocapture   # live conformance scenario

The live suite runs against a sandbox and is skipped unless OPENSMS_BASE_URL and OPENSMS_API_KEY are set. See the monorepo README and spec/SURFACE.md for the full API surface this SDK implements.

License

MIT