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

# Getting Started

> Get started sending transactional emails from Rust with the official Lettr SDK, a type-safe, async-first Tokio interface.

Send transactional emails from your Rust applications using the official Lettr Rust SDK. The SDK provides a type-safe, async-first interface for the Lettr API with full Tokio support and zero-copy deserialization.

Using Cursor? [Jump straight in using this prompt](https://cursor.com/link/prompt?text=Help%20me%20add%20a%20Lettr%20sending%20example%20for%20Rust%20using%20the%20lettr%20crate%2C%20or%20migrate%20my%20current%20Rust%20sending%20solution%20to%20Lettr%20using%20these%20docs%3A%20https%3A%2F%2Fdocs.lettr.com%2Fquickstart%2Frust%2Fquickstart)

## Why Use the Rust SDK?

Rather than making raw HTTP requests, the SDK provides:

* **Type-safe API** — Full type safety with serde-powered serialization
* **Async-first design** — Built on Tokio for non-blocking operations
* **Zero-copy** — Efficient deserialization with minimal allocations
* **Builder pattern** — Fluent API for constructing complex emails
* **Result types** — Idiomatic error handling with Rust's `Result<T, E>`

<Note>
  If you prefer not to use the SDK, you can also send emails via [SMTP](/quickstart/smtp/introduction) or make direct [HTTP API](/api-reference/emails/send-email) calls.
</Note>

## Prerequisites

Before you begin, make sure you have:

<CardGroup cols={2}>
  <Card title="API Key" icon="key" href="https://app.lettr.com/api-keys">
    Create an API key in the Lettr dashboard
  </Card>

  <Card title="Verified Domain" icon="globe" href="/learn/domains/sending-domains">
    Add and verify your sending domain
  </Card>
</CardGroup>

You'll also need:

* **Rust 1.70 or later** installed (via rustup)
* A verified sending domain in your [Lettr dashboard](https://app.lettr.com/domains)

## Quick Setup

Get started in three quick steps: install, configure, and send.

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    cargo add lettr
    cargo add tokio --features macros,rt-multi-thread
    ```

    The SDK requires Tokio as an async runtime. The `macros` feature provides `#[tokio::main]` and the `rt-multi-thread` feature enables the multi-threaded runtime.
  </Step>

  <Step title="Create a client">
    ```rust theme={null}
    use lettr::Lettr;

    #[tokio::main]
    async fn main() -> lettr::Result<()> {
        let client = Lettr::new("your-api-key");

        // Verify the client is configured correctly
        let auth = client.auth_check().await?;
        println!("Connected to Lettr (Team ID: {})", auth.data.team_id);

        Ok(())
    }
    ```

    <Tip>
      Store your API key in environment variables, never hardcode it. API keys use the `lttr_` prefix followed by 64 hexadecimal characters.
    </Tip>
  </Step>

  <Step title="Send your first email">
    ```rust theme={null}
    use lettr::{Lettr, CreateEmailOptions};

    #[tokio::main]
    async fn main() -> lettr::Result<()> {
        let client = Lettr::new("your-api-key");

        let email = CreateEmailOptions::new(
            "sender@yourdomain.com",
            ["recipient@example.com"],
            "Hello from Lettr",
        )
        .with_html("<h1>Hello!</h1><p>This is a test email.</p>");

        let response = client.emails.send(email).await?;
        println!("Email sent! Request ID: {}, Accepted: {}",
            response.request_id, response.accepted);

        Ok(())
    }
    ```

    The response includes a `request_id` for tracking and the number of accepted recipients.
  </Step>
</Steps>

<Warning>
  The sender domain must be verified in your [Lettr dashboard](https://app.lettr.com/domains) before you can send emails. Sending from an unverified domain returns a validation error.
</Warning>

## Configuration

### Environment Variables

Read your API key from an environment variable:

```rust theme={null}
use std::env;
use lettr::Lettr;

#[tokio::main]
async fn main() -> lettr::Result<()> {
    let api_key = env::var("LETTR_API_KEY")
        .expect("LETTR_API_KEY environment variable is required");

    let client = Lettr::new(&api_key);

    Ok(())
}
```

### Using dotenvy

Load environment variables from a `.env` file using the `dotenvy` crate:

```bash theme={null}
cargo add dotenvy
```

Create a `.env` file:

```env theme={null}
LETTR_API_KEY=lttr_your_api_key_here
```

Load it in your application:

```rust theme={null}
use dotenvy::dotenv;
use lettr::Lettr;

#[tokio::main]
async fn main() -> lettr::Result<()> {
    // Load .env file
    dotenv().ok();

    // Read from environment variable
    let api_key = std::env::var("LETTR_API_KEY")
        .expect("LETTR_API_KEY is required");

    let client = Lettr::new(&api_key);

    Ok(())
}
```

<Tip>
  Add `.env` to your `.gitignore` file to prevent accidentally committing your API key to version control.
</Tip>

### Custom HTTP Client

Use a custom reqwest client with custom timeouts or settings:

```rust theme={null}
use lettr::Lettr;
use reqwest::Client;
use std::time::Duration;

#[tokio::main]
async fn main() -> lettr::Result<()> {
    let http_client = Client::builder()
        .timeout(Duration::from_secs(30))
        .build()?;

    let client = Lettr::with_client("your-api-key", http_client);

    Ok(())
}
```

## Sending Emails

### Basic HTML Email

Send a simple HTML email:

```rust theme={null}
use lettr::{Lettr, CreateEmailOptions};

let email = CreateEmailOptions::new(
    "notifications@yourdomain.com",
    ["user@example.com"],
    "Welcome to our service",
)
.with_html("<h1>Welcome!</h1><p>Thanks for signing up.</p>");

let response = client.emails.send(email).await?;
println!("Email sent successfully (Request ID: {})", response.request_id);
```

### With Display Name

Add a friendly display name to the sender address:

```rust theme={null}
let email = CreateEmailOptions::new(
    "notifications@yourdomain.com",
    ["user@example.com"],
    "Welcome to Acme",
)
.with_from_name("Acme Corp")
.with_html("<h1>Hello!</h1>");

client.emails.send(email).await?;
```

### Plain Text Email

Send a plain text email without HTML:

```rust theme={null}
let email = CreateEmailOptions::new(
    "notifications@yourdomain.com",
    ["user@example.com"],
    "Plain text email",
)
.with_text("This is a plain text email.\n\nIt has no HTML formatting.");

client.emails.send(email).await?;
```

### Multipart Emails (HTML + Text)

Send both HTML and plain text versions for maximum compatibility:

```rust theme={null}
let email = CreateEmailOptions::new(
    "notifications@yourdomain.com",
    ["user@example.com"],
    "Multipart email",
)
.with_html("<h1>Hello!</h1><p>This is the HTML version.</p>")
.with_text("Hello!\n\nThis is the plain text version.");

client.emails.send(email).await?;
```

<Tip>
  Providing both HTML and plain text ensures your emails are readable in all email clients, including text-only clients and accessibility tools.
</Tip>

## Explore the SDK

Beyond sending, the SDK manages every Lettr resource:

<CardGroup cols={2}>
  <Card title="Templates" icon="file-code" href="/quickstart/rust/templates">
    Manage Lettr templates and merge tags
  </Card>

  <Card title="Domains" icon="globe" href="/quickstart/rust/domains">
    Add, verify, and manage sending domains
  </Card>

  <Card title="Webhooks" icon="bell" href="/quickstart/rust/webhooks">
    Manage webhook endpoints for delivery and engagement events
  </Card>

  <Card title="Audience" icon="users" href="/quickstart/rust/audience">
    Lists, contacts, topics, properties, and segments
  </Card>

  <Card title="Campaigns" icon="paper-plane" href="/quickstart/rust/campaigns">
    List, send, and schedule campaigns
  </Card>
</CardGroup>

## What's Next

<CardGroup cols={2}>
  <Card title="Advanced Features" icon="rocket" href="/quickstart/rust/advanced">
    Learn about attachments, templates, tracking, and more
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Best Practices" icon="shield-check" href="/knowledge-base/best-practices/deliverability">
    Email deliverability tips
  </Card>
</CardGroup>