Guerrilla Mail Getting Started: Quickstart Guide (2026)

Getting started overview

Guerrilla Mail primarily offers a web interface for users to generate and manage temporary email addresses, effectively helping to prevent spam and protect privacy online. For developers, interacting with Guerrilla Mail's functionality programmatically involves understanding its undocumented API. This guide outlines the process of generating a temporary email address and fetching its inbox content using direct HTTP requests, acknowledging that official API documentation is not publicly available.

The core process involves three main steps:

1. Generate a temporary email address: Obtain a unique email address from Guerrilla Mail.
2. Monitor the inbox: Check for incoming emails at the generated address.
3. Retrieve email content: Access the subject and body of received messages.

Because the API is not officially documented, many developers rely on community-contributed libraries or direct HTTP calls to interact with the service. This guide focuses on direct HTTP interactions for maximum clarity and control.

Create an account and get keys

Guerrilla Mail operates on a simple, free model and does not require users to create an account or obtain API keys for basic usage. This design choice simplifies access but also means there are no user-specific credentials to manage. The API is accessed directly via public endpoints. This approach contrasts with many commercial APIs that use authentication mechanisms such as API keys, OAuth 2.0, or JSON Web Tokens (JWTs) to secure access and identify users, as described in common API security practices by OAuth 2.0 documentation.

To interact with the Guerrilla Mail API, you will make direct HTTP requests to specific URLs. There's no registration process; you can begin making calls immediately. This characteristic makes Guerrilla Mail suitable for rapid prototyping and testing scenarios where credential management would introduce unnecessary overhead.

Your first request

This section walks through making your first API calls to Guerrilla Mail to obtain a temporary email address and then check its inbox. The examples will use curl for clarity, but the principles apply to any HTTP client library in languages like Python, JavaScript, or Java.

1. Get a new email address

The first step is to request a new temporary email address. Guerrilla Mail offers an endpoint for this purpose. The response will include the generated email address and a session ID.

curl "https://www.guerrillamail.com/ajax.php?f=get_email_address&ip=127.0.0.1"

A successful response will look similar to this JSON object:

{
  "sid_token": "your_session_id_token",
  "email_addr": "[email protected]",
  "email_timestamp": 1678886400,
  "alias": "example"
}

From this response, note the email_addr for sending test emails and the sid_token for subsequent API calls related to this session.

2. Check the inbox

Once you have an email address, you can send a test email to it (e.g., from another email account). Then, you can poll the Guerrilla Mail API to check for new messages in the inbox associated with your session ID. This endpoint requires the sid_token obtained in the previous step.

curl "https://www.guerrillamail.com/ajax.php?f=check_email&seq=0&sid_token=your_session_id_token"

The seq parameter can be used to retrieve messages starting from a specific sequence number, which is useful for fetching new messages incrementally. For a first check, seq=0 is appropriate. A typical response, showing no new emails, might look like this:

{
  "list": [],
  "count": "0",
  "email_addr": "[email protected]",
  "email_timestamp": 1678886400,
  "sid_token": "your_session_id_token",
  "alias": "example"
}

If an email has been received, the list array will contain objects representing the emails. Each object will include details like mail_id, mail_from, mail_subject, and mail_timestamp.

3. Fetch a specific email

If check_email returns messages in the list, you can retrieve the full content of a specific email using its mail_id. This also requires your sid_token.

curl "https://www.guerrillamail.com/ajax.php?f=fetch_email&mail_id=the_mail_id_from_check_email&sid_token=your_session_id_token"

The response for fetching an email will include comprehensive details, such as the full HTML and plain text bodies of the message, headers, subject, and sender:

{
  "mail_id": "the_mail_id_from_check_email",
  "mail_from": "[email protected]",
  "mail_subject": "Your Test Email",
  "mail_excerpt": "This is a test message body...",
  "mail_timestamp": 1678886500,
  "mail_read": 1,
  "mail_body": "<p>This is the HTML body of your test email.</p>",
  "mail_body_plain": "This is the plain text body of your test email.",
  "mail_attachments": []
}

This sequence of calls demonstrates the fundamental interaction pattern with the Guerrilla Mail API.

Common next steps

After successfully making your first requests to Guerrilla Mail, consider these next steps to integrate it effectively into your development workflow:

• Automate email testing: Integrate Guerrilla Mail into your CI/CD pipeline to automate testing of email registration, password resets, and notification systems. This helps ensure that your application's email functionality works as expected without relying on real user emails.
• Explore community libraries: While the API is undocumented, various programming language wrappers have been developed by the community. Searching for “Guerrilla Mail API Python” or “Guerrilla Mail API Node.js” can lead to existing libraries that simplify interaction, abstracting away the direct HTTP calls. These libraries often handle session management and parsing responses, similar to how official SDKs like the Twilio Python Helper Library streamline API usage.
• Understand rate limits and usage: Although Guerrilla Mail is free, it's essential to infer or monitor any unstated rate limits to avoid being temporarily blocked. Anecdotal evidence suggests frequent polling might trigger temporary IP bans.
• Implement robust error handling: For any API integration, especially with undocumented services, implement comprehensive error handling. This includes checking HTTP status codes and parsing JSON responses for error messages to gracefully manage unexpected outcomes.
• Consider security implications: While useful for testing and privacy, be aware that temporary email services are not designed for sensitive or long-term communications. Data transmitted through them should not be considered secure or permanent.

Troubleshooting the first call

When making your first calls to the Guerrilla Mail API, you might encounter issues. Here are common problems and their potential solutions:

• No response or connection refused:
  • Issue: Your curl command or HTTP client receives no response, or reports a connection error.
  • Solution: Verify your internet connection. Ensure the Guerrilla Mail server is operational by visiting the Guerrilla Mail website in a browser. Temporary network issues or server maintenance can cause this.
• Incorrect URL or parameters:
  • Issue: The API returns an error message, or the response JSON indicates an invalid request.
  • Solution: Double-check the URL and all query parameters against the examples provided. Ensure parameters like f (function) and sid_token are correctly spelled and have valid values. The structure of the URL, including ajax.php?f=function_name&param=value, is critical.
• sid_token mismatch or expiry:
  • Issue: Subsequent calls to check_email or fetch_email fail after successfully getting an email address.
  • Solution: Ensure you are using the exact sid_token returned by the get_email_address call for all subsequent requests within the same session. While not explicitly documented, sessions might have a timeout. If errors persist, try obtaining a new email address and sid_token to start a fresh session.
• IP-related issues:
  • Issue: Requests suddenly stop working, or you receive an error indicating a block.
  • Solution: Guerrilla Mail may temporarily block IPs that make an excessive number of requests in a short period. Reduce your request frequency. If using a VPN, try changing your server location. The ip=127.0.0.1 parameter in get_email_address is often a placeholder and doesn't necessarily dictate the IP used for rate limiting.
• JSON parsing errors:
  • Issue: Your application fails to parse the API response.
  • Solution: Confirm that the response is indeed valid JSON. Sometimes, an HTML error page might be returned instead of JSON if an unhandled server error occurs. Use a JSON linter or validator to inspect the raw response if in doubt. Organizations such as the W3C provide resources on JSON structure for web developers.