Messages

Messages

List Emails

List all emails in a mailbox.

mails = client.list_mails("ed930b25-dd40-41b3-a712-e502fbcc5565")

for mail in mails["items"]:
    print(f"From: {mail['sender']}")
    print(f"Subject: {mail['subject']}")
    print(f"Has attachments: {mail['hasAttachments']}")
    print("---")

Parameters

Parameter	Type	Required	Description
mailbox_id	str	✅	Mailbox identifier

Returns

{
    "items": [
        {
            "id": "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
            "mailboxId": "ed930b25-dd40-41b3-a712-e502fbcc5565",
            "sender": "sender@example.com",
            "subject": "Welcome!",
            "body": "This is a test email.",
            "hasAttachments": True,
            "attachments": [
                {
                    "id": "12345678-1234-1234-1234-123456789abc",
                    "name": "document.pdf",
                    "sizeBytes": 102400
                }
            ],
            "receivedAt": "2024-01-18T00:15:00Z"
        }
    ]
}

---

Get Email

Retrieve a specific email.

mail = client.get_mail("ed930b25-dd40-41b3-a712-e502fbcc5565", "f1e2d3c4-b5a6-9876-5432-10fedcba9876")

print(f"From: {mail['sender']}")
print(f"Subject: {mail['subject']}")
print(f"Body: {mail['body']}")

if mail["hasAttachments"]:
    print(f"Attachments: {len(mail['attachments'])}")

Parameters

Parameter	Type	Required	Description
mailbox_id	str	✅	Mailbox identifier
mail_id	str	✅	Email identifier

---

Delete Email

Delete a single email.

client.delete_mail("ed930b25-dd40-41b3-a712-e502fbcc5565", "f1e2d3c4-b5a6-9876-5432-10fedcba9876")
print("Email deleted")

Parameters

Parameter	Type	Required	Description
mailbox_id	str	✅	Mailbox identifier
mail_id	str	✅	Email identifier

---

Delete Multiple Emails (Bulk)

NEW in v1.0.0: Delete multiple emails from a mailbox in a single atomic operation.

# Delete multiple emails at once
client.delete_mails(
    "ed930b25-dd40-41b3-a712-e502fbcc5565",
    [
        "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
        "a2b3c4d5-e6f7-8765-4321-0fedcba98765",
        "b3c4d5e6-f7a8-7654-3210-fedcba987654"
    ]
)

print("All emails deleted")

Parameters

Parameter	Type	Required	Description
mailbox_id	str	✅	Mailbox identifier
ids	List[str]	✅	Array of email identifiers to delete

Returns

None (returns None on success)

Notes

• All attachments associated with the emails are also deleted
• Operation is atomic: either all emails are deleted or none
• Silently skips non-existent email IDs

---

Polling for Emails

Wait for emails to arrive using a polling pattern.

import time
from minutemail import MinuteMailClient

client = MinuteMailClient(api_key="your-api-key")

def wait_for_email(mailbox_id, timeout=60, poll_interval=5):
    """
    Poll for emails until one arrives or timeout is reached.

    Args:
        mailbox_id: Mailbox to check
        timeout: Maximum time to wait (seconds)
        poll_interval: Time between checks (seconds)

    Returns:
        First email received, or None if timeout
    """
    elapsed = 0

    while elapsed < timeout:
        mails = client.list_mails(mailbox_id)

        if mails["items"]:
            return mails["items"][0]  # Return first email

        time.sleep(poll_interval)
        elapsed += poll_interval

    return None

# Usage
mailbox = client.create_mailbox(
    domain="minutemail.cc",
    expires_in=30  # 30 minutes
)

print(f"Waiting for email at {mailbox['address']}...")
email = wait_for_email(mailbox["id"], timeout=120)

if email:
    print(f"Received email from {email['sender']}")
    print(f"Subject: {email['subject']}")
else:
    print("No email received within timeout")

---

Extracting Verification Links

Extract links from email bodies for automated testing.

import re

def extract_verification_link(email_body, domain="example.com"):
    """Extract verification/confirmation links from email body."""
    # Match URLs containing 'verify', 'confirm', or 'activate'
    pattern = rf'https?://{re.escape(domain)}/[^\s]*(?:verify|confirm|activate)[^\s]*'

    matches = re.findall(pattern, email_body)
    return matches[0] if matches else None

# Usage
mail = client.get_mail(mailbox_id, mail_id)
link = extract_verification_link(mail["body"], "example.com")

if link:
    print(f"Verification link: {link}")
    # Proceed with automated testing

---

Complete Example: Email Verification Flow

from minutemail import MinuteMailClient
import time
import re

client = MinuteMailClient(api_key="your-api-key")

def test_email_verification():
    # 1. Create mailbox
    mailbox = client.create_mailbox(
        domain="minutemail.cc",
        expires_in=15,
        tag="test-signup"
    )
    email_address = mailbox["address"]
    print(f"✓ Created mailbox: {email_address}")

    # 2. Trigger signup (your application logic)
    # signup_user(email_address)

    # 3. Wait for verification email
    print("Waiting for verification email...")
    for attempt in range(24):  # 2 minutes max (24 * 5s)
        mails = client.list_mails(mailbox["id"])

        if mails["items"]:
            mail = mails["items"][0]
            print(f"✓ Received email: {mail['subject']}")

            # 4. Extract verification link
            link_pattern = r'https://example\.com/verify\?token=[\w-]+'
            match = re.search(link_pattern, mail["body"])

            if match:
                verification_link = match.group(0)
                print(f"✓ Found verification link: {verification_link}")

                # 5. Clean up
                client.delete_mailbox(mailbox["id"])
                return verification_link

        time.sleep(5)

    print("✗ No email received")
    client.delete_mailbox(mailbox["id"])
    return None

# Run the test
link = test_email_verification()
if link:
    print(f"Test passed! Verification link: {link}")

---

Attachments

List Attachments

List all attachments for an email.

attachments = client.list_attachments("ed930b25-dd40-41b3-a712-e502fbcc5565", "f1e2d3c4-b5a6-9876-5432-10fedcba9876")

for att in attachments["items"]:
    print(f"Name: {att['name']}")
    print(f"Type: {att['contentType']}")
    print(f"Size: {att['sizeBytes']} bytes")

Parameters

Parameter	Type	Required	Description
mailbox_id	str	✅	Mailbox identifier
mail_id	str	✅	Email identifier

Returns

{
    "items": [
        {
            "id": "12345678-1234-1234-1234-123456789abc",
            "mailId": "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
            "name": "document.pdf",
            "contentType": "application/pdf",
            "sizeBytes": 102400
        }
    ]
}

---

Get Attachment

Download a specific attachment.

import base64

attachment = client.get_attachment("ed930b25-dd40-41b3-a712-e502fbcc5565", "f1e2d3c4-b5a6-9876-5432-10fedcba9876", "12345678-1234-1234-1234-123456789abc")

# Decode base64 data
file_data = base64.b64decode(attachment["data"])

# Save to disk
with open(attachment["name"], "wb") as f:
    f.write(file_data)

print(f"Saved {attachment['name']} ({attachment['sizeBytes']} bytes)")

Parameters

Parameter	Type	Required	Description
mailbox_id	str	✅	Mailbox identifier
mail_id	str	✅	Email identifier
attachment_id	str	✅	Attachment identifier

Returns

{
    "id": "12345678-1234-1234-1234-123456789abc",
    "name": "document.pdf",
    "contentType": "application/pdf",
    "data": "JVBERi0xLjQKJ...",  # Base64-encoded content
    "sizeBytes": 102400
}

---

Delete Attachment

Delete a single attachment.

client.delete_attachment("ed930b25-dd40-41b3-a712-e502fbcc5565", "f1e2d3c4-b5a6-9876-5432-10fedcba9876", "12345678-1234-1234-1234-123456789abc")
print("Attachment deleted")

Parameters

Parameter	Type	Required	Description
mailbox_id	str	✅	Mailbox identifier
mail_id	str	✅	Email identifier
attachment_id	str	✅	Attachment identifier

---

Delete Multiple Attachments (Bulk)

NEW in v1.0.0: Delete multiple attachments from an email in a single atomic operation.

# Delete multiple attachments at once
client.delete_attachments(
    "ed930b25-dd40-41b3-a712-e502fbcc5565",
    "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
    [
        "12345678-1234-1234-1234-123456789abc",
        "23456789-2345-2345-2345-234567890bcd",
        "34567890-3456-3456-3456-345678901cde"
    ]
)

print("All attachments deleted")

Parameters

Parameter	Type	Required	Description
mailbox_id	str	✅	Mailbox identifier
mail_id	str	✅	Email identifier
ids	List[str]	✅	Array of attachment identifiers to delete

Returns

None (returns None on success)

Notes

• Attachment summaries are automatically refreshed after deletion
• Silently skips non-existent attachment IDs
• Operation is atomic at the mailbox ownership level

---

Download All Attachments

Download all attachments from an email.

import base64
import os

def download_all_attachments(mailbox_id, mail_id, output_dir="downloads"):
    """
    Download all attachments from an email.

    Args:
        mailbox_id: Mailbox identifier
        mail_id: Email identifier
        output_dir: Directory to save attachments
    """
    # Create output directory
    os.makedirs(output_dir, exist_ok=True)

    # List attachments
    attachments = client.list_attachments(mailbox_id, mail_id)

    downloaded = []
    for att_meta in attachments["items"]:
        # Get full attachment with data
        att = client.get_attachment(mailbox_id, mail_id, att_meta["id"])

        # Decode and save
        file_data = base64.b64decode(att["data"])
        file_path = os.path.join(output_dir, att["name"])

        with open(file_path, "wb") as f:
            f.write(file_data)

        downloaded.append(file_path)
        print(f"Downloaded: {file_path}")

    return downloaded

# Usage
files = download_all_attachments("ed930b25-dd40-41b3-a712-e502fbcc5565", "f1e2d3c4-b5a6-9876-5432-10fedcba9876")
print(f"Downloaded {len(files)} attachment(s)")

---

Verify Attachment Content

Verify downloaded files match expected content.

import base64
import hashlib

def verify_attachment(mailbox_id, mail_id, attachment_id, expected_hash):
    """
    Verify attachment integrity using SHA256 hash.

    Args:
        mailbox_id: Mailbox identifier
        mail_id: Email identifier
        attachment_id: Attachment identifier
        expected_hash: Expected SHA256 hash (hex string)

    Returns:
        True if hash matches, False otherwise
    """
    att = client.get_attachment(mailbox_id, mail_id, attachment_id)
    file_data = base64.b64decode(att["data"])

    actual_hash = hashlib.sha256(file_data).hexdigest()

    return actual_hash == expected_hash

# Usage
is_valid = verify_attachment(
    "ed930b25-dd40-41b3-a712-e502fbcc5565",
    "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
    "12345678-1234-1234-1234-123456789abc",
    "a3c5e8d9f..."  # Expected hash
)

print(f"Attachment valid: {is_valid}")

---

Complete Example: Process Email with Attachments

from minutemail import MinuteMailClient
import base64
import os

client = MinuteMailClient(api_key="your-api-key")

def process_email_with_attachments(mailbox_id):
    """
    Process the first email in a mailbox and download attachments.
    """
    # Get emails
    mails = client.list_mails(mailbox_id)

    if not mails["items"]:
        print("No emails found")
        return

    mail = mails["items"][0]
    print(f"Processing email from {mail['sender']}")
    print(f"Subject: {mail['subject']}")

    # Check for attachments
    if not mail["hasAttachments"]:
        print("No attachments")
        return

    print(f"Found {len(mail['attachments'])} attachment(s)")

    # Download each attachment
    output_dir = f"mailbox_{mailbox_id}"
    os.makedirs(output_dir, exist_ok=True)

    for att_meta in mail["attachments"]:
        # Get full attachment
        att = client.get_attachment(
            mailbox_id,
            mail["id"],
            att_meta["id"]
        )

        # Decode and save
        file_data = base64.b64decode(att["data"])
        file_path = os.path.join(output_dir, att["name"])

        with open(file_path, "wb") as f:
            f.write(file_data)

        print(f"  ✓ {att['name']} ({att['sizeBytes']} bytes)")

    print(f"All attachments saved to {output_dir}/")

# Usage
mailbox = client.create_mailbox(domain="minutemail.cc", expires_in=30  # 30 minutes)
print(f"Send emails with attachments to: {mailbox['address']}")

# Wait for email...
import time
time.sleep(30)

process_email_with_attachments(mailbox["id"])
client.delete_mailbox(mailbox["id"])