Send email from a Vercel AI SDK agent

Give an AI SDK agent the Unitpost send tool through the AI SDK MCP client, or one typed tool that calls the REST API. Either way your server code holds a send-only key and decides which sends go out.

1. 1

   Create a send-only key

   Open https://www.unitpost.com → Settings → API keys and create a key with Sending only permissions. On a paid plan, open Advanced and keep only emails:send, so the key can send email and do nothing else. Copy the pk_live_… value (shown once) into the environment your agent runs in.

   Shell

   export UNITPOST_API_KEY=pk_live_YOUR_KEY

   A Sending only key can also send campaigns and read contacts, segments, templates and domains. Keep the key in your server code: the model never needs to see it.

2. 2

   Connect the AI SDK MCP client

   Install ai and @ai-sdk/mcp. createMCPClient connects over streamable HTTP with your key as a Bearer header. ?toolsets=sending keeps the server's list to sending tools, and the agent gets one of them: email_send.

   TypeScript

   import { createMCPClient } from "@ai-sdk/mcp";
   import { generateText, isStepCount } from "ai";
   
   const mcp = await createMCPClient({
     transport: {
       type: "http",
       url: "https://mcp.unitpost.com/mcp?toolsets=sending",
       headers: { Authorization: `Bearer ${process.env.UNITPOST_API_KEY}` },
     },
   });
   
   try {
     const { email_send } = await mcp.tools();
     const result = await generateText({
       model: "anthropic/claude-sonnet-5.5", // any model the AI SDK supports
       tools: { email_send },
       stopWhen: isStepCount(5),
       prompt: "Email ada@example.com from hi@yourdomain.com: the report is ready.",
     });
     console.log(result.text);
   } finally {
     await mcp.close();
   }

   email_send takes an idempotency_key beside body. Tell the agent to pass a new one per message and the same one on a retry: the server's instructions say so too.

3. 3

   Or add one REST send tool

   No MCP client needed: one typed tool() that posts to /api/v1/email. Your code holds the key, checks the recipient, and sends the result or the error envelope back to the model.

   TypeScript

   import { tool } from "ai";
   import { z } from "zod";
   
   const ALLOWED = new Set(["ada@example.com"]); // who this agent may email
   
   export const sendEmail = tool({
     description: "Send one email through Unitpost.",
     inputSchema: z.object({
       from: z.string().describe("Sender on a verified domain, e.g. Acme <hi@acme.com>"),
       to: z.string().describe("One recipient address"),
       subject: z.string(),
       text: z.string().describe("Plain-text body"),
       idempotency_key: z.string().describe("A new value for each message; the same value when retrying this one"),
     }),
     execute: async (email) => {
       if (!ALLOWED.has(email.to)) return { refused: `${email.to} is not on the allowlist` };
       const { idempotency_key, ...message } = email;
       const body = JSON.stringify(message);
       const res = await fetch("https://www.unitpost.com/api/v1/email", {
         method: "POST",
         headers: {
           Authorization: `Bearer ${process.env.UNITPOST_API_KEY}`,
           "Content-Type": "application/json",
           "User-Agent": "my-agent/1.0",
           "Idempotency-Key": idempotency_key, // the model's: a retry of this message reuses it
         },
         body,
       });
       return res.json(); // { id, status, scheduled_at } or { error: { code, message, details } }
     },
   });

   The model passes idempotency_key: a new one per message, and the same one when it retries that message, so a lost response never becomes a second email. A key made inside the tool would change on every retry. Never derive it from the content, or two separate identical notifications become one. User-Agent is required: a request without one is refused with missing_user_agent (403).

4. 4

   Gate each send

   Every send is real mail to a real person. Send only transactional mail or mail people opted in to: the Acceptable Use Policy rules out cold outreach. Check each recipient against an allowlist, or have a person approve the send, before the call goes out. Pass an idempotency key, and the same key on a retry: for 24 hours a retry returns the first result instead of sending twice. In the AI SDK, toolApproval decides per call: deny any recipient off the allowlist and ask a person about the rest. The result then holds a tool-approval-request; answer it with a tool-approval-response and call generateText again.

   TypeScript

   const ALLOWED = new Set(["ada@example.com"]);
   
   const result = await generateText({
     model: "anthropic/claude-sonnet-5.5",
     tools: { email_send },
     prompt,
     toolApproval: ({ toolCall }) => {
       const body = (toolCall.input as { body?: Record<string, string | string[]> }).body ?? {};
       const recipients = [body.to, body.cc, body.bcc].flat().filter(Boolean) as string[];
       return recipients.length > 0 && recipients.every((a) => ALLOWED.has(a))
         ? "user-approval"
         : { type: "denied", reason: "A recipient is not on the allowlist." };
     },
   });
   
   for (const part of result.content) {
     if (part.type === "tool-approval-request" && !part.isAutomatic) {
       console.log("Approve this send?", part.toolCall.input); // show a person, then reply
     }
   }

   Errors come back as { "error": { "code", "message", "details" } }. Branch on error.code and fix the call instead of resending it: domain_not_verified means the from domain isn't verified, validation_error names the bad fields in details, and rate_limit_exceeded comes with a Retry-After wait. Over MCP the same error arrives under data, with a hint for the next move.

5. 5

   Verify the send

   Make the first send to an address you own, from an address on a verified domain. A success returns the email's id and a status of queued (scheduled when you set scheduled_at); over MCP the same object comes back under data. Open Emails in the dashboard to see the message, its recipient and its delivery status, or read it back with email_get (MCP) or GET /api/v1/email/{id}.

   JSON

   {
     "id": "email_…",
     "status": "queued",
     "scheduled_at": null
   }

   A retry with the same idempotency key returns this same body (REST adds Idempotent-Replayed: true) and sends nothing new.