VirtualSMS Rust SDK

July 19, 2026 · View on GitHub

What is VirtualSMS?

Official Rust SDK for the VirtualSMS API. VirtualSMS is an account verification platform for individuals, developers, and AI agents: one-time SMS verification, dedicated number rentals, matching-country proxies, and private cloud browser sessions (beta), all behind one API, one MCP server, and one prepaid balance. This crate is a native async Rust client over the REST API, backed by real carrier-issued mobile numbers (real physical SIM cards, not VoIP) across 2500+ services in 145+ countries.

Built for developers and AI agents: REST API, hosted MCP server, SDKs.

This crate is a first-party, idiomatic Rust client for that API directly - it is not a wrapper around any third-party or legacy client library.

Async (Tokio), built on reqwest + serde
Typed errors (virtualsms::Error) mapped from HTTP status codes - no string-matching on error messages
Built-in idempotency keys on every mutating call, and a bounded retry policy for transient failures on reads only (mutating calls are never auto-retried - see Errors below)
Covers activations/orders, rentals (Full Access + Platform tiers), proxies, account, browser sessions (beta), public tools, and webhooks - 46 methods total

Install

cargo add virtualsms

Quickstart

Get an API key at virtualsms.io.
Buy a number for the service you need to verify.
Wait for the code.

use virtualsms::VirtualSms;

#[tokio::main]
async fn main() -> Result<(), virtualsms::Error> {
    let client = VirtualSms::new("YOUR_API_KEY");

    // Buy a number for WhatsApp verification in the UK.
    let order = client.create_order("wa", "GB").await?;
    println!("bought {}", order.phone_number);

    // Block until the SMS arrives (default timeout: 5 minutes).
    let sms = client.wait_for_sms(&order.order_id, None).await?;
    if sms.success {
        println!("code: {:?}", sms.code);
    } else {
        // Never raises on timeout -  returns a result you can retry or cancel.
        client.cancel_order(&order.order_id).await?;
    }

    Ok(())
}

More flows in examples/: activation.rs (SMS verification), rental.rs (SIM rentals), proxy.rs (residential/mobile proxies).

Capabilities

One-time SMS verification. Receive a code for a service like WhatsApp, Telegram, Discord, or a dating app, on demand, from $0.05 per code.
Dedicated number rentals. Hold one number for 1-30 days and receive SMS from any service on that number, from $0.25/day.
Matching-country proxies. Pair a number with an IP from the same country, across 190+ proxy countries, from $1.10/GB.
Private cloud browser sessions (beta). Start a country-matched browser in a live viewer for the signup step itself, invite-only.

Why real SIM cards

VirtualSMS runs on real carrier-issued mobile numbers, backed by real physical SIM cards, not VoIP. Services like WhatsApp, Telegram, Discord, and dating apps run a carrier lookup before they send a code, and VoIP or virtual numbers fail that check more often than a real SIM does. A physical SIM on a real carrier network reads like any other phone on that network, carriers like Vodafone, O2, and T-Mobile depending on the country, which is part of why VirtualSMS holds a 95%+ success rate across 2500+ services in 145+ countries.

Errors

Every fallible call returns virtualsms::Error, with typed variants mapped from HTTP status:

Status	Variant	Notes
401	`BadKey`	Invalid or missing API key
402	`InsufficientBalance`	Top up your balance
403	`Forbidden`	Account not allowlisted for this operation
404 (purchase/rental/proxy-buy)	`NoNumbers`	No stock for that combo right now - try another country/service
404 (other)	`NotFound`	Resource id not found
429	`RateLimited`	Never auto-retried - back off yourself
5xx on a read	`ServerErrorReadOnly`	Already retried up to 3× internally; safe to retry again
5xx on a mutating call	`ServerErrorMutating`	May have already succeeded server-side. Verify with a read call (`list_orders`, `get_order`, `list_rentals`, etc.) before retrying - never blindly retry a purchase/cancel/rotate
-	`CooldownActive`	`cancel_order`/`swap_number` called during the 120s post-purchase cooldown; raised client-side before a network call
-	`SessionsUnavailable`	Browser sessions are invite-only beta

GET requests get a bounded retry (up to 3 attempts, exponential backoff) on network failure or 5xx. Mutating requests (POST/PUT/PATCH/DELETE) are never retried by this client and always carry a fresh X-Idempotency-Key.

Configuration

use std::time::Duration;
use virtualsms::{ClientOptions, VirtualSms};

// Default: base URL https://virtualsms.io/api/v1, 30s timeout.
let client = VirtualSms::new("YOUR_API_KEY");

// Override base URL / timeout (also respects the VIRTUALSMS_BASE_URL env var).
let client = VirtualSms::with_options(
    Some("YOUR_API_KEY".to_string()),
    ClientOptions { base_url: None, timeout: Some(Duration::from_secs(60)) },
);

// Public-only client (no API key) -  authenticated calls return Error::MissingApiKey.
let client = VirtualSms::anonymous();

What this SDK does not do

No register/login - account creation is a web-only flow; this SDK is API-key-based.
No raw wss://.../ws/orders subscription as a standalone method - wait_for_sms polls internally (WebSocket racing is a possible v2.1 addition, not in this baseline).
No release_rental (early release with a partial refund) - gated server-side pending a pricing decision; not exposed here until it ships.
No session-drive methods (navigate/stop/viewer) beyond start_manual_registration_session - those are gated behind a separate beta flag.

v1 → v2 breaking change

v2.0.0 is the first REST-v1-native major release. v1.x wrapped the legacy /stubs/handler_api.php (sms-activate-compatible) dispatcher; v2 talks to /api/v1/* REST endpoints directly and does not use the legacy dispatcher at all. If you're upgrading from v1.x, expect breaking changes across every method signature.

AI agents and MCP

This crate is the API-client half of VirtualSMS: typed methods you call directly from your own Rust code. VirtualSMS also exposes a hosted MCP server, so an AI agent such as Claude or Cursor can request a number, wait for a code, or manage a rental the same way this crate does, without you writing the glue code yourself. See virtualsms.io/docs for MCP server details.

FAQ

What is VirtualSMS?

VirtualSMS is an account verification platform for individuals, developers, and AI agents. It combines one-time SMS verification, dedicated number rentals, matching-country proxies, and private cloud browser sessions behind one API, one MCP server, and one prepaid balance.

Does VirtualSMS use real SIM cards or VoIP numbers?

VirtualSMS uses real carrier-issued mobile numbers, backed by real physical SIM cards, not VoIP. Many services, including WhatsApp, Telegram, Discord, and dating apps, reject VoIP and virtual numbers at signup; a real physical SIM on a real carrier network passes that check far more often, which is reflected in a 95%+ success rate.

Which services and countries does VirtualSMS support?

VirtualSMS covers 2500+ services across 145+ countries for SMS verification and number rentals, plus matching-country proxies across 190+ proxy countries. Coverage spans messaging apps, social platforms, marketplaces, dating apps, and financial services.

VirtualSMS Rust SDK

What is VirtualSMS?

Install

Quickstart

Capabilities

Why real SIM cards

Errors

Configuration

What this SDK does not do

v1 → v2 breaking change

AI agents and MCP

FAQ

What is VirtualSMS?

Does VirtualSMS use real SIM cards or VoIP numbers?

Which services and countries does VirtualSMS support?

Can I rent a number, or only buy one-time codes?

Does VirtualSMS work with AI agents and MCP?

How much does VirtualSMS cost?

Is there a free API key?

Links

License