Skip to main content

Crate mailtea

Crate mailtea 

Source
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_keys resource. Reached through Mailtea::api_keys.
Assets
The assets resource (a publication’s image library). Reached through Mailtea::assets.
Attachment
A file to attach. content is base64 — Attachment::from_bytes does the encoding for you.
AutomationRuns
The automation_runs resource (one contact’s journey through one automation). Reached through Mailtea::automation_runs.
Automations
The automations resource (multi-step contact journeys). Reached through Mailtea::automations.
BatchSent
What Emails::batch returns: one id per message, in the order sent.
ContactProperties
The contact_properties resource (custom contact fields). Reached through Mailtea::contact_properties.
Contacts
The contacts resource. Reached through Mailtea::contacts.
CreateContact
The payload for Contacts::create / Contacts::upsert.
CreatePost
The payload for Posts::create.
CreateTopic
The payload for Topics::create.
DomainClaims
Domain claims — take a domain back from whichever publication currently holds it. Reached through Mailtea::domains.claims.
Domains
The domains resource (email and site sending domains). Reached through Mailtea::domains.
Email
A stored email. Unknown fields land in extra rather than failing the deserialize, so a field added server-side will not break this.
Emails
The emails resource. Reached through Mailtea::emails.
Error
Something went wrong: the API refused the request, or the client could not make it in the first place.
EventDefinitions
The event_definitions resource (the catalog of event names a publication expects, with optional property schemas). Reached through Mailtea::event_definitions.
Events
The events resource (custom product events that trigger automations and resume wait_for_event steps). Reached through Mailtea::events.
HttpRequest
One outgoing request, already fully addressed and authorized.
HttpResponse
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.
InboundAttachments
Attachments on a received email. Each carries a short-lived signed download_url.
InboundEmails
Inbound (received) emails. Reached through Mailtea::emails.inbound.
Mailtea
The Mailtea client.
MailteaBuilder
Builds a Mailtea with a base URL or a transport of your own.
Posts
The posts resource (newsletter posts and broadcasts). Reached through Mailtea::posts.
ReqwestTransport
The default transport: reqwest over rustls.
Segments
The segments resource. Reached through Mailtea::segments.
SendEmail
A message to send.
SendPost
The payload for Posts::send: schedule it, or send now with ().
SendTestPost
The payload for Posts::send_test.
Senders
The senders resource (named From identities). Reached through Mailtea::senders.
SentEmail
What a send returns: the id to look the email up by.
Suppressions
The suppressions resource (the org-wide do-not-send list). Reached through Mailtea::suppressions.
Tag
An arbitrary label carried with the send and echoed back on its events.
TemplateRef
A reference to a published server template, plus the variables to render it with.
Templates
The templates resource (reusable server-side email templates). Reached through Mailtea::templates.
Topics
The topics resource (topic definitions). Reached through Mailtea::topics.
TrackingDomains
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.
UpdateContact
The payload for Contacts::update.
UploadAsset
The payload for Assets::upload. content is base64 — UploadAsset::from_bytes does the encoding for you.
VerifyOptions
How verification is tuned. Default is the 5-minute tolerance against the real clock.
Webhooks
The webhooks resource (outbound event subscriptions). Reached through Mailtea::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-Agent on every request.

Traits§

IntoUnixSeconds
Anything a webhook-timestamp can 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-signature header against the expected HMAC, with the default 5-minute replay window.
verify_webhook_signature_with
verify_webhook_signature with the tolerance and clock under your control.

Type Aliases§

BoxFuture
A boxed future, because a trait with async fn cannot be used as dyn Transport and an injectable transport has to be a trait object.
Result
The result of every SDK call.