vibemail 1.2.0

Official VibeMail SDK for transactional email
Documentation

VibeMail SDK for Rust

Official SDK for the VibeMail transactional email API.

cargo add vibemail

Send an email

use vibemail::{SendRequest, VibeMail};

#[tokio::main]
async fn main() -> Result<(), vibemail::Error> {
    let client = VibeMail::new(std::env::var("VIBEMAIL_API_KEY").unwrap());

    let sent = client
        .send(
            SendRequest::new("ada@example.com")
                .from("hello@yourdomain.com")
                .subject("Welcome")
                .html("<p>Glad you're here.</p>")
                .text("Glad you're here."),
        )
        .await?;

    println!("{} {}", sent.id, sent.status);
    Ok(())
}

send returns once the API has accepted the message, not once it has been delivered. Use get to follow it.

Always send text alongside html. Mail with no plain-text part is measurably more likely to be spam-foldered.

Recipients

One message goes to one recipient. To reach several people, use batch, it sends a separate message to each, which is also what stops your recipients from seeing one another's addresses:

let res = client.batch(vec![
    SendRequest::new("ada@example.com").subject("Welcome").text("Hi Ada"),
    SendRequest::new("alan@example.com").subject("Welcome").text("Hi Alan"),
]).await?;

for entry in &res.data {
    if let Some(err) = &entry.error {
        eprintln!("rejected: {err}");
    }
}

Each entry succeeds or fails on its own. A comma-joined to returns Error::InvalidRecipient before anything reaches the network, rather than delivering to just one of the addresses.

Retries and idempotency

Use send_idempotent for anything you might retry. A repeat carrying the same key returns the original result instead of sending a second copy, which matters because a client that times out has no way of knowing whether the message went out.

client.send_idempotent(request, format!("receipt-{order_id}")).await?;

The client retries 429 and 5xx on its own (twice by default, honouring Retry-After) and never retries a request the server rejected on its merits. Use .with_max_retries(0) to handle that yourself.

Scheduling

let sent = client
    .send(
        SendRequest::new("ada@example.com")
            .subject("Reminder")
            .text("Standup in 15 minutes.")
            .scheduled_at("in 2 hours"),   // or an RFC 3339 timestamp
    )
    .await?;

client.cancel(&sent.id).await?;            // while it is still scheduled

Up to 30 days ahead. Once the dispatcher has claimed a message it is on its way out and can no longer be withdrawn.

Templates

let templates = client.templates().await?;

client.send(
    SendRequest::new("ada@example.com")
        .template("welcome")
        .variable("name", "Ada"),
).await?;

Anything you set explicitly - subject, html, text, overrides the stored template.

Domains

Mail sent from your own domain needs that domain added and verified. Adding one returns the DNS records to publish; it stays unverified until they resolve.

use vibemail::{ListOptions, VibeMail};

let domain = client.create_domain("yourdomain.com").await?;

for (purpose, record) in domain.dns_records.unwrap_or_default() {
    println!("{purpose} {} {} {}", record.r#type, record.host, record.value);
}

dns_records is keyed by purpose, not a list: verification, mx, spf and dmarc. Each carries type, host, value, and priority where the type takes one. Publish all four; the domain verifies once they resolve.

Come back for the same records at any time, along with whether verification has gone through:

let d = client.domain(&domain.id.to_string()).await?;
println!("verified: {}", d.is_verified);

Listing is paged. total counts every domain on the account, not just the page you asked for:

let page = client.domains(ListOptions::new().limit(25)).await?;
println!("{} of {}", page.data.len(), page.total);

client.delete_domain("7").await?;

Removing a domain does not affect mail already sent from it.

Contacts

client
    .create_contact("ada@example.com", Some("Ada Lovelace"), Some("met at a talk"))
    .await?;

let page = client
    .contacts(ListOptions::new().search("ada").limit(50))
    .await?;

client.delete_contact(&page.data[0].id.to_string()).await?;

search matches against address and name. None for name or notes leaves the field off the wire entirely.

Suppressions

Addresses that will not be sent to: hard bounces, spam complaints, and anything blocked by hand. A send to a suppressed address is dropped rather than attempted, which is what keeps a bad list from taking your sending reputation with it.

let page = client.suppressions(ListOptions::new().limit(100)).await?;

for entry in page.data {
    println!("{} {}", entry.email, entry.reason.unwrap_or_default());
}

reason is free text, not a fixed set: manual for anything added by hand or through the API, and hard bounce: ... carrying the remote server's own wording when the queue gave up on an address.

Paging

domains, contacts and suppressions all return Page<T>:

pub struct Page<T> {
    pub object: String,
    pub total: i64,
    pub limit: i64,
    pub offset: i64,
    pub data: Vec<T>,
}

limit defaults to 50 and is capped at 100. ListOptions::new() sends no query at all and takes the server defaults. Walk the whole set by stepping offset until you have total:

let mut all = Vec::new();
let mut offset = 0;
loop {
    let page = client
        .contacts(ListOptions::new().limit(100).offset(offset))
        .await?;
    let total = page.total;
    all.extend(page.data);
    if all.len() as i64 >= total {
        break;
    }
    offset += 100;
}

Errors

match client.send(SendRequest::new("ada@example.com").subject("Hi")).await {
    Ok(sent) => println!("{}", sent.id),
    Err(err) => {
        if let Some(status) = err.status() {
            eprintln!("api said {status}");
        }
        if err.is_retryable() {
            // 429 or 5xx, already retried up to `with_max_retries`
        }
    }
}
Status Means
400 The request was malformed, such as a domain that is not a domain.
401 The API key is missing, wrong, or revoked.
402 A plan limit was reached. Not retried.
404 No such record, or not yours.
409 Already exists, such as a domain someone has registered.
422 Required fields missing, or a schedule more than 30 days out.
429 Rate limited. Retried automatically, honouring Retry-After.
5xx Our fault. Retried automatically.

Validation that can be caught without a round trip, such as a SendRequest with several recipients, fails before the request is made.

Configuration

let client = VibeMail::new("vm_live_...")
    .with_base_url("https://vibemail.ai")
    .with_max_retries(2)
    .with_http_client(my_reqwest_client);

VibeMail::new panics on an empty key; try_new returns a Result instead. Cloning a client is cheap: the connection pool is shared.

API

send(request) Send one message.
send_idempotent(request, key) Send with an idempotency key.
batch(requests) Send many, one recipient each.
get(id) Status of a send.
cancel(id) Withdraw a scheduled send.
templates() Stored templates.
domains(opts) A page of sending domains.
domain(id) One domain, with the records that verify it.
create_domain(domain) Add a domain.
delete_domain(id) Remove a domain.
contacts(opts) A page of contacts.
create_contact(email, name, notes) Store a contact.
delete_contact(id) Forget a contact.
suppressions(opts) Addresses that will not be sent to.

SendRequest builders

new(to) Recipient. One per message; use batch() for many.
from(address) Sender. Must be an address your account owns.
subject(s)
text(s) Plain-text body. Always send one alongside html.
html(s) HTML body.
template(name) Name or id of a stored template.
variable(key, value) One substitution; call repeatedly.
tags(iter) Labels carried through to analytics.
track_opens(bool) Tracking pixel on HTML sends. Defaults to on.
track_clicks(bool) Link rewriting. Defaults to on.
scheduled_at(when) ISO 8601 or a relative offset like "in 2 hours". Up to 30 days.

Not in the SDK yet

Webhooks and analytics are served by the API but are not wrapped here. They will be added when the shapes settle; until then reach them with reqwest and the same bearer token.

License

MIT