io.github.anima-labs-ai/anima

Single-call workspace snapshot: organization context, credential identity, send-capability flags (canSendEmail / canSendSms), inventory counts (agents, domains, phones), active blockers (each carrying the canonical MCP tool that resolves it), and the running MCP server's deploy identity (commitSha, revision, buildId, startedAt). Strict superset of the legacy whoami + workspace_health pair. Use before any non-trivial workflow to answer 'who am I, can I do X right now, and which deploy is serving me?' in one round-trip — no real send needed to find out.

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.

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.

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.

Register a custom sending domain in the workspace so it can be configured for email traffic. Use this before DNS setup and verification.

Delete a domain from the workspace when it is no longer needed. Use this to remove old or incorrect domain configurations.

Fetch full detail for a single domain by ID, including verification and configuration state. Use domain_list to browse all domains.

List all domains connected to the current workspace. Use this to audit configured sender domains and choose one for follow-up actions.

Update mutable configuration on a domain. Currently the only updatable field is `feedbackEnabled` — toggle SES bounce and complaint feedback processing on or off without re-verifying the domain.

Trigger a verification check for a domain after DNS records are configured. Use this to re-run DNS validation and update verification status.

Get the full DNS zone file for a domain. Use this for complete DNS export or to verify all records are correctly configured.

Get a temporary download URL for an email attachment. Use this when you need direct file access for preview or download.

Create a new email draft (composed but not sent). Drafts can be incomplete — missing recipients, subject, or body. Use email_draft_send later to actually deliver, or email_draft_delete to discard.

Discard a draft. Use this to remove drafts that are no longer needed. Use email_draft_send if you want to deliver instead.

Fetch full detail for a single draft by ID. Use email_draft_list to browse drafts.

List email drafts with optional filters. Returns lightweight draft records — use email_draft_get for full detail.

Send a draft. Atomically converts the draft to a delivered Message + deletes the draft row. The draft must have at least one recipient, a subject, and a body. Returns the newly-created Message.

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

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

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.

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.

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.

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.

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 all email messages in one or more threads. Pass `id` for a single thread or `ids` for multiple. Returns messages ordered within each thread. Uses the messages endpoint filtered by threadId + channel=EMAIL under the hood.

Create a short-lived, single-use connect URL that links a browser extension (or a headless Puppeteer worker) to an Anima agent. Returns `connectUrl` — hand it to the extension to complete the handshake before `exchangeExpiresAt`. The response carries no token or secret. Auth: with a master key you MUST pass `agentId`; with an agent key OMIT `agentId` (the server resolves it from the key). `ttl` is optional; a value above the org's maximum is rejected.

Create a new email inbox (mailbox) that can receive mail immediately at its address. Choose a username and domain or let the platform generate them. Requires master key access.

Permanently delete an inbox and its mailbox. Mail sent to the address after deletion bounces. This cannot be undone. Requires master key access.

Fetch full detail for a single inbox by ID, including its email address, display name, and associated agent. Use inbox_list to browse all inboxes.

List inboxes in the workspace with cursor pagination and optional free-text search. Returns the address, display name, and agent association for each inbox.

Update the display name or agent association of an inbox. Pass null for a field to clear it (unlink the agent / remove the display name); omitted fields are left unchanged. The email address itself cannot be changed. Requires master key access.

Place a live phone call and have a real conversation. The tool stays open for the entire call duration. As the caller speaks, you receive live transcript chunks via progress notifications; when the caller finishes a turn (server emits isFinal: true), an elicitation prompt asks you what the agent should say next. You respond with `say` (the exact text to speak) and optional `endCallAfterSpoken: true` to hang up after the line. Returns the full transcript when the call ends. Requires the connecting MCP client to support elicitation — without it, the tool errors out immediately.

Get full detail for a single phone call: status, duration, participants, AI-generated summary (one-liner, topics, action items, decisions, open questions, next steps), and quality score. The summary is generated once on first read after post-call processing and cached.

List phone calls with optional filters. Returns lightweight call records — for full call detail including summary and score, use phone_call_get.

Get a time-limited download URL for a call recording (WAV format). The URL expires after 1 hour. Recording must have been enabled during the call.

Get the full transcript of a phone call with speaker labels, timestamps, and confidence scores. Available after the call ends and transcription completes.

List phone numbers assigned to an agent. Each result includes status and capability flags (sms/mms/voice).

Provision a new phone number from the carrier pool and assign it to an agent. Note: provisioning a number costs money on the underlying carrier; do not call speculatively. Use countryCode / areaCode / capabilities to constrain selection.

Release a previously provisioned phone number back to the carrier pool. Use this when cleaning up unused numbers. Released numbers cannot be recovered.

Fetch full detail for a single SMS by ID (includes its `threadId` for joining the conversation). Use sms_list to browse multiple SMS messages.

List SMS messages with optional filters. Each result includes its `threadId` for joining the conversation. Use sms_get for full single-message detail.

Send an SMS to a phone number, or an MMS by passing `mediaUrls`. The agent must have a provisioned phone number. Use this for transactional texts or conversational messaging.

Get one SMS/MMS conversation with its message history, oldest first. Use sms_thread_list to find thread IDs (or take `threadId` off any SMS). For a conversation longer than `limit`, returns its most recent messages; page deeper history with sms_list.

List SMS/MMS conversations, most recently active first. A conversation is one agent number talking to one external contact. Returns summaries (participant, last message snippet, message count) — use sms_thread_get for the full history. Optionally filter by agentId.

Usage rollup for a billing period. Returns counters keyed by usage type (e.g. 'email_sent', 'sms_sent', 'voice_call_minutes') plus the latest update timestamp. Defaults to the current calendar month in UTC when `period` is omitted. Read-only, callable by any authenticated credential — scoped to the caller's org. Use to answer 'where am I against my tier limits?' without paying for per-event detail (UsageEvent is operator-tier).

Create a new credential in an agent vault. Pass `type` plus the matching payload block (login / card / identity / oauthToken / apiKey / certificate / notes). For login credentials, prefer `generatePassword` over supplying `login.password` — the vault generates and stores the password server-side and returns only the credential reference, so the secret never enters the conversation. For api_key/oauth_token credentials, set `allowedHosts` so the credential can be exercised through vault_credential_use.

Delete a credential from vault storage by ID. Use to remove obsolete or compromised secrets.

Get a single vault credential by ID. Sensitive fields (passwords, tokens, SSNs, CVV) are masked. To use the plaintext for autofill or as an upstream credential, mint a vault token at the credential broker — the LLM never sees the secret directly.