OpenAI Assistants API with Email: Add Inbox Tools to Your Assistant

The OpenAI Assistants API supports function calling, which lets your assistant invoke external APIs. Adding email capabilities takes about 10 minutes.

Define the Functions

const tools = [
  {
    type: "function",
    function: {
      name: "create_inbox",
      description: "Create a new email inbox for the agent",
      parameters: {
        type: "object",
        properties: {
          name: { type: "string", description: "Optional inbox name" }
        }
      }
    }
  },
  {
    type: "function",
    function: {
      name: "wait_for_otp",
      description: "Wait for an OTP verification code to arrive in an inbox",
      parameters: {
        type: "object",
        required: ["inbox_id"],
        properties: {
          inbox_id: { type: "string" },
          timeout: { type: "number", default: 60 }
        }
      }
    }
  },
  {
    type: "function",
    function: {
      name: "send_email",
      description: "Send an email from an inbox",
      parameters: {
        type: "object",
        required: ["inbox_id", "to", "subject", "text"],
        properties: {
          inbox_id: { type: "string" },
          to: { type: "string" },
          subject: { type: "string" },
          text: { type: "string" }
        }
      }
    }
  }
];

Handle Function Calls

const API = "https://api.agentmailr.com";
const KEY = process.env.AGENTMAILR_API_KEY;
const h = { "X-API-Key": KEY, "Content-Type": "application/json" };

async function handleToolCall(name, args) {
  if (name === "create_inbox") {
    const r = await fetch(`${API}/v1/inboxes`, { method: "POST", headers: h, body: JSON.stringify(args) });
    return r.json();
  }
  if (name === "wait_for_otp") {
    const r = await fetch(`${API}/v1/inboxes/${args.inbox_id}/otp?timeout=${args.timeout || 60}`, { headers: h });
    return r.json();
  }
  if (name === "send_email") {
    const r = await fetch(`${API}/v1/inboxes/${args.inbox_id}/send`, { method: "POST", headers: h, body: JSON.stringify(args) });
    return r.json();
  }
}

Create the Run

const run = await openai.beta.threads.runs.create(threadId, {
  assistant_id: assistantId,
  tools
});
// Poll for required_action, call handleToolCall, submit outputs...

What Your Assistant Can Now Do

With these three functions, your assistant can autonomously register for web services, complete email verification, and send messages. This is the foundation for agents that can act on the open web.