VibeMail SDK for Rust
Official SDK for the VibeMail transactional email API.
Send an email
use ;
async
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.await?;
for entry in &res.data
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.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
.await?;
client.cancel.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.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 ;
let domain = client.create_domain.await?;
for in domain.dns_records.unwrap_or_default
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.await?;
println!;
Listing is paged. total counts every domain on the account, not just the page you asked for:
let page = client.domains.await?;
println!;
client.delete_domain.await?;
Removing a domain does not affect mail already sent from it.
Contacts
client
.create_contact
.await?;
let page = client
.contacts
.await?;
client.delete_contact.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.await?;
for entry in page.data
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>:
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 = Vecnew;
let mut offset = 0;
loop
Errors
match client.send.await
| 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 = new
.with_base_url
.with_max_retries
.with_http_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