> ## Documentation Index > Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt > Use this file to discover all available pages before exploring further. # Post messagesemail ## OpenAPI ````yaml /openapi.json post /messages/email openapi: 3.1.1 info: title: Anima API version: 0.1.0 description: >- The Anima API provides programmatic access to unified infrastructure for AI agents: create and manage agents; send and receive email; place phone calls and send/receive SMS and voice; store and retrieve vault credentials; manage agent identity; and configure webhooks for real-time events. Authenticate using a Bearer token or an API key passed via the X-API-Key header. contact: name: Anima Labs url: https://useanima.sh email: support@useanima.sh license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://api.useanima.sh/v1 description: Production security: - BearerAuth: [] - ApiKeyAuth: [] tags: - name: Agents description: Create and manage AI agents with email and phone capabilities - name: Inboxes description: Manage email inboxes and their configurations - name: Messages description: Send, receive, and search email messages - name: Webhooks description: Register and manage webhook subscriptions for real-time events - name: Organizations description: Manage organizations and team settings - name: Domains description: Configure and verify custom email domains - name: Phone description: Manage phone numbers and SMS/voice capabilities - name: Invoices description: Track invoices, match receipts, and reconcile payments - name: Billing description: View usage, tiers, and billing information - name: Security description: Configure security policies and access controls - name: Vault description: Store and retrieve encrypted secrets - name: API Keys description: Create and manage API keys for programmatic access paths: /messages/email: post: operationId: message.sendEmail requestBody: required: true content: application/json: schema: type: object properties: agentId: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ description: ID of the agent sending the email fromIdentityId: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ description: >- Optional EmailIdentity ID to send from. Must belong to this agent and be verified. If omitted, the agent's primary identity is used. Use this to route different message types through different identities (e.g. transactional from @brawz.ai, support from @support.brawz.ai). List the agent's identities first via agent_email_identity_list to discover available IDs. to: type: array items: type: string format: email minItems: 1 description: List of recipient email addresses (at least one required) cc: default: [] type: array items: type: string format: email description: List of CC recipient email addresses bcc: default: [] type: array items: type: string format: email description: List of BCC recipient email addresses subject: type: string minLength: 1 maxLength: 998 description: Email subject line (max 998 characters per RFC 2822) body: type: string minLength: 1 description: Plain-text body of the email bodyHtml: type: string description: Optional HTML body of the email attachments: type: array items: type: object properties: filename: type: string minLength: 1 maxLength: 255 description: >- Filename presented to the recipient. Inferred from the URL path when `url` is used and this is omitted; falls back to 'attachment' when neither is available. contentId: type: string minLength: 1 maxLength: 255 description: >- Content-ID for inline attachments referenced in the HTML body via `cid:` URIs (e.g. set to 'logo' to be referenced as ``). When present, the attachment uses `Content-Disposition: inline`; when absent, `attachment`. contentType: type: string description: >- MIME type. Auto-detected from `filename` extension if omitted (e.g. 'application/pdf' for .pdf, 'image/png' for .png). Falls back to 'application/octet-stream' if undetectable. content: type: string description: >- Base64-encoded attachment bytes. Provide either `content` or `url`. Single base64 string up to ~33MB on the wire (decodes to ~25MB binary). url: type: string format: uri description: >- Public URL the server fetches and attaches. Provide either `content` or `url`. URLs to private/loopback/link-local IPs are rejected to prevent SSRF. Max 25MB after download. description: >- File attachment for outbound email. Provide exactly one of `content` (base64-inline) or `url` (server-fetch). Optional `contentId` makes the attachment inline for HTML-embedded images. maxItems: 20 description: >- Optional file attachments. Max 25MB total across all attachments (after base64 decode for inline, after fetch for URL-source); max 20 attachments per email. Each entry provides either inline base64 `content` or a public `url` for server-fetch. headers: default: {} type: object additionalProperties: type: string description: Custom email headers as key-value pairs metadata: default: {} type: object additionalProperties: {} description: Arbitrary key-value metadata to attach to the message required: - agentId - to - subject - body description: Request body for sending an email through an agent responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ description: Unique identifier of the message agentId: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ description: ID of the agent that sent or received the message channel: enum: - EMAIL - SMS - MMS - VOICE type: string description: Communication channel used direction: enum: - INBOUND - OUTBOUND type: string description: Whether the message was inbound or outbound status: enum: - QUEUED - SENT - DELIVERED - FAILED - BOUNCED - BLOCKED - PENDING_APPROVAL type: string description: Current delivery status fromAddress: type: string description: Sender address (email or phone number) toAddress: type: string description: Recipient address (email or phone number) subject: anyOf: - type: string - type: 'null' description: >- Message subject line, or null for channels that do not support subjects body: type: string description: Plain-text content of the message bodyHtml: anyOf: - type: string - type: 'null' description: HTML content of the message, or null if not available headers: anyOf: - type: object additionalProperties: {} - type: 'null' description: Raw message headers as key-value pairs, or null metadata: anyOf: - type: object additionalProperties: {} - type: 'null' description: Arbitrary metadata attached to the message, or null threadId: anyOf: - type: string - type: 'null' description: Thread identifier for conversation grouping, or null inReplyTo: anyOf: - type: string - type: 'null' description: Message ID this message is replying to, or null externalId: anyOf: - type: string - type: 'null' description: Provider-assigned external identifier, or null sentAt: anyOf: - type: string format: date-time - type: 'null' description: >- Timestamp when the message was sent, or null if not yet sent receivedAt: anyOf: - type: string format: date-time - type: 'null' description: >- Timestamp when the message was received, or null for outbound messages attachments: type: array items: type: object properties: id: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ description: Unique identifier of the attachment filename: type: string description: Original filename of the attachment mimeType: type: string description: MIME type of the attachment (e.g. application/pdf) sizeBytes: type: integer minimum: 0 description: File size in bytes storageKey: type: string description: Internal storage key for retrieving the file url: anyOf: - type: string format: uri - type: 'null' description: >- Pre-signed download URL, or null if not yet generated createdAt: type: string format: date-time description: Timestamp when the attachment was created scanStatus: enum: - PENDING - CLEAN - FLAGGED - BLOCKED type: string description: >- Content-scan verdict. BLOCKED attachments cannot be downloaded — inspect before fetching bytes. detectedMimeType: anyOf: - type: string - type: 'null' description: >- MIME type inferred from magic bytes; may differ from the declared mimeType required: - id - filename - mimeType - sizeBytes - storageKey - url - createdAt - scanStatus - detectedMimeType description: File attachment associated with a message description: File attachments associated with this message createdAt: type: string format: date-time description: Timestamp when the message record was created updatedAt: type: string format: date-time description: Timestamp when the message record was last updated required: - id - agentId - channel - direction - status - fromAddress - toAddress - subject - body - bodyHtml - headers - metadata - threadId - inReplyTo - externalId - sentAt - receivedAt - attachments - createdAt - updatedAt description: Full message resource representation components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer ApiKeyAuth: type: apiKey in: header name: X-API-Key description: 'API key for programmatic access. Pass as: X-API-Key: ' ````