Mail¶

Ephemeral email for AI agents. Create a mailbox, send and receive, throw it away.

Create a mailbox¶

from primitif import mail

mb = mail.create_mailbox(name="support-agent", ttl=3600)
print(mb.address)  # support-agent-x7k2@mail.primitif.ai

name is optional (random if omitted). ttl is seconds until auto-expire. No TTL means the mailbox lives until you delete it.

Send email¶

mb.send("user@example.com", "Hello", "Hi from my agent")

Check inbox¶

for msg in mb.inbox():
    print(msg.from_address, msg.subject)
    detail = mb.read(msg)
    print(detail.body_text)

Reply¶

for msg in mb.inbox(unread_only=True):
    mb.reply(msg, "Got it, thanks!")

Threads¶

for thread in mb.threads():
    print(thread.subject, thread.participants)
    detail = mb.thread(thread)
    for msg in detail.messages:
        print(msg.from_address, msg.body_text)

Attachments¶

for att in mb.list_attachments(msg):
    print(att.filename, att.size_bytes)
    data = mb.download(att)
    with open(att.filename, "wb") as f:
        f.write(data)

Sender allowlist¶

# Open inbox to all senders
mb.add_allowlist("*")

# Or restrict to specific senders
mb.add_allowlist("trusted@example.com")

# List and remove
for entry in mb.get_allowlist():
    print(entry.sender_address)
mb.remove_allowlist(entry.id)

Webhooks¶

wh = mb.set_webhook("https://myapp.com/hook")
print(wh.secret)  # save — shown once

# Verify incoming webhooks
from primitif import verify_webhook

payload = verify_webhook(
    body=request.body,
    signature=request.headers["X-Webhook-Signature"],
    secret="whsec_...",
)

Send with human approval¶

result = mb.send(
    "ceo@bigclient.com",
    "Contract proposal",
    "Please find attached...",
    require_approval=True,
)
print(result.status)        # "held"
print(result.approval_url)  # link for a human

Protected recipients¶

mail.add_protected_recipient("ceo@bigcorp.com")
mail.add_protected_recipient("@sensitive-domain.com")
mail.list_protected_recipients()

Admin operations¶

# List all mailboxes
for mb in mail.list_mailboxes():
    print(mb.address, mb.received_count)

# Delete by ID
mail.delete_mailbox("mb_...")

# Account info
info = mail.account()
print(info.plan, info.mailbox_count)