openai assistants api email function calling: how to wire up real email delivery

{
  "name": "send_email",
  "description": "Send an email to a recipient with a subject and body",
  "parameters": {
    "type": "object",
    "properties": {
      "to": {
        "type": "string",
        "description": "Recipient email address"
      },
      "subject": {
        "type": "string",
        "description": "Email subject line"
      },
      "body": {
        "type": "string",
        "description": "Plain text email body"
      }
    },
    "required": ["to", "subject", "body"]
  }
}

Keep the descriptions clear. The model uses them to decide when and how to call the function. Vague descriptions produce vague arguments.

You can add multiple tools to a single assistant. If your agent needs to read emails too, define a `read_inbox` function alongside `send_email`. The model will pick the right one based on the user's message.

## Handling the run lifecycle

Once the user sends a message like "Send a follow-up email to dana@example.com about the Q2 report," you create a run. Here's what the polling loop looks like in practice:

```typescript
import OpenAI from "openai";

const openai = new OpenAI();

// Create run
let run = await openai.beta.threads.runs.create(threadId, {
  assistant_id: assistantId,
});

// Poll until the run needs action or completes
while (run.status === "queued" || run.status === "in_progress") {
  await new Promise((r) => setTimeout(r, 1000));
  run = await openai.beta.threads.runs.retrieve(threadId, run.id);
}

if (run.status === "requires_action") {
  const toolCalls =
    run.required_action.submit_tool_outputs.tool_calls;

  const outputs = [];

  for (const call of toolCalls) {
    const args = JSON.parse(call.function.arguments);

    if (call.function.name === "send_email") {
      const result = await sendEmailViaYourAPI(
        args.to,
        args.subject,
        args.body
      );
      outputs.push({
        tool_call_id: call.id,
        output: JSON.stringify(result),
      });
    }
  }

  // Submit results back
  await openai.beta.threads.runs.submitToolOutputs(threadId, run.id, {
    tool_outputs: outputs,
  });
}
The `requires_action` status is the handoff point. The model has decided it wants to send an email. It's extracted the recipient, subject, and body from the conversation. Now it's waiting for you to do the actual sending and report back.

That `sendEmailViaYourAPI` function is where the real decisions happen.

## The delivery problem most tutorials skip

Here's where I see people get stuck. They build the function calling loop, test it with `console.log`, and call it done. Then they wire up a real email backend and discover that sending email reliably is its own project.

If you're using raw SMTP or a personal Gmail account, you'll run into a familiar set of problems. You need SPF and DKIM records configured correctly or recipient servers will reject your messages. You need to handle rate limits. You need to monitor bounce rates because a spike in bounces damages your sender reputation, and once that's damaged, even valid emails start hitting spam folders.

For agents that send emails autonomously (without a human reviewing each one), these problems compound. A misconfigured agent can burn through a domain's reputation in hours. We've written about [the OAuth problem with Gmail](/blog/oauth-gmail-agents-painful) and why it creates so much friction for agent-based email workflows.

The pattern that works well for agent email is to let the agent itself provision and manage its own inbox. Instead of configuring OAuth tokens and SMTP credentials, the agent creates an inbox on demand and sends through authenticated infrastructure. This is the approach behind [agent self-signup](/blog/agent-self-signup-explained), where the agent handles its own email setup without human intervention.

## Wiring up a reliable email backend

Here's what the `sendEmailViaYourAPI` function can look like when you use LobsterMail as the delivery backend:

```typescript
import { LobsterMail } from "@lobsterkit/lobstermail";

const lm = await LobsterMail.create();
const inbox = await lm.createSmartInbox({ name: "Email Assistant" });

async function sendEmailViaYourAPI(
  to: string,
  subject: string,
  body: string
) {
  const result = await inbox.send({ to, subject, text: body });
  return {
    success: true,
    messageId: result.messageId,
    from: inbox.address,
  };
}

The agent gets its own `@lobstermail.ai` address. SPF and DKIM are handled automatically. No DNS configuration, no credential management, no OAuth consent screens. The agent provisions the inbox itself when the code first runs.

This fits naturally into the function calling pattern: the assistant decides to send an email, your function executes through authenticated infrastructure, and the result (including the message ID for tracking) goes back to the assistant.

## Adding a human approval step

One question that comes up often: should you let an LLM send emails without any human review? For internal notifications or transactional messages, autonomous sending is usually fine. For customer-facing emails or anything with legal implications, you probably want a human in the loop.

The Assistants API actually makes this easy. When the run hits `requires_action`, you don't have to submit tool outputs immediately. You can pause, surface the email draft to a human for approval, and only call the send function after they confirm. The run will wait.

```typescript
if (call.function.name === "send_email") {
  const args = JSON.parse(call.function.arguments);

  // Surface to human for approval
  const approved = await requestHumanApproval({
    to: args.to,
    subject: args.subject,
    body: args.body,
  });

  if (approved) {
    const result = await sendEmailViaYourAPI(
      args.to,
      args.subject,
      args.body
    );
    outputs.push({
      tool_call_id: call.id,
      output: JSON.stringify(result),
    });
  } else {
    outputs.push({
      tool_call_id: call.id,
      output: JSON.stringify({ success: false, reason: "Rejected by user" }),
    });
  }
}

async function sendEmailViaYourAPI(to, subject, body) {
  console.log("Would send:", { to, subject, body });
  return { success: true, messageId: "test-123" };
}