guerrillamail-client

An async Rust client for the GuerrillaMail temporary email service.

This crate lets you programmatically create disposable email addresses, poll inboxes, and fetch message contents using an idiomatic async Rust API built on tokio and reqwest.

⚠️ Unofficial API
GuerrillaMail does not provide a documented public API. This client reverse-engineers the web interface and may break if GuerrillaMail changes their frontend behavior.

When to use this

• Email-based testing (signups, verification emails, password resets)
• Automation and scraping workflows
• CI / integration tests that need a disposable inbox
• Security research and tooling

Not recommended for long-lived accounts or reliability-critical workflows.

Features

• 🚀 Async/await first — built on tokio and reqwest
• 📧 Create temporary email addresses
• 📬 Poll inbox messages
• 📄 Fetch full email contents
• 🗑️ Forget/delete addresses
• 🌐 Proxy support (e.g. Burp, mitmproxy)
• 🛠️ Configurable TLS + User-Agent
• 📚 Well-typed errors with proper chaining

Installation

Add to your Cargo.toml:

[dependencies]
guerrillamail-client = "0.5.0"
tokio = { version = "1", features = ["full"] }

Quick start

use guerrillamail_client::Client;

#[tokio::main]
async fn main() -> Result<(), guerrillamail_client::Error> {
    // Create a client (performs a bootstrap request)
    let client = Client::new().await?;

    // Create a temporary email address
    let email = client.create_email("myalias").await?;
    println!("Temporary email: {email}");

    // Poll inbox
    let messages = client.get_messages(&email).await?;
    for msg in messages {
        println!("From: {}", msg.mail_from);
        println!("Subject: {}", msg.mail_subject);
    }

    // Fetch full email body
    if let Some(msg) = messages.first() {
        let details = client.fetch_email(&email, &msg.mail_id).await?;
        println!("Body:\n{}", details.mail_body);
    }

    // Forget the email address
    client.delete_email(&email).await?;

    Ok(())
}

Configuration via builder

For proxies, stricter TLS, or custom user agents, use the builder API:

use guerrillamail_client::Client;

let client = Client::builder()
    .proxy("http://127.0.0.1:8080")
    .danger_accept_invalid_certs(false)
    .user_agent("my-app/1.0")
    .build()
    .await?;

Error handling

All public APIs return a crate-level Error enum.

• Transport / HTTP issues → Error::Request
• Invalid or unexpected JSON → Error::Json
• Response shape changes (missing fields, schema drift) → Error::ResponseParse
• Bootstrap token failures → Error::TokenParse

Underlying errors are preserved as sources, so tools like anyhow or eyre can display full error chains.

Limitations & caveats

• GuerrillaMail inboxes are not permanent
• Messages may disappear at any time
• Address reuse is not guaranteed
• Rate limits and blocking are controlled by GuerrillaMail, not this crate
• API behavior may change without warning

Acknowledgements

This project was inspired by and partially based on
GuerrillaMail-Python.

Contributing

PRs are welcome!
Please run cargo fmt and cargo clippy before submitting.

If you’re changing behavior (e.g. stricter parsing), document it in the PR.

Support

If this crate saves you time or helps your work, support is appreciated:

License

This project is licensed under the MIT License; see license for details.