Give Swarm agents email capabilities that persist across handoffs — with MultiMail's oversight ensuring every send is gated regardless of which agent triggers it.
OpenAI Swarm is an experimental framework for lightweight multi-agent orchestration using function-based routing and agent handoffs. When email tasks pass through a handoff chain — from a triage agent to a support agent to a follow-up agent — MultiMail ensures oversight is enforced at every step.
Swarm's handoff pattern means an email action might be initiated by one agent and completed by another. MultiMail's API-level oversight catches every send call regardless of which agent in the chain makes it, preventing oversight gaps during agent transitions.
Integration is natural: define email functions that call the MultiMail REST API, then pass them as tools to your Swarm agents. The functions follow Swarm's convention of returning strings for the next agent to process.
Swarm agents hand off tasks to each other. MultiMail's API-level oversight ensures that email sends are gated regardless of which agent in the chain initiates the action — no oversight gaps during transitions.
Swarm's context_variables carry state across handoffs. Store mailbox IDs, thread IDs, and email context in context_variables so agents downstream in the chain have the information they need for email actions.
Swarm uses plain Python functions as tools, matching exactly how you define MultiMail API wrappers. No adapters or special integrations needed — just define functions and pass them to agents.
Different Swarm agents can use different mailboxes. A sales agent sends from the sales mailbox while a support agent uses the support mailbox, each with appropriate oversight settings.
import requests
MULTIMAIL_API = "https://api.multimail.dev/v1"
HEADERS = {"Authorization": "Bearer mm_live_your_api_key"}
def send_email(context_variables: dict, to: str, subject: str, body: str) -> str:
"""Send an email via MultiMail. Uses gated_send mode by default."""
mailbox_id = context_variables.get("mailbox_id")
resp = requests.post(f"{MULTIMAIL_API}/send", headers=HEADERS, json={
"mailbox_id": mailbox_id,
"to": to,
"subject": subject,
"body": body
})
result = resp.json()
return f"Email queued for approval: {result.get(&"cm">#039;id', 'unknown')}"
def check_inbox(context_variables: dict) -> str:
"""Check the inbox for the current mailbox."""
mailbox_id = context_variables.get("mailbox_id")
resp = requests.get(
f"{MULTIMAIL_API}/mailboxes/{mailbox_id}/inbox",
headers=HEADERS,
params={"limit": 10}
)
return str(resp.json())
def reply_email(context_variables: dict, message_id: str, body: str) -> str:
"""Reply to an email within its thread."""
resp = requests.post(f"{MULTIMAIL_API}/reply", headers=HEADERS, json={
"message_id": message_id,
"body": body
})
return str(resp.json())Create email functions following Swarm's convention of accepting context_variables and returning strings.
from swarm import Swarm, Agent
client = Swarm()
def transfer_to_support():
return support_agent
def transfer_to_followup():
return followup_agent
triage_agent = Agent(
name="Triage Agent",
instructions=(
"You triage incoming emails. Check the inbox, read messages, "
"and hand off to the support agent for responses. "
"Use check_inbox to see new messages."
),
functions=[check_inbox, transfer_to_support]
)
support_agent = Agent(
name="Support Agent",
instructions=(
"You handle customer support emails. Draft professional "
"replies using reply_email. All replies go through "
"gated_send mode for human approval. Hand off to "
"follow-up agent for scheduling."
),
functions=[reply_email, transfer_to_followup]
)
followup_agent = Agent(
name="Follow-up Agent",
instructions=(
"You send follow-up emails to ensure customer satisfaction. "
"Use send_email to compose follow-ups. All emails are "
"queued for human approval before delivery."
),
functions=[send_email]
)Build a Swarm with triage, support, and follow-up agents that hand off email tasks.
response = client.run(
agent=triage_agent,
messages=[{
"role": "user",
"content": "Check the support inbox and handle any "
"customer inquiries that need responses."
}],
context_variables={
"mailbox_id": "your_support_mailbox_id",
"current_thread": None,
"oversight_mode": "gated_send"
}
)
print(f"Final agent: {response.agent.name}")
print(f"Response: {response.messages[-1][&"cm">#039;content']}")
"cm"># The handoff chain might look like:
"cm"># 1. Triage Agent checks inbox via MultiMail API
"cm"># 2. Triage Agent hands off to Support Agent
"cm"># 3. Support Agent drafts reply (queued for approval)
"cm"># 4. Support Agent hands off to Follow-up Agent
"cm"># 5. Follow-up Agent sends follow-up (also queued)Execute the swarm with context variables carrying mailbox and thread state.
Sign up at multimail.dev, create a mailbox, and generate an API key from your dashboard. Your key will start with mm_live_.
Install the OpenAI Python package (which includes Swarm) and the HTTP library for API calls.
pip install openai requestsCreate functions that accept context_variables and call MultiMail API endpoints. Follow Swarm's convention of returning strings.
Define Swarm Agent instances with appropriate email functions and handoff transfer functions. Include oversight mode details in each agent's instructions.
Review emails queued by any agent in the Swarm chain via the MultiMail dashboard. Approve or reject before delivery.
Email infrastructure built for AI agents. Verifiable identity, graduated oversight, and a 38-tool MCP server. Formally verified in Lean 4.