Guides

Reading the Inbox

The SDK exposes raw paginated readers (list_inbox, iter_inbox_pages), single-message accessors (get_message), and a higher-level helper (fetch_message / iter_inbox) that polls attachments and decrypts OpenPGP bodies in one call.

Single page#

python

page = client.list_inbox(limit=25)
for item in page.get("items", []):
    msg_id   = item["MessageID"]
    verified = item["SenderVerified"]
    print(msg_id, verified)

All pages (auto-pagination)#

python

for page in client.iter_inbox_pages(page_size=50, verified_only=True):
    for item in page.get("items", []):
        process(item)

iter_inbox_pages yields each page dict until there is no next_cursor.

Fetch a full message#

python

msg = client.get_message(message_id)
print(msg["raw_mime"])           # full RFC 5322 MIME string
print(msg["Sender"])             # envelope sender
print(msg["SenderVerified"])     # bool

fetch_message and iter_inbox#

fetch_message wraps get_message, polls each inbound attachment until it is ready, downloads the bytes, and — when you supply decrypt_with — transparently decrypts any body or attachments that arrived OpenPGP-encrypted.

python

import os

msg = client.fetch_message(
    message_id,
    download_dir="./inbox",
    include_attachments=True,
    decrypt_with=my_private_key_armored,
    passphrase=os.environ.get("AGENTMAIL_PGP_PASSPHRASE"),
    poll_interval_seconds=2.0,
    max_poll_seconds=60.0,
)

print(msg.get("body_text_decrypted") or msg["body_text"])
for att in msg["downloaded_attachments"]:
    print(att["index"], att["filename"], att["status"], att.get("path"))

Each downloaded_attachments entry has:

index, filename, content_type, status — mirror the manifest row.
path — set when download_dir is provided; otherwise bytes holds the raw payload in memory.
encrypted — true if the blob was delivered OpenPGP-armored.
decrypted — true if decrypt_with was supplied and decryption succeeded.
error — populated on failure (poll_timeout, decrypt_failed: ..., etc.).

To sweep the whole inbox and auto-decrypt each message:

python

for msg in client.iter_inbox(
    download_dir="./inbox",
    decrypt_with=my_private_key_armored,
    passphrase=os.environ.get("AGENTMAIL_PGP_PASSPHRASE"),
    verified_only=True,
):
    process(msg)

iter_inbox delegates paging to iter_inbox_pages and yields fully hydrated messages one at a time.

Deleting a message#

python

client.delete_message(message_id)

Need to react to inbound mail without polling? Configure a webhook instead.