minutemail-sdk 1.0.1

Official Python SDK for the MinuteMail API - 100% API coverage with full feature support.

MinuteMail Python SDK

Python SDK for automating temporary email workflows in testing and CI/CD environments. Create disposable mailboxes, retrieve emails programmatically, and test email-dependent features without exposing real user data.

Resources:

• Official Documentation
• MinuteMail Platform

Installation

pip install minutemail-sdk

Requirements: Python 3.9+ and requests>=2.31.0.

Authentication

Every authenticated call sends Authorization: Bearer <api-key>. Pass your tenant-scoped API key when constructing the client:

from minutemail import MinuteMailClient

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

Usage examples

Create and use a mailbox

from minutemail import MinuteMailClient, APIError

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

try:
    mailbox = client.create_mailbox(
        domain="minutemail.cc",
        recoverable=True,
        tag="onboarding",
        expires_in="20m",
    )
    print("Mailbox address:", mailbox["address"])

except APIError as exc:
    print("Request failed:", exc)

Fetch messages from a mailbox

# List all emails in the mailbox
mails = client.list_mails(mailbox_id="your-mailbox-id")
for mail in mails["items"]:
    print(f"From: {mail['from']}, Subject: {mail['subject']}")

# Get full email content
mail = client.get_mail(mailbox_id="your-mailbox-id", mail_id="mail-id")
print("Body:", mail["body"])
print("Has attachments:", mail["hasAttachments"])

Client classes

• MinuteMailClient: Client for managing mailboxes, reading mail, and deleting data.

Constructor parameters

• api_key (str, required): Tenant-scoped API key used for all authenticated calls.
• timeout (float, default 10.0): Per-request timeout in seconds.
• session (requests.Session, optional): Provide to reuse connections/custom adapters.

MinuteMailClient methods

Mailboxes

• list_mailboxes() → dict {items:[...]}; returns active mailboxes sorted by createdAt. Auth required.
• create_mailbox(domain, recoverable=None, tag=None, expires_in=None) → mailbox dict (201).
  • domain (str, required): Domain to use.
  • recoverable (bool, optional): When True, mailbox is archived on delete/expiry.
  • tag (str, optional): Required when recoverable=True.
  • expires_in (str, optional): TTL like "20m" or "2h".
• get_mailbox(mailbox_id) → mailbox dict.
  • mailbox_id (str, required).
• delete_mailbox(mailbox_id) → None (204).
  • mailbox_id (str, required).

Archived mailboxes

• list_archived_mailboxes() → dict {items:[...]} of archived mailbox records.
• get_archived_mailbox(archived_mailbox_id) → archived mailbox dict.
  • archived_mailbox_id (str).
• reactivate_archived_mailbox(archived_mailbox_id, expires_in=None) → newly created mailbox dict (201).
  • expires_in (str, optional): TTL for the new mailbox; defaults to service TTL.
• delete_archived_mailbox(archived_mailbox_id) → None (204).

Mails

• list_mails(mailbox_id) → dict {items:[...]} newest-first.
  • mailbox_id (str).
• get_mail(mailbox_id, mail_id) → mail dict including attachments summaries and hasAttachments.
  • mail_id (str).
• delete_mail(mailbox_id, mail_id) → None (204).

Attachments

• list_attachments(mailbox_id, mail_id) → dict {items:[...]} metadata only.
  • mail_id (str).
• get_attachment(mailbox_id, mail_id, attachment_id) → metadata + base64 data.
  • attachment_id (str).
• delete_attachment(mailbox_id, mail_id, attachment_id) → None (204).

Errors

• Network/timeouts raise TransportError.
• Non-2xx responses raise APIError with status_code, error, message, and a stringified response preview.

Example:

from minutemail import APIError

try:
    client.delete_mailbox("missing-id")
except APIError as exc:
    print(exc.status_code, exc.error, exc.message)

Contributing

1. Create a virtualenv and install: pip install -e .
2. Run your tests using your API key.

Planned: unit tests against a mocked gateway; semantic versioning for releases.