desplega-ai/agent-swarm/agentmail-sending

AgentMail Sending

Canonical Base URL

Use this base URL exactly:

https://api.agentmail.to/v0/

DO NOT use api.agentmail.ai. That host is a hallucination and will not send mail through AgentMail's current API.

Canonical Send-Message Fields

For POST /inboxes/{inbox}/messages/send, the JSON body fields are exactly:

to
bcc
subject
text

Use text, NOT text_body, body, or content.

Do NOT pass html. AgentMail has a known rendering bug: when html is passed with text, the HTML body can be empty and email clients may show a blank email. AgentMail renders text correctly on its own.

Rule 0: One-Shots Stay One-Shots

For a one-off send, such as a kickoff email or a single notification, do not create a reusable swarm-script. Use raw curl from Bash, or inline script_run if you need swarm-visible execution.

Only use script_upsert when the send will be reused by a workflow that fires repeatedly.

Default Example: Raw curl

Use this direct API call first. It does not assume any SDK is installed.

Endpoint:

https://api.agentmail.to/v0/inboxes/{inbox}/messages/send

INBOX="<agentmail-inbox-id>"
 
curl -sS -X POST "https://api.agentmail.to/v0/inboxes/${INBOX}/messages/send" \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "to": ["recipient@example.com"],
  "bcc": ["oversight@example.com"],
  "subject": "Subject line",
  "text": "Plain-text email body."
}
JSON

Notes:

• AGENTMAIL_API_KEY must be configured in swarm config or exported into the shell before running curl.
• Keep bcc for external recipients so a human oversight inbox sees outbound email.
• Do not add html; text is the canonical content field.

Reusable Workflow Example: script_upsert

Use this only when the send is part of a reusable workflow. The script resolves the API key from swarm config at runtime and calls the same raw HTTP endpoint with fetch.

await script_upsert({
  name: "send-agentmail-text-email",
  description: "Send a text-only AgentMail message from a reusable workflow.",
  intent: "Reusable workflow email send via AgentMail raw API",
  scope: "agent",
  source: `
import type { ScriptContext } from "swarm-sdk";
type Args = {
  inbox: string;
  to: string[];
  bcc: string[];
  subject: string;
  text: string;
};
export default async (args: Args, ctx: ScriptContext) => {
  const redactedKey = ctx.swarm.config.get('AGENTMAIL_API_KEY');
  if (!redactedKey) {
    throw new Error("AGENTMAIL_API_KEY is not configured in swarm config");
  }
  const apiKey = ctx.stdlib.Redacted.value(redactedKey);
  const response = await ctx.stdlib.fetch(
    \`https://api.agentmail.to/v0/inboxes/\${encodeURIComponent(args.inbox)}/messages/send\`,
    {
      method: "POST",
      headers: {
        Authorization: \`Bearer \${apiKey}\`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        to: args.to,
        bcc: args.bcc,
        subject: args.subject,
        text: args.text,
      }),
    },
  );
  const responseText = await response.text();
  if (!response.ok) {
    throw new Error(\`AgentMail send failed: \${response.status} \${responseText}\`);
  }
  return responseText ? JSON.parse(responseText) : { ok: true };
};
`,
});

Run it from a workflow with args shaped like:

{
  "inbox": "<agentmail-inbox-id>",
  "to": ["recipient@example.com"],
  "bcc": ["oversight@example.com"],
  "subject": "Subject line",
  "text": "Plain-text email body."
}

BCC Policy

All outbound emails to external recipients MUST include a human oversight email address in bcc. This gives the operator visibility into what the swarm sends.

Exception: internal emails between the swarm's own agent inboxes do not need BCC.

Human Approval

Never send outreach or cold emails to external recipients without explicit human approval. Draft the email, present it for review, and send only after receiving approval.

Checklist

Before every AgentMail send:

• Use https://api.agentmail.to/v0/.
• Use only to, bcc, subject, and text in the send-message JSON body.
• Use text, not text_body, body, or content.
• Do not pass html.
• BCC a human oversight address for external recipients.
• Get human approval for outreach or cold email.
• Use raw curl or inline script_run for one-offs; reserve script_upsert for reusable workflow sends.

Common Errors