guerrillamail-api

Python client for the Guerrilla Mail disposable email JSON API.

Create temporary inboxes, poll for new mail, read full messages, customize addresses, extend lifetime, and delete messages — with automatic PHPSESSID / SUBSCR cookie handling.

Install

pip install guerrillamail-api

Quick start

from guerrillamail import GuerrillaMailClient

with GuerrillaMailClient() as gm:
    mailbox = gm.create_email()
    print("Address:", mailbox.address)
    print("Expires in (s):", mailbox.seconds_remaining())

    inbox = gm.check_inbox()
    for msg in inbox.messages:
        print(msg.mail_from, "—", msg.mail_subject)

    full = gm.read_message(inbox.messages[0].mail_id)
    print(full.mail_body)

Wait for an incoming email

with GuerrillaMailClient() as gm:
    gm.create_email()
    gm.check_inbox()  # consume welcome mail sequence

    # Poll until a message arrives (adjust filters as needed)
    msg = gm.wait_for_message(
        timeout=180,
        poll_interval=5,
        subject_contains="verification",
    )
    print(msg.mail_body)

Custom address

with GuerrillaMailClient() as gm:
    gm.create_email()
    gm.set_username("mytestuser")
    print(gm.mailbox.address)

API coverage

Method	Guerrilla Mail function
create_email()	get_email_address
set_username()	set_email_user
check_inbox()	check_email
list_inbox()	get_email_list
read_message()	fetch_email
delete_messages()	del_email
forget_address()	forget_me
extend_time()	extend
get_older_list()	get_older_list

Lower-level methods (get_email_address, check_email, …) return raw JSON dicts.

Rate limits

The public API may be rate-limited. Avoid tight polling; use poll_interval ≥ 5 seconds in production.

License

MIT