Receive email in real time with Rust

Receive email in Rust with a signed JSON webhook: install the SDK, run a receiver, configure a MailKite address, and test delivery. Here, live means event-driven delivery after the email arrives, with normal SMTP and forwarding delays; it does not promise an exact latency.

1. Prepare a receiving address

In MailKite, add a domain or claim an available hosted subdomain. Complete the verification shown in the dashboard before receiving. For your own domain, publish the exact MX record MailKite returns. Choose an address such as inbound@your-receiving-domain.

For a detailed setup walkthrough, use the quickstart and domain verification docs. Your HTTP receiver needs a public HTTPS URL; a development tunnel can expose local port 3000 during testing.

The shared demo repository contains the exact receiver sources, local checks and inbox inspector used by this series.

2. Configure the webhook and run the Rust receiver

Create a webhook route matching your receiving address and point it to https://your-app.example/hooks/mailkite, replacing the example host with your public HTTPS host. Copy that route's signing secret into the receiver's environment. Avoid a catch-all route if you only want mail for one address.

A current Rust toolchain. Save the receiver as src/main.rs in the inbound project. Set MAILKITE_WEBHOOK_SECRET to the signing secret for your configured MailKite webhook, supplied through your environment or secret manager. You do not need an API key for local signature verification.

cargo new inbound
cd inbound
cargo add mailkite axum serde_json
cargo add tokio --features macros,rt-multi-thread,net

Axum's Bytes extractor preserves the signed body. Convert it to UTF-8 once, verify it, then call serde_json. Configure the framework's body limit for the largest event you accept; do not raise it without considering memory use.

// Docs: docs/website/content/live-receiving-email-series.md
use axum::{body::Bytes, http::{header, HeaderMap, StatusCode}, response::{IntoResponse, Response}, routing::post, Router};
use serde_json::Value;

async fn receive(headers: HeaderMap, body: Bytes) -> Response {
    let signature = headers.get("x-mailkite-signature").and_then(|v| v.to_str().ok()).unwrap_or("");
    let raw = match std::str::from_utf8(&body) { Ok(raw) => raw, Err(_) => return StatusCode::BAD_REQUEST.into_response() };
    let secret = std::env::var("MAILKITE_WEBHOOK_SECRET").expect("Set MAILKITE_WEBHOOK_SECRET");
    if !mailkite::verify_webhook(signature, raw, &secret) { return StatusCode::UNAUTHORIZED.into_response(); }
    let event: Value = match serde_json::from_str(raw) { Ok(v) => v, Err(_) => return StatusCode::BAD_REQUEST.into_response() };
    let kind = match event.get("type").and_then(Value::as_str) {
        Some(kind) if !kind.trim().is_empty() => kind,
        _ => return StatusCode::BAD_REQUEST.into_response(),
    };
    if kind == "email.received" {
        let id = match event.get("id").and_then(Value::as_str) {
            Some(id) if !id.trim().is_empty() => id,
            _ => return StatusCode::BAD_REQUEST.into_response(),
        };
        println!("received {id}");
    }
    // Demonstration only: persist/enqueue and deduplicate before production acknowledgement.
    ([(header::CONTENT_TYPE, "application/json")], mailkite::reply_ok()).into_response()
}

#[tokio::main]
async fn main() {
    let secret = std::env::var("MAILKITE_WEBHOOK_SECRET").expect("Set MAILKITE_WEBHOOK_SECRET");
    assert!(!secret.trim().is_empty(), "Set MAILKITE_WEBHOOK_SECRET");
    let port = std::env::var("PORT").unwrap_or_else(|_| "3000".into());
    let listener = tokio::net::TcpListener::bind(format!("127.0.0.1:{port}")).await.unwrap();
    axum::serve(listener, Router::new().route("/hooks/mailkite", post(receive))).await.unwrap();
}

Download the exact receiver shown above. Save it beside its dependencies, then start it with the environment variable already set:

cargo run

This is a verification-and-logging demonstration, not a durable inbox. Before production, insert the event into a database or durable queue using its id as a unique key, and only then acknowledge it. Logging followed by a 200 response can lose work if the process stops.

3. Test the exact receiver and address

Download the local signed test and run it with Node.js and the same webhook secret. It creates synthetic HTTP requests only, including a duplicate id and a tampered body; it sends no email. The first two requests should return the SDK's JSON acknowledgement, and the tampered one should return 401.

node check.mjs http://127.0.0.1:3000/hooks/mailkite

Then send a real message to the exact receiving address to test routing. The dashboard's domain-webhook test uses a catch-all route; it does not test an exact-address route. See signature verification and delivery and retries.

4. Check a real message and its payload

Send a new message to the MailKite receiving address. Confirm delivery in MailKite and receipt at the endpoint. The JSON event has type: "email.received", a stable id, sender and recipient address objects, decoded bodies, attachment metadata and authentication results.

• Body: use text, falling back to textFromHtml when the plain-text part is null.
• Attachments: process the signed download URLs after durable acceptance, before they expire.
• Authentication: the webhook signature authenticates MailKite's delivery. It does not prove the original sender is trustworthy. Forwarding can change email-authentication results.
• Retries: replay a delivery and confirm your production handler does not create a second job for the same message id.

Troubleshoot the delivery boundary

Continue with the complete event reference, other receiving guides or the companion implementation article.