Skip to main content

​
Email

Every Anima agent has a real email inbox. You can send outbound messages, read received messages, search the inbox, and subscribe to delivery events via webhooks.
Agents on a shared Anima domain send from agent-name@useanima.sh by default. Add a custom domain to send from your own brand, such as agent@yourcompany.com.

​
Send an email

from anima import Anima

anima = Anima(api_key="ak_...")

anima.messages.send_email(
    agent_id="ag_01abc123",
    to="user@example.com",
    subject="Your order has shipped",
    body="Hi — your order is on its way and will arrive by Friday.",
)

​
Parameters

​
agent_id
string
required
The ID of the agent sending the email. Must begin with ag_.
​
to
string
required
The recipient email address.
​
subject
string
required
The email subject line.
​
body
string
required
The plain-text body of the email.

​
List messages

Retrieve the messages in an agent’s inbox: 
messages = anima.messages.list(agent_id="ag_01abc123")
for msg in messages:
    print(f"{msg.subject}  from={msg.from_}")

​
Search the inbox

results = anima.messages.search(
    agent_id="ag_01abc123",
    query="invoice",
)
for msg in results:
    print(msg.subject)

​
Inboxes

Each agent has a default inbox. You can list all inboxes for an agent or fetch a specific one.

​
List inboxes

inboxes = anima.inboxes.list(agent_id="ag_01abc123")
for inbox in inboxes:
    print(f"{inbox.id}  {inbox.address}")

​
Get an inbox

inbox = anima.inboxes.get(
    agent_id="ag_01abc123",
    inbox_id="inbox_xyz",
)
print(inbox.address)

​
Webhook events

Subscribe to email events by configuring a webhook in the dashboard. When an agent receives a new message, Anima posts a message.received payload to your endpoint: 
{
  "event": "message.received",
  "data": {
    "id": "msg_12345",
    "agent_id": "ag_01abc123",
    "from": "user@example.com",
    "subject": "Re: Your order has shipped",
    "body": "Thanks, looking forward to it!",
    "timestamp": "2024-03-15T10:30:00Z"
  }
}
See Webhooks for the full list of event types and how to verify request signatures.