Set Up Agent Email in Five Minutes with Anima

Why Agent-Specific Email?#

When building autonomous agents, you shouldn't use your personal or corporate email address. You need a deterministic, dedicated mailbox for every agent to receive receipts, confirmation codes, and support tickets. Anima provides this infrastructure as a native primitive of the agent's identity.

Step 1: Install the SDK#

Ensure you have the latest version of the @anima-labs/sdk installed in your project.

npm install @anima-labs/sdk

Step 2: Initialize the Identity#

Every email address is tied to an Anima identity. Create one with the email capability enabled.

import { Anima } from '@anima-labs/sdk';
 
const anima = new Anima({ apiKey: process.env.ANIMA_API_KEY! });
 
const agent = await anima.agents.create({
  orgId: process.env.ANIMA_ORG_ID!,
  name: "Customer Support Bot 01",
  slug: "support-01"
});

Step 3: Configure Your Domain#

You can use a custom domain or a subdomain managed by Anima. We'll use a custom domain for this example.

Under the hood, Anima uses a hybrid architecture: mail infrastructure we run ourselves receives inbound mail, and a specialist delivery provider sends outbound mail. That means your custom-domain DNS will point MX at our inbound mail host, while SPF and DKIM stay aligned with the outbound sender.

Every agent gets an address on agents.useanima.sh the moment it is created — there is no separate provisioning call:

console.log(agent.emailIdentities[0]?.email);
// support-01@agents.useanima.sh

To use your own domain instead, register it once and publish the records it returns:

const domain = await anima.domains.add({ domain: "agents.yourcompany.com" });
 
const records = await anima.domains.dnsRecords(domain.id);
console.log(records); // MX, SPF, DKIM to publish
 
// Once the records are live:
await anima.domains.verify(domain.id);

Step 4: Sending Your First Email#

Sending an email from your agent is a simple method call. The SDK handles all the SPF/DKIM/DMARC headers automatically.

const sent = await anima.messages.sendEmail({
  agentId: agent.id,
  to: ["user@example.com"],
  subject: "Your Ticket #123 is Resolved",
  body: "Hello, we have processed your request. Thank you for your patience."
});
 
console.log(`Email sent! Message ID: ${sent.id}`);

Step 5: Handling Incoming Email#

Incoming emails are delivered via webhooks. The Anima SDK provides a convenient way to listen for these events.

agent.on('email:received', async (mail) => {
  console.log(`New email from ${mail.from}: ${mail.subject}`);
  
  // Use the parsed data to trigger your agent's reasoning loop
  const summary = await agent.summarize(mail.text);
  console.log(`Summary: ${summary}`);
});

Advanced: Inbound Routing and Webhooks#

If you are not using the SDK's built-in event listeners, you can configure a direct webhook URL in the Anima dashboard or via the API.

await agent.email.updateConfig({
  webhookUrl: "https://your-api.com/webhooks/agent-mail",
  secret: process.env.WEBHOOK_SECRET
});

Local Testing#

You can test most of this flow locally by running ./start.sh from the repository root. That boots the mail server, Postgres, Redis, the API, and the dashboard so you can validate mailbox provisioning, domain setup UX, and inbound processing.

The one piece that still needs a real cloud account is outbound delivery. To send real email externally you need an API key for the outbound provider — see .env.example for the exact variable — plus a verified sending domain, using the DKIM and SPF records the domain wizard hands you. Inbound needs nothing extra: the local stack handles it.

Summary#

In less than five minutes, you've provisioned a professional, deterministic email address for your agent. No more managing separate SMTP credentials or struggling with complex inbound parsing logic. Anima treats email as a core component of your agent's identity, making it easier than ever to build agents that communicate effectively in the real world.

For more information, visit our Custom Domains Documentation. Happy sending!