> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usglobalmail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server.

# Python SDK

## Install

```bash
pip install usgm
```

Requires Python 3.8+.

## Initialize

```python
import os
from usgm import Usgm

usgm = Usgm(token=os.environ["USGM_API_KEY"])  # never hard-code the key
```

## Usage

```python
# Your account profile
account = usgm.account.get()
print(account.email, account.status)

# List mail, one page at a time (cursor pagination)
cursor = None
while True:
    page = usgm.mails.list(cursor=cursor)
    for mail in page.data:
        print(mail.id, mail.sender_name)
    cursor = page.next_cursor
    if cursor is None:
        break

# Fetch one item
mail = usgm.mails.get(id="80421")

# Create a folder
folder = usgm.folders.create(name="Taxes")
```

## Async

```python
import asyncio
from usgm import AsyncUsgm

usgm = AsyncUsgm(token=os.environ["USGM_API_KEY"])

async def main():
    page = await usgm.mails.list()
    for mail in page.data:
        print(mail.id)

asyncio.run(main())
```

## Error handling

```python
from usgm.core.api_error import ApiError

try:
    usgm.mails.get(id="does-not-exist")
except ApiError as err:
    # `body` is the RFC 9457 problem+json payload (code, request_id, detail, …)
    print(err.status_code, err.body)
    raise
```

> **Note**
>
> Transient `429` and `5xx` responses are retried automatically with exponential backoff. See
> [Errors](/guides/core-concepts/errors) for the full problem+json contract.