Mailboxes

Mailboxes

Create Mailbox

Create a new temporary email address.

mailbox = client.create_mailbox(
    domain="minutemail.cc",
    expires_in=30,  # Integer: minutes (1-60)
    recoverable=True,
    tag="signup-flow"
)

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

Parameters

Parameter	Type	Required	Description
domain	str	❌	Domain for the mailbox (e.g., minutemail.cc). Defaults to minutemail.cc if omitted.
expires_in	int	❌	Lifetime in minutes (1-60)
recoverable	bool	❌	Archive mailbox on expiration (allows reactivation)
tag	str	Conditional	Required if recoverable=True

Returns

{
    "id": "mb_abc123",
    "alias": "random-alias",
    "domain": "minutemail.cc",
    "address": "random-alias@minutemail.cc",
    "recoverable": True,
    "tag": "signup-flow",
    "messageCount": 0,
    "expiresAt": "2024-01-18T00:30:00Z",
    "createdAt": "2024-01-18T00:00:00Z"
}

---

List Mailboxes

Retrieve all active mailboxes for your account.

# List all mailboxes
result = client.list_mailboxes()

for mailbox in result["items"]:
    print(f"{mailbox['address']} - Expires: {mailbox['expiresAt']}")

# Filter by exact email address (NEW in v1.0.0)
result = client.list_mailboxes(address="specific@minutemail.cc")

Parameters

Parameter	Type	Required	Description
address	str	❌	Filter by exact email address

Returns

{
    "items": [
        {
            "id": "mb_abc123",
            "alias": "random-alias",
            "domain": "minutemail.cc",
            "address": "random-alias@minutemail.cc",
            "recoverable": True,
            "tag": "important",
            "messageCount": 3,
            "expiresAt": "2024-01-18T01:00:00Z",
            "createdAt": "2024-01-18T00:00:00Z"
        }
    ]
}

---

Get Mailbox

Retrieve details of a specific mailbox.

mailbox = client.get_mailbox("mb_abc123")

print(f"Address: {mailbox['address']}")
print(f"Tag: {mailbox['tag']}")

Parameters

Parameter	Type	Required	Description
mailbox_id	str	✅	Mailbox identifier

---

Delete Mailbox

Delete a single mailbox. If created with recoverable=True, it will be archived.

client.delete_mailbox("mb_abc123")
print("Mailbox deleted")

Parameters

Parameter	Type	Required	Description
mailbox_id	str	✅	Mailbox identifier

Returns

None (returns None on success)

---

Delete Multiple Mailboxes (Bulk)

NEW in v1.0.0: Delete multiple mailboxes in a single atomic operation.

# Delete multiple mailboxes at once
client.delete_mailboxes([
    "mb_abc123",
    "mb_def456",
    "mb_ghi789"
])

print("All mailboxes deleted")

Parameters

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

Returns

None (returns None on success)

Notes

• Recoverable mailboxes will be archived before deletion
• Non-recoverable mailboxes will be permanently deleted
• Operation is atomic: all mailboxes are validated before any deletion occurs
• If any validation fails, the entire operation is rejected (no partial deletions)
• All emails and attachments in the mailboxes are also deleted

---

Complete Example

from minutemail import MinuteMailClient, APIError
import time

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

try:
    # Create a recoverable mailbox
    mailbox = client.create_mailbox(
        domain="minutemail.cc",
        expires_in=60,  # 1 hour (integer in minutes)
        recoverable=True,
        tag="email-verification"
    )

    print(f"✓ Created mailbox: {mailbox['address']}")

    # Wait for an email (simplified polling)
    max_attempts = 10
    for attempt in range(max_attempts):
        mails = client.list_mails(mailbox["id"])
        if mails["items"]:
            print(f"✓ Received {len(mails['items'])} email(s)")
            break
        time.sleep(5)  # Poll every 5 seconds

    # Clean up
    client.delete_mailbox(mailbox["id"])
    print("✓ Mailbox deleted")

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