> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Email

> Create an email inbox, route incoming mail through a Distribution Ion, and reply in the same thread.

<Note>
  Email distributions are available in preview. Managed inbox setup and the same-thread reply loop are implemented,
  but availability depends on the current environment's email configuration.
</Note>

An **Email Distribution Ion** connects one Aion-managed inbox to an
[Ion Sequence](/docs/concepts/ions#ions-and-sequences). Incoming email becomes an A2A request, travels through the
Sequence, and receives the agent's final text response in the same email thread.

## Overview

An Email Distribution has three responsibilities:

1. receive supported messages sent to its assigned address;
2. preserve the sender, recipients, subject, thread, reply, and attachment metadata for the agent; and
3. send the agent's final text response back to the sender in the same thread.

Aion creates and manages the inbox. You choose the name before `@`, while Aion selects and displays the fixed domain
for the current environment. Connecting Gmail, Google Workspace, another existing mailbox, or a customer-owned domain
is not supported in the current release.

## Default request loop

```mermaid theme={null}
sequenceDiagram
  participant U as Email sender
  participant I as Aion-managed inbox
  participant D as Email Distribution Ion
  participant Q as Ion Sequence

  U->>I: Send an email
  I->>D: Deliver the received message
  D->>D: Verify, filter, and normalize the message
  D->>Q: Send an A2A request in the email thread context
  Q-->>D: Return the final text response
  D-->>U: Reply in the same email thread
```

Aion accepts the incoming message before the Sequence finishes. Response delivery continues asynchronously and uses
the original inbox, thread, and triggering-message coordinates.

## Configuration

### Before you begin

You need:

* an Aion organization and a Project containing an Email Distribution Ion;
* permission to add integrations to that organization; and
* an available inbox name on the domain shown during setup.

### Create an email inbox

1. Open **Integrations**, then select **Email**.
2. Select **Create email inbox**.
3. Enter the **Inbox name**. Enter only the part before `@`; the displayed domain cannot be changed.
4. Select **Create Inbox** and wait for the inbox to become ready.
5. Confirm that the assigned address appears under the Email integration.

If setup is interrupted, reopen the pending setup and use the available retry action. An unavailable name returns the
same safe error whether it is reserved or already in use.

### Assign the inbox to a Distribution

Creating an inbox does not automatically bind it to a Project or Distribution.

1. Open the Project in [Composer](/docs/composer).
2. Select the Email Distribution Ion and open its **Identity** tab.
3. Select the ready inbox under **Email**.
4. To make this endpoint part of an Aion, select its **Principal Identity**.
5. Sync the Project changes.

### Configure automated messages

Open the Distribution Ion's **Configuration** tab to control automated inbound mail.

| Setting                  | Default  | Effect                                                                    |
| ------------------------ | -------- | ------------------------------------------------------------------------- |
| Allow Automated Messages | Disabled | Lets auto-replies, bulk mail, and mailing-list mail trigger the Sequence. |

Keep this setting disabled unless the agent is designed to avoid mail loops. Messages sent by the connected inbox are
always suppressed.

### Activate the Distribution

An Email Distribution can activate when the selected inbox is ready and belongs to the same organization. After
resolving any validation messages, turn on **Activate distribution** and sync the Project.

<Warning>
  Releasing an Email identity permanently deletes its managed inbox and mailbox contents after Aion stops new routing.
  Save anything that must be retained before release.
</Warning>

## Message mapping

For each accepted email, Aion sends the Sequence:

* a text part containing bounded plain text, or safe text extracted from HTML when plain text is unavailable;
* a `MessageEventPayload` containing the sender, message, thread, mailbox-parent, and reply coordinates; and
* a sanitized source-system event containing the subject, recipients, selected headers, and attachment metadata.

The email thread maps to the immediate A2A context. The managed inbox maps to its parent context. A message with an
`In-Reply-To` value uses `trajectory = "reply"`; another message in the thread uses
`trajectory = "conversation"`.

| Email value              | A2A messaging value |
| ------------------------ | ------------------- |
| Sender address           | `userId`            |
| Email thread             | `contextId`         |
| Managed inbox            | `parentContextId`   |
| Message identifier       | `messageId`         |
| `In-Reply-To` identifier | `replyToMessageId`  |

Subject, recipient, header, and attachment details are request metadata rather than extra text injected into the user
message. Attachments include metadata only; the Distribution does not download or execute attachment content. See
[Media and attachments](/docs/distributions/messaging/media-and-attachments) for the shared distinction between
metadata, accessible bytes, and transcription.

The default outbound behavior sends one final text reply to the sender in the same thread. It does not reply-all. For
the shared protocol contracts, see [Distribution](/a2a/extensions/aion/distribution/1.0.0),
[Event](/a2a/extensions/aion/event/1.0.0), and
[Distribution/Messaging](/a2a/extensions/aion/distribution/messaging/1.0.0).

## Features

### Messages and thread replies

Every accepted incoming email starts a new A2A task while reusing the mapped context for its email thread. The agent
can use ordinary text output; the Distribution sends the final response back to the triggering sender.

<Tabs borderBottom>
  <Tab title="LangGraph">
    ```python theme={null}
    from typing import Annotated, TypedDict

    from langchain_core.messages import AIMessage, BaseMessage
    from langgraph.graph import add_messages


    class AgentState(TypedDict):
        messages: Annotated[list[BaseMessage], add_messages]


    def reply_to_email(state: AgentState) -> dict:
        inbound = state["messages"][-1]
        return {
            "messages": [
                AIMessage(content=f"Thanks for your email. {inbound.content}")
            ]
        }
    ```
  </Tab>

  <Tab title="Google ADK">
    ```python theme={null}
    from google.adk.agents import BaseAgent
    from google.adk.events import Event


    class EmailReplyAgent(BaseAgent):
        async def _run_async_impl(self, ctx):
            texts = [
                part.text
                for part in ctx.a2a_inbox.message.parts
                if getattr(part, "text", None)
            ]
            text = "\n".join(texts)
            yield Event(
                author=self.name,
                content={"parts": [{"text": f"Thanks for your email. {text}"}]},
            )
    ```
  </Tab>

  <Tab title="A2A">
    ```json theme={null}
    {
      "data": {
        "userId": "sender@example.com",
        "contextId": "email-thread-context",
        "parentContextId": "email-inbox-context",
        "messageId": "message-42",
        "replyToMessageId": "message-41",
        "trajectory": "reply"
      },
      "mediaType": "application/json",
      "metadata": {
        "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
          "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/messaging/1.0.0#MessageEventPayload"
        }
      }
    }
    ```
  </Tab>
</Tabs>

For framework-specific request access, see
[LangGraph message mapping](/sdk/langgraph/message-mapping) and
[Google ADK message mapping](/sdk/google-adk/message-mapping).

### Filtering

The Distribution accepts supported, authenticated incoming messages. Spam, blocked, unauthenticated, self-authored,
and unsafe messages do not start agent work. Standard auto-reply, bulk, and mailing-list headers are also suppressed
unless **Allow Automated Messages** is enabled.

### Attachments

Agents receive bounded attachment metadata such as file name, content type, and size. Attachment bytes are not fetched
or added to the A2A request in the current release. Email does not emit an Aion media file part or automatically
transcribe audio attachments. Attachment metadata remains in the sanitized source-system event.

### Streaming and structured actions

Email does not expose partial streaming output. The sender receives one final text reply after the agent turn completes.
Cards, reactions, slash commands, mentions, and direct-message actions are not part of the Email distribution.

### Email tools

When the Email tool capability is enabled for the Distribution, an agent can inspect the selected inbox and threads,
search messages, and send, reply to, or forward email. The capability is scoped to that exact inbox.

Email write tools are not retried automatically after an ambiguous result. Repeating an uncertain send, reply, or
forward can produce duplicate mail.