> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/channels/email.md). # Email ## Use Cases and Sender Identities Email on the platform is organized around use cases. A use case names one email sender identity - a sender address backed by a verified sending domain - owned by a workspace. Each use case records an explicit decision on two inbox posture settings: * **Unsubscribable** - whether sends carry one-click unsubscribe headers and honor per-use-case opt-out lists. Marketing email must be unsubscribable. Transactional use cases may opt out for must-send flows such as password resets. * **Accepts cold inbound** - whether the sender address acts as an open inbox (cold first-contact email reaches the agent after authentication and spam gates) or a strict thread-only inbox (only replies to outbound messages are accepted). Binding a use case to a service is the act that enables the email channel for the workspace. Once bound, inbound traffic for the use case resolves to the bound service, and outbound dispatch from the service routes through the use case. Rebinding replaces the current binding immediately. Unbinding turns the channel off. Use cases are managed through the platform API and the Developer Console's Channels section (private preview). The Developer Console provides a creation form, a list view with inbox posture badges, and row actions for binding, unbinding, and deleting use cases. ## Sending Domain Setup Before an email use case can send or receive messages, the workspace must register a verified sending domain. Each setup binds a logical tenant name to a domain identity, creating an isolation boundary for reputation and suppression management. The registration process works in three steps: 1. **Create the setup** - Provide a tenant name and domain identity. The platform provisions the domain and returns a set of DNS records (DKIM, SPF, MX, and DMARC) that must be published at your DNS provider. 2. **Publish DNS records** - Add the returned records to your domain's DNS configuration. Each record has a type, address, and value. 3. **Verify** - Trigger a verification check from the Developer Console or API. The platform resolves each record against live DNS and marks it as verified or pending. All records must pass before the setup can back any email use case. A single domain identity serves both outbound sending and inbound receiving. Setups that have not completed DNS verification cannot be used by email use cases. Setups can be deleted when no longer needed, though active use cases referencing a setup will block deletion. ## Email ### Reliability and Operational Recovery The email channel includes production hardening for reliable message processing. Inbound email turns are processed with automatic retry logic - if processing fails after multiple attempts, the turn is dead-lettered with a durable record that captures the full routing context (service, use case, session, and message references). Dead-lettered turns retain their ingest claim to prevent duplicate processing from upstream retries. Operators can recover dead-lettered turns after the underlying fault is resolved using a dedicated redrive tool. The redrive reads the durable dead-letter record, reconstructs a fresh processing item with a clean retry budget, releases the original ingest claim, and re-enqueues the turn for the live consumer to process. The tool defaults to a dry-run mode that displays the reconstructed item without writing anything, requiring an explicit flag to apply changes. The platform tracks processing backlog depth on a periodic cadence, surfacing the count of queued work items and in-progress sessions as operational gauges. A rising backlog indicates that inbound turns are arriving faster than they can be processed - a condition that per-turn liveness signals alone cannot detect. During rolling deploys and pod shutdowns, the email consumer drains gracefully. It stops claiming new work while allowing any in-flight turn to complete within a bounded window, then re-queues any work it popped but did not start so successor instances pick it up without delay. Channel Setup The platform supports workspace-scoped email channel configuration. Each workspace can provision one or more verified email domains for sending and receiving messages. When a domain is added, the platform returns the DNS records (DKIM, SPF, MX, DMARC) that must be published at the customer's DNS provider. Subsequent verification checks confirm that the records are in place and the domain is ready for use. Domain verification is live - every status check re-queries DNS rather than relying on cached results, so teams see up-to-date verification status without waiting for a background refresh cycle. Each email domain setup is isolated to its workspace. Cross-workspace access is prevented at the API layer, and deletion is blocked while any active use case still references the setup. {% hint style="info" %} Email sending, delivery tracking, and engagement analytics are available through the Platform API. See the [Developer Guide](https://docs.amigo.ai/developer-guide) for endpoint details. {% endhint %} The platform supports email as a communication channel alongside voice and text. Workspaces can set up verified sending domains, create email use cases, send messages through the platform API, and receive inbound replies that thread back into the original conversation. ## Email Setup Before sending email, a workspace configures an email setup by registering a sending domain. The platform provisions the necessary DNS records for domain authentication. Once the DNS records are verified, the domain is approved for sending. Each email setup includes: * **Domain identity** - The domain used for sending (e.g., `notifications.example.com`) * **DNS records** - Records that must be added to the domain's DNS configuration for verification, including DKIM signing keys, SPF records, DMARC policies, and inbound MX routing * **Verification status** - Whether the DNS records have been confirmed ## Email Use Cases Once a domain is verified, you create email use cases that define how the domain is used. Each email use case specifies: * **Sender email address** - The `From` address for messages sent through this use case * **Email type** - Either `transactional` (triggered by user actions, like appointment confirmations) or `marketing` (bulk or promotional messages). The type determines sending rules and compliance handling. * **Entity name and use case name** - Labels that identify the purpose of the use case for reporting and management Email use cases are managed through the Platform API. See the [Developer Guide](https://docs.amigo.ai/developer-guide) for endpoint details. ## Inbound Email ### Attachment Handling The platform extracts attachments from inbound emails by walking the full MIME tree depth-first, handling deeply nested structures produced by clients like Apple Mail and iOS Mail that wrap HTML alternatives and attachments together inside nested multipart branches. This ensures attachments are never silently dropped regardless of how the sending client structures its MIME parts. Forwarded-as-attachment emails (enclosed as `message/rfc822` parts) are treated as single opaque `.eml` files - the platform does not recurse into forwarded messages, so attachments inside a forwarded email are never incorrectly attributed to the outer message. Inline images referenced from the email body via `cid:` URLs are identified by matching Content-ID headers against references in the HTML. These images are stored using their Content-ID as the filename, allowing frontend clients rendering the email body to resolve `cid:` image references directly to the attachment path without additional lookups. This also prevents inline images like signature logos from appearing as both rendered body content and separate downloadable attachments. When a domain's MX records are configured, the platform receives and processes inbound email. Inbound messages are resolved back to the original outbound email that prompted the reply, linking the patient's response to the correct conversation context. Reply resolution uses the standard `In-Reply-To` and `References` headers from the inbound message to find the parent outbound. When a match is found, the inbound email is associated with the same use case and workspace, giving downstream systems full thread context. ## Reply Threading Outbound emails can be sent as replies to inbound messages, maintaining thread continuity in the patient's email client. When sending a reply, the platform sets the `In-Reply-To` and `References` headers according to RFC 5322, so the patient sees a single threaded conversation rather than disconnected messages. The platform maintains the full reference chain across multiple reply rounds. If a patient replies to an outbound, and the platform replies back, and the patient replies again, each message carries the complete thread history. Even when a patient's email client strips the `References` header (some lightweight mailers do this), the platform reconstructs the chain from its stored records so the next outbound reply still threads correctly. Reply threading is scoped to the same use case and email setup. Cross-use-case replies are rejected to prevent confused-deputy scenarios where a reply intended for one context could be misattributed to another. ## Delivery Tracking The platform tracks delivery events for every outbound email: * **Delivery confirmation** - When the receiving mail server accepts the message * **Bounce handling** - Hard bounces (invalid address) and soft bounces (temporary failure) are recorded and influence future sending decisions * **Complaint tracking** - When a recipient marks a message as spam, the platform records the complaint and can suppress future sends to that address ## Unsubscribe Handling Outbound emails include RFC 8058 one-click unsubscribe headers. When a patient clicks the unsubscribe button in their email client, the platform processes the opt-out automatically. Unsubscribe scope can be per-use-case (the patient stops receiving emails from one campaign but continues receiving others) or per-setup (the patient opts out of all email from that domain). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.amigo.ai/channels/email.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.