Email API

Managed email API

Current documentation

Connect a backend, Claude, or another agent to tenant-safe domains, mailboxes, threads, and sends.

One key, one workspace

Send the workspace API key in x-api-key on every /v1/email/* request. The key resolves the workspace on Beam's server. There is no tenant id in the request body and no way to ask for another workspace.

Server-side onlyNever put a workspace key in browser JavaScript, a public agent prompt, a client-side Claude artifact, source control, logs, or screenshots. Store it in the calling system's secret manager.

Available operations

Method	Path	Purpose
GET	`/v1/email/plan`	Read plan, usage, cap, and the public catalog.
GET / POST	`/v1/email/domains`	List or provision a workspace-owned domain.
POST	`/v1/email/domains/:id/verify`	Request verification and perform provider read-back.
GET / POST	`/v1/email/mailboxes`	List or create identities on an owned domain.
GET	`/v1/email/threads`	List email threads for the workspace.
GET	`/v1/email/threads/:id`	Read one owned thread and its timeline.
POST	`/v1/email/messages`	Start a one-to-one email thread.
POST	`/v1/email/threads/:id/messages`	Reply on an owned thread.
POST	`/v1/email/threads/:id/takeover`	Pause or deliberately resume the assistant.

Send example

curl -X POST https://beam.aisync.link/v1/email/messages \
  -H "x-api-key: $BEAM_WORKSPACE_KEY" \
  -H "content-type: application/json" \
  -d '{"domain_id":"12","mailbox_id":"18","to":"lead@example.com","subject":"Following up","text":"Hi Maya — here is the information you asked for.","request_key":"crm-contact-847:follow-up-1"}'

const response = await fetch("https://beam.aisync.link/v1/email/messages", {
  method: "POST",
  headers: { "x-api-key": process.env.BEAM_WORKSPACE_KEY, "content-type": "application/json" },
  body: JSON.stringify({ domain_id: "12", mailbox_id: "18", to: "lead@example.com", subject: "Following up", text: "Hi Maya — here is the information you asked for.", request_key: "crm-contact-847:follow-up-1" }),
});

Idempotency and delivery truth

request_key is required for sends. Reuse the same key for a retry of the same business action; Beam returns the original record and does not consume another allowance unit. A 202 response means queued, not delivered. Use the thread timeline and signed events for final state. Never automatically retry delivery_unknown.

Claude and agent use

Give the agent the LLM documentation corpus and OpenAPI contract, but inject the workspace key only into a protected server tool. Require approval for domain changes and live sends. Human takeover must call the takeover endpoint before the agent stops working the thread.