Archiving

Archived mailboxes are mailboxes created with recoverable=True that have expired or been deleted. They can be reactivated with the same email address.

List Archived Mailboxes

Retrieve all archived mailboxes.

archived = client.list_archived_mailboxes()

for mailbox in archived["items"]:
    print(f"{mailbox['alias']}@{mailbox['domain']}")
    print(f"  Tag: {mailbox['tag']}")
    print(f"  Created: {mailbox['createdAt']}")

Returns

{
    "items": [
        {
            "id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
            "alias": "old-alias",
            "domain": "minutemail.cc",
            "tag": "newsletter",
            "createdAt": "2024-01-17T00:00:00Z"
        }
    ]
}

Get Archived Mailbox

Retrieve details of a specific archived mailbox.

mailbox = client.get_archived_mailbox("a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d")

print(f"Address: {mailbox['alias']}@{mailbox['domain']}")
print(f"Tag: {mailbox['tag']}")

Parameters

Parameter	Type	Required	Description
`archived_mailbox_id`	str	✅	Archived mailbox identifier

Reactivate Archived Mailbox

Restore an archived mailbox with the same email address.

mailbox = client.reactivate_archived_mailbox(
    "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    expires_in=120  # Integer: minutes (1-60)
)

print(f"Reactivated: {mailbox['address']}")
print(f"Expires at: {mailbox['expiresAt']}")

Parameters

Parameter	Type	Required	Description
`archived_mailbox_id`	str	✅	Archived mailbox identifier
`expires_in`	int	❌	Lifetime in minutes (1-60) for reactivated mailbox

Returns

A new active mailbox with the same email address:

{
    "id": "ed930b25-dd40-41b3-a712-e502fbcc5565",  # New ID
    "alias": "old-alias",
    "domain": "minutemail.cc",
    "address": "old-alias@minutemail.cc",
    "recoverable": True,
    "tag": "newsletter",
    "messageCount": 0,
    "expiresAt": "2024-01-18T03:00:00Z",
    "createdAt": "2024-01-18T01:00:00Z"
}

Delete Archived Mailbox

Permanently delete a single archived mailbox. This action cannot be undone.

client.delete_archived_mailbox("a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d")
print("Archived mailbox permanently deleted")

Parameters

Parameter	Type	Required	Description
`archived_mailbox_id`	str	✅	Archived mailbox identifier

Delete Multiple Archived Mailboxes (Bulk)

NEW in v1.0.0: Permanently delete multiple archived mailboxes in a single atomic operation.

# Delete multiple archived mailboxes at once
client.delete_archived_mailboxes([
    "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "b2c3d4e5-f6a7-5432-9876-1234567890ab",
    "c3d4e5f6-a7b8-6543-0987-234567890abc"
])

print("All archived mailboxes permanently deleted")

Parameters

Parameter	Type	Required	Description
`ids`	List[str]	✅	Array of archived mailbox identifiers to delete

Returns

None (returns None on success)

Notes

This action cannot be undone
Operation is atomic: all archived mailboxes are validated before any deletion occurs
If any validation fails, the entire operation is rejected (no partial deletions)
All associated data is permanently deleted

Use Case: Recurring Test Email Address

Reuse the same email address for repeated testing.

from minutemail import MinuteMailClient

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

def get_or_create_test_mailbox(tag="nightly-tests"):
    """
    Get a reusable test mailbox by tag, or create a new one.
    """
    # Check for archived mailbox with this tag
    archived = client.list_archived_mailboxes()

    for mailbox in archived["items"]:
        if mailbox["tag"] == tag:
            # Reactivate existing mailbox
            reactivated = client.reactivate_archived_mailbox(
                mailbox["id"],
                expires_in=60  # 1 hour (integer in minutes)
            )
            print(f"✓ Reactivated: {reactivated['address']}")
            return reactivated

    # No archived mailbox found, create new one
    new_mailbox = client.create_mailbox(
        domain="minutemail.cc",
        recoverable=True,
        tag=tag,
        expires_in=60  # 1 hour (integer in minutes)
    )
    print(f"✓ Created new: {new_mailbox['address']}")
    return new_mailbox

# Usage in nightly tests
mailbox = get_or_create_test_mailbox("nightly-tests")
print(f"Using mailbox: {mailbox['address']}")

# Run tests...
# (mailbox will auto-archive when it expires)

Complete Example: Managing Test Mailboxes

from minutemail import MinuteMailClient, APIError
from datetime import datetime

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

def manage_test_mailboxes():
    """
    Example workflow for managing test mailboxes.
    """
    # 1. Create a recoverable mailbox for testing
    print("Creating test mailbox...")
    mailbox = client.create_mailbox(
        domain="minutemail.cc",
        recoverable=True,
        tag="integration-test",
        expires_in=30  # 30 minutes (integer)
    )
    print(f"✓ Created: {mailbox['address']}")

    # 2. Use the mailbox (simulate test)
    print("Running test...")
    # ... your test logic ...

    # 3. Manually archive it (delete)
    print("Archiving mailbox...")
    client.delete_mailbox(mailbox["id"])

    # 4. List archived mailboxes
    print("\nArchived mailboxes:")
    archived = client.list_archived_mailboxes()
    for arch in archived["items"]:
        print(f"  - {arch['alias']}@{arch['domain']} (tag: {arch['tag']})")

    # 5. Reactivate for another test run
    if archived["items"]:
        first_archived = archived["items"][0]
        print(f"\nReactivating: {first_archived['alias']}@{first_archived['domain']}")

        reactivated = client.reactivate_archived_mailbox(
            first_archived["id"],
            expires_in=60  # 1 hour (integer in minutes)
        )
        print(f"✓ Reactivated: {reactivated['address']}")

        # Clean up permanently when done
        client.delete_archived_mailbox(first_archived["id"])
        print("✓ Permanently deleted archived mailbox")

try:
    manage_test_mailboxes()
except APIError as e:
    print(f"Error: {e.message}")

Best Practices

Tag Organization

Use descriptive tags to organize archived mailboxes:

# Different tags for different test suites
client.create_mailbox(
    domain="minutemail.cc",
    recoverable=True,
    tag="unit-tests",
    expires_in=15  # 15 minutes (integer)
)

client.create_mailbox(
    domain="minutemail.cc",
    recoverable=True,
    tag="integration-tests",
    expires_in=30  # 30 minutes (integer)
)

client.create_mailbox(
    domain="minutemail.cc",
    recoverable=True,
    tag="e2e-tests",
    expires_in=60  # 60 minutes / 1 hour (integer)
)

Cleanup Archived Mailboxes

Periodically clean up old archived mailboxes to avoid quota limits:

def cleanup_old_archived_mailboxes(keep_tags=None):
    """
    Delete archived mailboxes except those with specific tags.

    Args:
        keep_tags: List of tags to keep (e.g., ["production-tests"])
    """
    keep_tags = keep_tags or []
    archived = client.list_archived_mailboxes()

    # Collect IDs to delete
    ids_to_delete = [
        mailbox["id"]
        for mailbox in archived["items"]
        if mailbox["tag"] not in keep_tags
    ]

    # Bulk delete (NEW in v1.0.0)
    if ids_to_delete:
        client.delete_archived_mailboxes(ids_to_delete)
        print(f"Deleted {len(ids_to_delete)} archived mailboxes")

# Usage
cleanup_old_archived_mailboxes(keep_tags=["nightly-tests"])