> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazobiamail.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust SDK

> Install wazobiamail from crates.io for an async, strongly typed transactional email client built on reqwest and tokio.

The official Rust SDK is async, strongly typed and entirely safe Rust (`#![forbid(unsafe_code)]`). It provides request builders, typed response models, secret masking and resources for sending, domains, mailboxes, templates, tracking and deliverability.

> [card] [crates.io](https://crates.io/crates/wazobiamail)
>
> `wazobiamail` — version 0.1.0

> [card] [Source](https://github.com/WazobiaMail/wazobiamail-rust)
>
> WazobiaMail/wazobiamail-rust

## At a glance

| | |
| - | - |
| Runtime | Rust 1.75+ |
| Async runtime | tokio |
| HTTP | reqwest with rustls |
| Package | `wazobiamail` |
| Install | `cargo add wazobiamail` |
| Source | [github.com/WazobiaMail/wazobiamail-rust](https://github.com/WazobiaMail/wazobiamail-rust) |

## Install

```bash theme={null}
cargo add wazobiamail
cargo add tokio --features full
```

Or edit `Cargo.toml`:

```toml theme={null}
[dependencies]
wazobiamail = "0.1.0"
tokio = { version = "1", features = ["full"] }
```

## Configure

```rust theme={null}
use wazobiamail::WazobiaMail;

let client = WazobiaMail::new("wzbm_live_...")?;

// Or resolve WAZOBIA_API_KEY / WAZOBIAMAIL_API_KEY:
let client = WazobiaMail::from_env()?;

// Builder form:
let client = WazobiaMail::builder()
    .api_key("wzbm_live_...")
    .timeout(std::time::Duration::from_secs(15))
    .build()?;
```

## Send your first email

```rust theme={null}
use wazobiamail::prelude::*;

#[tokio::main]
async fn main() -> Result<(), WazobiaError> {
    let client = WazobiaMail::new("wzbm_live_...")?;

    let request = SendMessageRequest::builder()
        .from("Acme <hello@mail.example.com>")
        .to("customer@example.com")
        .subject("Your order shipped")
        .html("<p>Your order is on its way.</p>")
        .text("Your order is on its way.")
        .build()?;

    let receipt = client.messages().send(request).await?;
    println!("queued: {}", receipt.data.result.tracking_id);
    Ok(())
}
```

Use `send_with_idempotency(request, "order-1042")` for safe retries.

## What you can do

* `messages()` — send, multipart attachments, tracking, spam checks, email logs.
* `domains()` — list/create/update/delete, DNS records and verification.
* `domains().cloudflare()` — account-level status, connect, sync and disconnect.
* `mailboxes()` — provisioning, credentials, storage and headless inbox.
* `templates()`, `support()`, `billing()`, `units()`, `plans()`, `api_keys()`, `smtp_relays()`, `smtp_access()`, `status()`.

## Errors

`WazobiaError` covers authentication, forbidden/upgrade, not found, conflict, validation, rate limit, server, timeout and transport errors. Match on the variant rather than string-matching messages:

```rust theme={null}
match client.messages().send(request).await {
    Ok(receipt) => println!("{}", receipt.data.result.tracking_id),
    Err(WazobiaError::RateLimit { retry_after, .. }) => {
        eprintln!("retry after {:?}", retry_after);
    }
    Err(error) => return Err(error),
}
```

Check the current enum in `src/errors.rs` before matching optional fields; the crate keeps typed error data where the API supplies it.

## Tokio and concurrency

The client is cheap to clone and holds an `Arc` around configuration and the reqwest client. Reuse one instance across tasks. All operations are `async`, so run them inside a tokio runtime or an async framework.

## Links

* [crates.io](https://crates.io/crates/wazobiamail)
* [GitHub](https://github.com/WazobiaMail/wazobiamail-rust)
* [Full README](https://github.com/WazobiaMail/wazobiamail-rust#readme)
* [All official SDKs](https://docs.wazobiamail.com/docs/guides/sdks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.