Email

Email channel with domain verification, inbound reply handling, thread continuity, and transactional and marketing use cases.

The platform supports email as a communication channel alongside voice and text. With a verified sending domain in place, workspaces create email use cases, send messages through the platform API, and receive inbound replies that thread back into the original conversation.

Sending Domain Setup

Before an email use case can send or receive messages, the workspace must have a verified sending domain. Each setup binds a logical tenant name to a domain identity, creating an isolation boundary for reputation and suppression management. Each email domain setup is isolated to its workspace, and a workspace can have more than one.

Sending-domain setup is provisioned by the Amigo team - it is not self-serve. The team registers the domain identity, provides the DNS records to publish at your DNS provider, and confirms verification against live DNS. A single domain identity serves both outbound sending and inbound receiving, and a domain must complete DNS verification before it can back an email use case. To enable email for a workspace, contact the Amigo team.

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: DKIM signing keys, SPF records, DMARC policies, and inbound MX routing
• Verification status - Whether the DNS records have been confirmed

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 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

Each use case also 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 (create, bind, unbind, and delete use cases).

Email sending, delivery tracking, and engagement analytics are available through the Platform API. See the Developer Guide for endpoint details.

Inbound Email

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.

Long-Running Tools and Reply Delivery

Some agent replies depend on a tool that takes longer than the synchronous turn window. Voice can provide a live acknowledgement. A web API client instead follows the REST contract: bounded wait_for_final, background_pending, and explicit polling when work remains.

Email is asynchronous, so its channel policy suppresses an intermediate acknowledgement and waits for supported background work before attempting the final reply. The recipient does not maintain a live text connection. Tool completion, message creation, provider acceptance, and recipient delivery are separate milestones.

The intended result is one useful reply rather than a filler followed by a correction. Tool failure, exhausted processing retries, suppression, bounce, or provider rejection can still prevent that outcome. Use channel status and the recovery queue to distinguish those cases.

SMS, iMessage, and WhatsApp use related non-live policies. Web conversations use request-scoped REST or SSE rather than a persistent text WebSocket.

Attachment Handling

The inbound parser handles standard MIME attachments and the deeply nested layouts produced by some mail clients. Supported behavior includes:

• Attachment parts are preserved. Recognized attachment parts are extracted with their content and metadata rather than flattened into the message body.
• Forwarded emails stay intact. An email forwarded as an attachment is kept as a single .eml file, preventing attachments inside it from being attributed to the outer message.
• Inline images retain CID identity. Content-ID parts are stored under their CID identifiers so renderers can resolve references from the message body. Consumers should not assume every client hides those parts from attachment views.

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 records available provider lifecycle events for 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).

Reliability and Operational Recovery

The email channel is built for reliable message processing. Inbound email turns are processed with automatic retry logic - if processing fails after multiple attempts, the turn is set aside in a durable record that captures the full routing context (service, use case, session, and message references), with safeguards against duplicate processing.

Operators can recover these failed turns after the underlying fault is resolved using a dedicated recovery tool. The recovery reconstructs a fresh processing item with a clean retry budget and re-submits the turn for processing. 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 monitors email processing load so teams can detect when inbound volume outpaces processing capacity. 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 maintenance or a worker restart, bounded retries can re-process unstarted work. Items that exhaust their retry budget move to durable recovery records; operators should monitor backlog and use the recovery workflow rather than assume lossless processing.