Unimatrix Rust SDK

The Unimatrix Rust SDK provides convenient access to integrate communication capabilities into your Rust applications using the Unimatrix HTTP API. The SDK provides support for sending SMS and 2FA verification.

Getting started

Before you begin, you need an Unimatrix account. If you don't have one yet, you can sign up for an Unimatrix account and get free credits to get you started.

Documentation

Check out the documentation at unimtx.com/docs for a quick overview.

Installation

The SDK uses an asynchronous client by default. Add uni-sdk and an async runtime to your Cargo.toml:

[dependencies]
uni-sdk = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

To use the synchronous client, enable the blocking feature. An async runtime is not required by the application:

[dependencies]
uni-sdk = { version = "0.3", features = ["blocking"] }

The SDK requires Rust 1.86 or later.

Usage

The following examples show how to use the Unimatrix Rust SDK to interact with Unimatrix services.

Initialize a client

use uni_sdk::UniClient;

fn main() -> uni_sdk::Result<()> {
    let client = UniClient::new(
        "your access key id",
        "your access key secret",
    )?;

    Ok(())
}

Or configure your credentials using environment variables:

export UNIMTX_ACCESS_KEY_ID=your_access_key_id
export UNIMTX_ACCESS_KEY_SECRET=your_access_key_secret

use uni_sdk::UniClient;

fn main() -> uni_sdk::Result<()> {
    let client = UniClient::from_env()?;

    Ok(())
}

Send SMS

Send a text message to a single recipient.

use uni_sdk::{SendMessageRequest, UniClient};

#[tokio::main]
async fn main() -> uni_sdk::Result<()> {
    let client = UniClient::from_env()?;
    let response = client
        .messages()
        .send(&SendMessageRequest::text(
            "+1206880xxxx", // in E.164 format
            "Your verification code is 2048.",
        ))
        .await?;

    println!("{:#?}", response.data);
    Ok(())
}

Send verification code

Send a one-time passcode (OTP) to a recipient. The following example sends an automatically generated verification code.

use uni_sdk::{SendOtpRequest, UniClient};

#[tokio::main]
async fn main() -> uni_sdk::Result<()> {
    let client = UniClient::from_env()?;
    let response = client
        .otp()
        .send(&SendOtpRequest::new("+1206880xxxx"))
        .await?;

    println!("{:#?}", response.data);
    Ok(())
}

Check verification code

Verify the one-time passcode that a user provided.

use uni_sdk::{UniClient, VerifyOtpRequest};

#[tokio::main]
async fn main() -> uni_sdk::Result<()> {
    let client = UniClient::from_env()?;
    let response = client
        .otp()
        .verify(&VerifyOtpRequest::new(
            "+1206880xxxx",
            "123456", // the code the user provided
        ))
        .await?;

    println!("{}", response.into_data()?.valid);
    Ok(())
}

Handle errors

API errors include the error code, HTTP status, and request ID.

use uni_sdk::{SendOtpRequest, UniClient};

#[tokio::main]
async fn main() -> uni_sdk::Result<()> {
    let client = UniClient::from_env()?;

    if let Err(error) = client.otp().send(&SendOtpRequest::new("invalid")).await {
        eprintln!("{}", error);
        eprintln!("request ID: {:?}", error.request_id());
    }

    Ok(())
}

Synchronous (non-async) client

Use uni_sdk::blocking::UniClient when your application does not use an async runtime. Its API mirrors the async client but does not require .await. Avoid calling the blocking client directly from an async task, because it blocks that task's executor thread.

use uni_sdk::{blocking::UniClient, SendMessageRequest};

fn main() -> uni_sdk::Result<()> {
    let client = UniClient::from_env()?;
    let response = client.messages().send(&SendMessageRequest::text(
        "+1206880xxxx",
        "Your verification code is 2048.",
    ))?;

    println!("{:#?}", response.data);
    Ok(())
}

Reference

Other Unimatrix SDKs

To find Unimatrix SDKs in other programming languages, check out the list below:

License

This library is released under the MIT License.

uni-sdk 0.3.0