Struct Client 

pub struct Client { /* private fields */ }

High-level async handle to a single GuerrillaMail session.

Conceptually, a Client owns the session state needed to talk to the public GuerrillaMail AJAX API: a cookie jar plus the ApiToken … header parsed from an initial bootstrap request. Every outbound request reuses prebuilt header maps that always include that token, a browser-like user agent, and the correct host/origin metadata.

Invariants/internal behavior:

• The API token is fetched once during construction and stored as a header; it is never refreshed automatically. Rebuild the client if the token expires.
• Addresses are treated as alias@domain; when the API only cares about the alias, the client extracts it for you.
• The underlying reqwest::Client has cookies enabled so successive calls share the same GuerrillaMail session.

Typical lifecycle: create a client (Client::new or Client::builder().build()), allocate an address, poll messages, fetch message details/attachments (via Message and crate::EmailDetails), then optionally forget the address.

Concurrency: Client is Clone and cheap to duplicate; clones share the HTTP connection pool, cookies, and token header, making it safe to pass into multiple async tasks.

Example

let client = Client::new().await?;
let email = client.create_email("demo").await?;
let messages = client.get_messages(&email).await?;
println!("Inbox size: {}", messages.len());
client.delete_email(&email).await?;

Implementations

impl Client

pub fn builder() -> ClientBuilder

Create a ClientBuilder for configuring a new client.

Use this when you need to set a proxy, change TLS behavior, or override the user agent.

Examples

let client = Client::builder()
    .user_agent("my-app/1.0")
    .build()
    .await?;

pub async fn new() -> Result<Self>

Build a default GuerrillaMail client.

Performs a single bootstrap GET to the GuerrillaMail homepage, extracts the ApiToken … header, and constructs a session-aware client using default headers and timeouts. The token is not refreshed automatically; rebuild the client if it expires. Use Client::builder when you need proxy/TLS overrides.

Errors

• Returns Error::Request on bootstrap network failures or any non-2xx response (via error_for_status).
• Returns Error::TokenParse when the API token cannot be extracted from the homepage HTML.
• Returns Error::HeaderValue if the parsed token cannot be encoded into a header.

Examples

let client = Client::new().await?;

pub fn proxy(&self) -> Option<&str>

Get the proxy URL configured for this client (if any).

Returns None when no proxy was set on the builder.

pub async fn create_email(&self, alias: &str) -> Result<String>

Request a new temporary address for the given alias.

Sends a POST to the GuerrillaMail AJAX endpoint, asking the service to reserve the supplied alias and return the full alias@domain address. Builds required headers and includes the session token automatically.

Arguments

• alias: Desired local-part before @.

Returns

The full email address assigned by GuerrillaMail (e.g., myalias@sharklasers.com).

Errors

• Returns Error::Request for network failures or non-2xx responses.
• Returns Error::ResponseParse if the JSON body lacks a string email_addr field. Network failures are typically transient; parse errors usually indicate an API schema change.

Network

Issues one POST request to ajax.php.

Examples

let client = Client::new().await?;
let email = client.create_email("myalias").await?;
println!("{email}");

pub async fn get_messages(&self, email: &str) -> Result<Vec<Message>>

Fetch the current inbox listing for an address.

Calls the check_email AJAX function using only the alias portion of the provided address. Includes cache-busting timestamp and required headers; parses the list array into Message structs.

Arguments

• email: Full address (alias is extracted automatically).

Returns

Vector of message headers/summaries currently in the inbox.

Errors

• Returns Error::Request for network failures or non-2xx responses.
• Returns Error::ResponseParse when the JSON body is missing a list array.
• Returns Error::Json if individual messages fail to deserialize. Network issues are transient; parse/deserialize errors generally indicate a schema change.

Network

Issues one GET request to ajax.php with query parameters.

Examples

let client = Client::new().await?;
let email = client.create_email("myalias").await?;
let messages = client.get_messages(&email).await?;
for msg in messages {
    println!("{}: {}", msg.mail_from, msg.mail_subject);
}

pub async fn fetch_email( &self, email: &str, mail_id: &str, ) -> Result<EmailDetails>

Fetch full contents for a message.

Calls the fetch_email AJAX function using the alias derived from the address and the provided mail_id, then deserializes the full message metadata and body.

Arguments

• email: Full address associated with the message.
• mail_id: Identifier obtained from get_messages.

Returns

crate::EmailDetails containing body, metadata, attachments, and optional sid_token.

Errors

• Returns Error::Request for network failures or non-2xx responses.
• Returns Error::Json if the response body cannot be deserialized into EmailDetails. Network issues are transient; deserialization errors suggest a changed API response.

Network

Issues one GET request to ajax.php.

Examples

let client = Client::new().await?;
let email = client.create_email("myalias").await?;
let messages = client.get_messages(&email).await?;
if let Some(msg) = messages.first() {
    let details = client.fetch_email(&email, &msg.mail_id).await?;
    println!("{}", details.mail_body);
}

pub async fn list_attachments( &self, email: &str, mail_id: &str, ) -> Result<Vec<Attachment>>

List attachment metadata for a message.

Convenience wrapper over fetch_email that extracts the attachment list from the returned details.

Errors

• Propagates any Error::Request or parsing errors from fetch_email. Transient network issues bubble up unchanged; parse errors imply the upstream response shape shifted.

pub async fn fetch_attachment( &self, email: &str, mail_id: &str, attachment: &Attachment, ) -> Result<Vec<u8>>

Download an attachment for a message.

Performs a GET to the inbox download endpoint, including any sid_token previously returned by fetch_email. Requires a non-empty part_id on the attachment and the originating mail_id.

Arguments

• email: Full address used to derive the alias for token-related calls.
• mail_id: Message id whose attachment is being fetched.
• attachment: Attachment metadata containing the part id to retrieve.

Returns

Raw bytes of the attachment body.

Errors

• Returns Error::ResponseParse if part_id or mail_id are empty.
• Returns Error::Request for network failures or non-2xx download responses (via error_for_status). Empty identifiers are permanent until corrected; network and status errors are transient.

Network

Issues one GET request to the inbox download endpoint (typically /inbox).

Examples

let client = Client::new().await?;
let email = client.create_email("myalias").await?;
let messages = client.get_messages(&email).await?;
if let Some(msg) = messages.first() {
    let attachments = client.list_attachments(&email, &msg.mail_id).await?;
    if let Some(attachment) = attachments.first() {
        let bytes = client.fetch_attachment(&email, &msg.mail_id, attachment).await?;
        println!("Downloaded {} bytes", bytes.len());
    }
}

pub async fn delete_email(&self, email: &str) -> Result<bool>

Ask GuerrillaMail to forget an address for this session.

Calls the forget_me AJAX function using the alias extracted from the provided address. Only affects the current session; it does not guarantee global deletion of the address.

Arguments

• email: Full address to remove from the session.

Returns

true when the HTTP response status is 2xx.

Errors

• Returns Error::Request for network failures or non-2xx responses from the forget_me call. Network/non-2xx failures are transient; repeated failures may indicate the service endpoint changed.

Network

Issues one POST request to ajax.php.

Examples

let client = Client::new().await?;
let email = client.create_email("myalias").await?;
let ok = client.delete_email(&email).await?;
println!("{ok}");

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.