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/sdk installed in your project.

npm install @anima/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/sdk';
 
const am = new Anima(process.env.AM_API_KEY);
 
const agent = await am.identities.create({
  name: "Customer-Support-Bot-01",
  capabilities: ['email']
});

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: Stalwart receives inbound mail and AWS SES sends outbound mail. That means your custom-domain DNS will point MX at the Stalwart mail host, while SPF and DKIM stay aligned with SES for outbound delivery.

const email = await agent.email.provision({
  domain: "agents.yourcompany.com",
  prefix: "support-01"
});
 
console.log(`Email address provisioned: ${email.address}`);

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 agent.email.send({
  to: "user@example.com",
  subject: "Your Ticket #123 is Resolved",
  body: "Hello, we have processed your request. Thank you for your patience."
});
 
if (sent.success) {
  console.log(`Email sent! Message ID: ${sent.messageId}`);
}

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 Stalwart, 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 real cloud infrastructure is SES outbound delivery. To send real email externally, you still need an SES-verified domain, IAM credentials, and production access in your target AWS region.

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!