Email for an OpenAI Agents SDK agent

Register

The response carries the address and an API key that is shown exactly once.

Wait a couple of seconds before the first send while the mailbox is provisioned.

# Once, outside the agent: give it an address and keep the key
curl -s -X POST https://api.mailgi.xyz/v1/agents/register \
  -H "Content-Type: application/json" -d '{"label":"my-agent"}'
# => {"emailAddress":"buzzing-falcon@mailgi.xyz","apiKey":"amb_..."}

export MAILGI_API_KEY=amb_...   # shown once: store it

The three tools

Docstrings become the tool descriptions the model sees, so keep them short and literal.

from is a list of objects; the address is m['from'][0]['email']. Treating it as a string is the most common mistake with this API.

A 402 comes back as text with a top-up link rather than an exception, so the model can explain it.

import os, time, requests

API = "https://api.mailgi.xyz"
KEY = os.environ["MAILGI_API_KEY"]
H = {"Authorization": f"Bearer {KEY}"}


def send_email(to: str, subject: str, body: str) -> str:
    """Send a plain-text email from the agent's own address."""
    r = requests.post(f"{API}/v1/mail/send", headers=H,
                      json={"to": [to], "subject": subject, "textBody": body})
    if r.status_code == 402:
        return "Not sent: balance too low. Top up: " + r.json()["error"]["details"]["topupPage"]
    r.raise_for_status()
    return f"Sent, message id {r.json()['messageId']}"


def list_inbox(limit: int = 10) -> str:
    """List the newest messages: id, sender, subject, preview."""
    r = requests.get(f"{API}/v1/mail", headers=H, params={"limit": limit})
    r.raise_for_status()
    return "\n".join(
        f"{m['id']} | {m['from'][0]['email']} | {m['subject']} | {m['preview'][:80]}"
        for m in r.json()["messages"]) or "Inbox is empty."


def read_email(message_id: str) -> str:
    """Read one message's full text."""
    r = requests.get(f"{API}/v1/mail/{message_id}", headers=H)
    r.raise_for_status()
    m = r.json()
    body = m.get("textBody") or m.get("htmlBody") or ""
    if isinstance(body, list):  # JMAP parts
        body = "".join(m["bodyValues"][p["partId"]]["value"] for p in body)
    return f"From: {m['from'][0]['email']}\nSubject: {m['subject']}\n\n{body}"