Zemail Python SDK

The official Python SDK for the Zemail Developer API. Create and manage temporary mailboxes, receive emails, and handle attachments programmatically.

Requirements

• Python 3.9 or higher
• httpx >= 0.24.0
• pydantic >= 2.0.0

Installation

Install the package via pip:

pip install zemail-python

Or install the latest development version directly from GitHub:

pip install git+https://github.com/zemailme/zemail-python.git

Quickstart

Initialize the ZemailClient with your API key:

from zemail import ZemailClient

client = ZemailClient(api_key="zm_live_your_api_key_here")

You can optionally specify an API version, timeout, custom headers, or use it as a context manager:

from zemail import ZemailClient

with ZemailClient(
    api_key="zm_live_your_api_key_here",
    version="2026-04-23",
    timeout=10.0,
    headers={"X-Custom-Header": "value"},
) as client:
    account = client.account.get()
    print(f"Logged in as: {account.email}")

Usage

1. Account & Subscription

Access your account profile, active subscription plan, and API/mailbox usage limits:

# Get account profile
account = client.account.get()
print(f"Account ID: {account.id}, Email: {account.email}, Tier: {account.tier}")

# Get active subscription
subscription = client.account.subscription()
print(f"Status: {subscription.status}, Tier: {subscription.tier}")

# Get current resource & API usage
usage = client.account.usage()
print("Mailbox Usage:", usage.mailboxes)
print("Storage Usage:", usage.storage)
print("Developer API Usage:", usage.developer_api)

2. Domains

List available domains for mailbox creation:

domains = client.domains.list()

for domain in domains.data:
    print(f"Domain: {domain.name} (Types: {', '.join(domain.allowed_types)})")

3. Mailboxes

List Mailboxes

mailboxes = client.mailboxes.list(page=1, limit=10)

for mailbox in mailboxes.data:
    print(f"Mailbox: {mailbox.address} (ID: {mailbox.id})")

if mailboxes.has_more:
    print(f"Next cursor: {mailboxes.next_cursor}")

Create a Random Mailbox

mailbox = client.mailboxes.create(type="random")
print(f"Created random mailbox: {mailbox.address}")

Create a Custom Mailbox

mailbox = client.mailboxes.create(
    type="custom",
    domain="zemail.me",
    username="my-inbox",
)
print(f"Created custom mailbox: {mailbox.address}")

Get Mailbox Details

mailbox = client.mailboxes.get(mailbox_id=123)
print(f"Address: {mailbox.address}, Unread emails: {mailbox.unread_count}")

Delete a Mailbox

deleted = client.mailboxes.delete(mailbox_id=123)
print(f"Mailbox deleted: {deleted.deleted}")

4. Emails & Attachments

List Emails in a Mailbox

# List emails with optional search query and pagination
emails = client.emails.list(
    mailbox_id=mailbox.id,
    page=1,
    limit=25,
    search="verification",
)

for email in emails.data:
    print(f"[{email.id}] From: {email.sender} | Subject: {email.subject}")

Tip: You can also access email methods via client.mailboxes.emails:

emails = client.mailboxes.emails.list(mailbox_id=mailbox.id)

Get Full Email Details

email = client.emails.get(mailbox_id=mailbox.id, email_id=email_id)

print(f"Subject: {email.subject}")
print(f"Plain text body: {email.body_text}")
print(f"HTML body: {email.body_html}")

# Inspect attachments
for attachment in email.attachments:
    print(f"Attachment: {attachment.name} ({attachment.size} bytes)")

Mark Email as Read

read_state = client.emails.mark_as_read(mailbox_id=mailbox.id, email_id=email_id)
print(f"Is read: {read_state.is_read}")

Get Temporary Attachment Download URL

download = client.emails.get_attachment_download_url(
    mailbox_id=mailbox.id,
    email_id=email_id,
    attachment_id="att_123",
)

print(f"Download URL: {download.url}")
print(f"Expires at: {download.expires_at}")

Delete an Email

deleted = client.emails.delete(mailbox_id=mailbox.id, email_id=email_id)
print(f"Email deleted: {deleted.deleted}")

Error Handling

All SDK exceptions inherit from ZemailAPIError (which subclasses ZemailError):

from zemail import (
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ValidationError,
    ZemailAPIError,
    ZemailClient,
)

client = ZemailClient(api_key="zm_live_...")

try:
    mailbox = client.mailboxes.create(type="custom")
except ValidationError as e:
    print(f"Validation failed: {e.message}")
    print("Errors:", e.errors)
except AuthenticationError as e:
    print(f"Auth error: {e.message}")
except RateLimitError as e:
    print(f"Rate limited: {e.message}")
except NotFoundError as e:
    print(f"Not found: {e.message}")
except ZemailAPIError as e:
    print(f"API error [{e.status}]: {e.message}")

Development & Testing

Run unit tests with pytest:

pytest

Run linting and type checks with ruff:

ruff check .
ruff format --check .

Format code with ruff:

ruff format .

License

The MIT License (MIT). Please see LICENSE for more information.