minutemail-sdk 1.0.0

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

MinuteMail Python SDK

Python client for the MinuteMail public API gateway (/v1). It handles auth headers, request wiring, and attachment encoding so you can focus on product logic.

Installation

pip install -e .

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",
    base_url="https://api.minutemail.cc",  # or http://localhost:8080 for local
)

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)

Client classes

• MinuteMailClient: Production-safe surface for managing mailboxes, reading mail, and deleting data.

Constructor parameters

• api_key (str, required): Tenant-scoped API key used for all authenticated calls.
• base_url (str, default https://api.minutemail.cc): Gateway origin (no /v1 suffix).
• timeout (float, default 10.0): Per-request timeout in seconds.
• session (requests.Session, optional): Provide to reuse connections/custom adapters.

MinuteMailClient methods (production)

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).

Health

• health() → {"ok":true}. No auth header sent.
• ready() → readiness payload. No auth header sent.

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)

Configuration notes

• base_url should be the gateway origin (no /v1 suffix). Default: https://api.minutemail.cc.
• expires_in mirrors the API: Go-style durations like 15m, 2h, or integer minutes.
• Attachments: strings are UTF-8 encoded then base64 encoded; override size_bytes if the decoded size is already known.

Development

1. Create a virtualenv and install dependencies: pip install -e .
2. Point base_url at your running gateway (http://localhost:8080).
3. Run your scripts/tests using your API key.

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