io.github.anima-labs-ai/anima

Create a new agent with optional metadata, and optionally attach an initial address. Use this when provisioning a new sending identity or automation actor. To add more addresses later, use agent_update. Pass idempotencyKey to make retries safe — same key + same body returns the original response, same key + different body returns IDEMPOTENCY_BODY_MISMATCH 409.

Fetch full detail for a single agent by ID: settings, metadata, status, and the full addresses[] / emailIdentities[] / phoneIdentities[] lists. Use agent_list to browse multiple agents.

List agents in the current account context with cursor pagination. Returns a lightweight per-agent record (addresses are NOT included to avoid N+1 round-trips). Use agent_get for full single-agent detail.

Update an agent's name or metadata, and/or add/update/delete an address. Use addAddress to attach a new address, updateAddress to change fields on an existing one (by addressId), deleteAddressId to remove one. Multiple field-level changes can be combined in a single call.

Delete an agent by ID. Use this to remove deprecated or compromised agents that should no longer send messages. Cascades to attached addresses, email identities, and phone identities.

Send a new outbound email from the agent mailbox. Use this when you need to compose and deliver a message with optional CC, threading headers.

Fetch full detail for a single email by ID, including metadata and body. Use email_list to browse emails in a folder.

List emails with cursor pagination. Returns lightweight per-email records plus a `pagination` object — pass `pagination.nextCursor` back as `cursor` for the next page. Use email_get for the full body, email_search to find specific messages.

Search messages by content. Fulltext mode (default) substring-matches subject/body/addresses of EMAIL messages and returns `{items, pagination}` with cursor paging. Semantic mode ranks by vector-embedding similarity and returns `{results}` scored 0-1 — each result spans ANY channel (check the `channel` field) and includes the message id for email_get / email_thread_get follow-ups.

Add and/or remove labels on one message — the agent's workflow state. Use this to mark mail read/unread (`read`/`unread`), archive it (`archived`), or apply your own tags, then filter with email_list's `labels`. Supply at least one of addLabels/removeLabels. One message per call: there is no batch form.

Reply to an existing email thread by first loading the original message and setting threading headers. Use this when you need a proper in-thread response.

Forward an existing email to another recipient by loading the original content first. Use this to share a prior message while preserving context.