unofficial-xitroo-api 0.9.1

Xitroo API

Unofficial Xitroo API for Python

A powerful and easy-to-use Python wrapper for the Xitroo temporary email service. This library allows you to programmatically create temporary email addresses, read inboxes, parse emails, handle attachments, and even send emails.

• Author: Th3K1n91
• Source Code: https://github.com/Th3K1n91/unofficial-xitroo-api

✨ Key Features

• 📧 Generate Email Addresses: Instantly create random Xitroo email addresses.
• 📥 Full Inbox Control: Fetch all emails from an inbox, get the total count, and access individual emails.
• 📖 Read Emails: Parse email content, including subject, sender, HTML body, and plain text body.
• 🔢 Automatic Code Parsing: Easily extract verification codes (e.g., 123456) from email bodies.
• 🔎 Powerful Search: Search your inbox by sender, subject, date, or specific text within the email body.
• 📎 Attachment Handling: List, download, or read attachments directly.
• 📤 Send Emails: Send emails from your temporary address (with CAPTCHA handling).
• 🗑️ Delete Emails: Clean up your inbox by deleting unwanted emails.
• ⏱️ Wait for New Mail: Asynchronously wait for the latest email to arrive.

📦 Installation

Install the library using pip:

pip install unofficial-xitroo-api

This library depends on the requests package, which will be installed automatically.

🚀 Usage Examples

Here are some common use cases to get you started.

Quick Start: Get a New Email and Read It

This example generates a new random email address, waits for the first email to arrive, and prints its subject and body.

from xitroo import Xitroo

# 1. Generate a random email address
random_email = Xitroo.generate()
print(f"Using temporary email: {random_email}")

# 2. Create a Xitroo instance
client = Xitroo(random_email)

# 3. Wait for the latest email to arrive (up to 60 seconds)
print("Waiting for a new email...")
# The waitForLatestMail method is ideal for automation scripts
latest_mail = client.waitForLatestMail()

if latest_mail:
    print("\n--- New Email Received! ---")
    print(f"From: {latest_mail.getFromMail()}")
    print(f"Subject: {latest_mail.getSubject()}")
    
    # Get a verification code from the email body
    try:
        code = latest_mail.getCode()
        print(f"Verification Code: {code}")
    except AttributeError:
        print("No verification code found in the email.")
    
    print("\n--- Email Body (Text) ---")
    print(latest_mail.getBodyText())
else:
    print("No email received within the time limit.")

Reading an Inbox

You can easily access an inbox and iterate through all the emails it contains.

from xitroo import Xitroo, EmailNotFound

# Use an existing email address
client = Xitroo("[e-mail]")

try:
    # Get the Inbox object
    inbox = client.Inbox()
    
    print(f"Total emails in inbox: {len(inbox)}")
    
    # Iterate through all emails
    for mail in inbox:
        print(f" - Subject: {mail.getSubject()}")

    # Get the first and last emails
    if len(inbox) > 0:
        first_mail = inbox.getMailFirst()
        print(f"\nOldest email subject: {first_mail.getSubject()}")

        last_mail = inbox.getMailLast()
        print(f"Newest email subject: {last_mail.getSubject()}")

except EmailNotFound as e:
    print(e)

Searching the Inbox

The searchInbox method provides a flexible way to find specific emails without iterating through the entire inbox yourself.

from xitroo import Xitroo

client = Xitroo("[e-mail]")
search = client.searchInbox()

# Search for all emails from "[e-mail]"
print("Searching for emails from '[e-mail]'...")
results_by_sender = search.BY.SENDER("[e-mail]")
print(f"Found {len(results_by_sender)} emails.")
for mail in results_by_sender:
    print(f"  - ID: {mail.getId()}, Subject: {mail.getSubject()}")


# Search for all emails with "verification" in the title
print("\nSearching for emails with 'Verification' in the subject...")
results_by_title = search.BY.TITLE("Verification")
print(f"Found {len(results_by_title)} emails.")
for mail in results_by_title:
    print(f"  - ID: {mail.getId()}, Subject: {mail.getSubject()}")

Sending an Email (with CAPTCHA)

You can send emails programmatically. This requires solving a CAPTCHA. The library supports both manual and programmatic solving.

Mode 1: Manual CAPTCHA Solving (User Input) The library will print the CAPTCHA to the console and wait for you to type the solution.

from xitroo import Xitroo

# Use your generated email address as the sender
sender_client = Xitroo(Xitroo.generate())

print(f"Sending email from: {sender_client.getMailAddress()}")

# Use mode=1 for manual input
# The CAPTCHA image text will be printed to the console
success = sender_client.sendMail(
    recipient="[e-mail]",
    subject="Hello from Xitroo API!",
    Text="This is a test email sent using the Python library.",
    mode=1 
)

if success:
    print("Email sent successfully!")
else:
    print("Failed to send email.")

Mode 0: Programmatic CAPTCHA Solving If you have an external CAPTCHA solving service, you can get the CAPTCHA data and submit the solution yourself.

from xitroo import Xitroo

client = Xitroo("[e-mail]")

# 1. Get the captcha object
captcha_handler = client.Captcha()

# 2. Get captcha data
captcha_data = captcha_handler.getCaptcha()
captcha_id = captcha_data["authID"]
captcha_image_code = captcha_data["captchaCode"] # This is the base64 encoded image

# --- Here you would send captcha_image_code to your solving service ---
# --- For this example, we'll pretend the solution is 'ABCDE' ---
solution = "ABCDE" # Replace with the actual solution

# 3. Verify the solution to get an auth token
if captcha_handler.verifyCaptcha(solution):
    print("Captcha solved! Sending email...")
    # 4. Use the captcha_id to send the mail with mode=0
    success = client.sendMail(
        recipient="[e-mail]",
        subject="Automated Email",
        Text="This was sent programmatically.",
        mode=0,
        id=captcha_id
    )
    if success:
        print("Email sent!")
    else:
        print("Email sending failed.")
else:
    print("Captcha verification failed.")

Handling Attachments

Download or read attachments from an email.

from xitroo import Xitroo

client = Xitroo("[e-mail]")
inbox = client.Inbox()

if len(inbox) > 0:
    # Get the latest mail
    mail = inbox.getMailFirst()
    
    # List attachments
    attachments = mail.getAttachments()
    if attachments:
        print(f"Found {len(attachments)} attachments.")
        for attachment in attachments:
            filename = attachment['filename']
            print(f" - Attachment Filename: {filename}")
            
            # Download the attachment
            success = mail.downloadAttachment(filename, path=".") # Download to current directory
            if success:
                print(f"   '{filename}' downloaded successfully.")
            else:
                print(f"   Failed to download '{filename}'.")
    else:
        print("No attachments found in the latest email.")

---

API Documentation

Xitroo Class

This is the main class to interact with the API.

• Xitroo(mailAddress, header={}, session=None): Constructor.
  • mailAddress (str): The full Xitroo email address (e.g., [e-mail]).
• generate(prefix="", suffix="", locale="de", randomletterscount=10) (staticmethod): Generates a random email address string.
• getCode(body, codelength=6) (staticmethod): Extracts a numerical code of a given length from a string.
• getMailAddress(): Returns the current mail address.
• setMailAddress(mailAddress): Changes the mail address for the instance.
• Inbox(): Returns an Inbox object for the current mail address.
• Mail(mailId): Returns a Mail object for a specific mail ID.
• getLatestMail(): Returns a Mail object for the most recent email, or None.
• waitForLatestMail(maxTime=60, sleepTime=5, checkMail=100): Waits for a new email to arrive and returns it.
• sendMail(recipient, subject, Text, mode=1, id=""): Sends an email.
  • mode=1: Manual user input for CAPTCHA.
  • mode=0: Programmatic; requires a valid id from a solved Captcha.
• searchInbox(): Returns a SearchMail object to perform searches.
• Captcha(): Returns a Captcha object for handling CAPTCHAs.

Inbox Class

Represents the email inbox. Accessed via Xitroo.Inbox().

• __len__(): Returns the total number of emails in the inbox.
• __getitem__(index): Allows iteration (e.g., for mail in inbox:). Returns a Mail object.
• getMail(index): Returns a Mail object at a specific index.
• getMailFirst(): Returns the newest email in the inbox.
• getMailLast(): Returns the oldest email in the inbox.
• getRawInbox(): Returns the raw JSON response from the API for the inbox.

Mail Class

Represents a single email. Accessed from an Inbox object or Xitroo.Mail(id).

• getId(): Returns the mail's unique ID.
• getSubject(): Returns the email subject as a decoded string.
• getBodyHtml(): Returns the full HTML body of the email.
• getBodyText(): Returns the plain text body of the email.
• getFromMail(): Returns the sender's email address.
• getArrivalTimestamp(): Returns the arrival timestamp.
• getCode(codelength=6): Searches the text body for a numerical code of codelength and returns it as a string.
• getAttachments(): Returns a list of attachment dictionaries.
• downloadAttachment(filetodownload, path=None): Downloads a named attachment to a specified path.
• readAttachment(filetoread, encoding='utf-8'): Reads a named attachment and returns its content as a string.
• delete(): Deletes the email from the inbox.
• getRawMail(): Returns the raw JSON response for the email.

SearchMail Class

Provides methods for searching. Accessed via Xitroo.searchInbox().

• Usage:

  search = client.searchInbox()
  results = search.BY.METHOD(query)
  

• search.BY Methods:
  • SENDER(sender_str): Search for emails where the sender contains sender_str.
  • TITLE(title_str): Search for emails where the subject contains title_str.
  • TEXT(text_str): Search for emails where the body contains text_str.
  • DATE(datetime_obj): Search for emails that arrived on the same date as the datetime object.
• Each search method returns a new Inbox object containing only the search results.

Captcha Class

Handles CAPTCHA generation and verification. Accessed via Xitroo.Captcha().

• getCaptcha(): Requests a new CAPTCHA from the server. Returns a dict containing the authID and the base64-encoded captchaCode (image).
• verifyCaptcha(solution, captchaid=""): Submits a solution for a given CAPTCHA ID. Returns True on success, False on failure.