Expand description
The official Rust SDK for Mailtea — a thin, typed wrapper over the REST API.
use mailtea::{Mailtea, SendEmail};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Reads MAILTEA_API_KEY, and MAILTEA_API_BASE_URL when it is set.
let mailtea = Mailtea::from_env()?;
let sent = mailtea
.emails
.send(
&SendEmail::new(
"you@yourdomain.com",
["recipient@example.com"],
"Hello from Mailtea",
)
.html("<p>Your first email, sent with <strong>Mailtea</strong>.</p>"),
)
.await?;
let email = mailtea.emails.get(&sent.id).await?;
println!("{} {:?}", email.id, email.status);
Ok(())
}§Payloads
Every method takes impl Serialize, so a payload can be a typed request
struct (SendEmail, CreateContact, CreatePost, CreateTopic,
SendTestPost, UploadAsset, …), a serde_json::json!({...}) literal,
or any struct of your own. Pass () where a method takes parameters you do
not need.
Responses are typed on the transactional email path (SentEmail,
Email, BatchSent) and serde_json::Value elsewhere. To deserialize
any endpoint into your own type, call Mailtea::request.
§Errors
Every call returns Result<T>, whose error is Error — one struct
carrying the HTTP status, the API’s message, its code and details
when present, and the x-request-id. A status of 0 means the request
never reached the API, so nothing was sent.
§Webhooks
verify_webhook_signature checks a Standard Webhooks delivery and rejects
replays; sign_webhook produces the same header for tests.
Structs§
- ApiKeys
- The
api_keysresource. Reached throughMailtea::api_keys. - Assets
- The
assetsresource (a publication’s image library). Reached throughMailtea::assets. - Attachment
- A file to attach.
contentis base64 —Attachment::from_bytesdoes the encoding for you. - Automation
Runs - The
automation_runsresource (one contact’s journey through one automation). Reached throughMailtea::automation_runs. - Automations
- The
automationsresource (multi-step contact journeys). Reached throughMailtea::automations. - Batch
Sent - What
Emails::batchreturns: one id per message, in the order sent. - Contact
Properties - The
contact_propertiesresource (custom contact fields). Reached throughMailtea::contact_properties. - Contacts
- The
contactsresource. Reached throughMailtea::contacts. - Create
Contact - The payload for
Contacts::create/Contacts::upsert. - Create
Post - The payload for
Posts::create. - Create
Topic - The payload for
Topics::create. - Domain
Claims - Domain claims — take a domain back from whichever publication currently
holds it. Reached through
Mailtea::domains.claims. - Domains
- The
domainsresource (email and site sending domains). Reached throughMailtea::domains. - A stored email. Unknown fields land in
extrarather than failing the deserialize, so a field added server-side will not break this. - Emails
- The
emailsresource. Reached throughMailtea::emails. - Error
- Something went wrong: the API refused the request, or the client could not make it in the first place.
- Event
Definitions - The
event_definitionsresource (the catalog of event names a publication expects, with optional property schemas). Reached throughMailtea::event_definitions. - Events
- The
eventsresource (custom product events that trigger automations and resumewait_for_eventsteps). Reached throughMailtea::events. - Http
Request - One outgoing request, already fully addressed and authorized.
- Http
Response - One answer. The body is kept as text: an error response carries JSON the caller needs to see, and deserializing straight into the success type would throw it away.
- Inbound
Attachments - Attachments on a received email. Each carries a short-lived signed
download_url. - Inbound
Emails - Inbound (received) emails. Reached through
Mailtea::emails.inbound. - Mailtea
- The Mailtea client.
- Mailtea
Builder - Builds a
Mailteawith a base URL or a transport of your own. - Posts
- The
postsresource (newsletter posts and broadcasts). Reached throughMailtea::posts. - Reqwest
Transport - The default transport:
reqwestover rustls. - Segments
- The
segmentsresource. Reached throughMailtea::segments. - Send
Email - A message to send.
- Send
Post - The payload for
Posts::send: schedule it, or send now with(). - Send
Test Post - The payload for
Posts::send_test. - Senders
- The
sendersresource (named From identities). Reached throughMailtea::senders. - Sent
Email - What a send returns: the id to look the email up by.
- Suppressions
- The
suppressionsresource (the org-wide do-not-send list). Reached throughMailtea::suppressions. - Tag
- An arbitrary label carried with the send and echoed back on its events.
- Template
Ref - A reference to a published server template, plus the variables to render it with.
- Templates
- The
templatesresource (reusable server-side email templates). Reached throughMailtea::templates. - Topics
- The
topicsresource (topic definitions). Reached throughMailtea::topics. - Tracking
Domains - Tracking sub-domains (CNAME) under a domain — used to serve the open pixel
and click-tracking links from your own domain. Reached through
Mailtea::domains.tracking. - Update
Contact - The payload for
Contacts::update. - Upload
Asset - The payload for
Assets::upload.contentis base64 —UploadAsset::from_bytesdoes the encoding for you. - Verify
Options - How verification is tuned.
Defaultis the 5-minute tolerance against the real clock. - Webhooks
- The
webhooksresource (outbound event subscriptions). Reached throughMailtea::webhooks.
Constants§
- DEFAULT_
BASE_ URL - Production API. Override it for local dev or a self-hosted Mailtea.
- DEFAULT_
TOLERANCE_ SECONDS - Allowed clock skew each way, in seconds. Five minutes, the Standard Webhooks default.
- VERSION
- The crate version, sent as the
User-Agenton every request.
Traits§
- Into
Unix Seconds - Anything a
webhook-timestampcan arrive as. A header is a string; a test usually has an integer. - Transport
- How a request actually goes out. Implement it to test without a network, to add retries or tracing, or to route through your own HTTP stack.
Functions§
- sign_
webhook - Sign a webhook payload.
- verify_
webhook_ signature - Verify a
webhook-signatureheader against the expected HMAC, with the default 5-minute replay window. - verify_
webhook_ signature_ with verify_webhook_signaturewith the tolerance and clock under your control.