Email

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.

An Email Distribution Ion connects one Aion-managed inbox to an Ion Sequence. 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:

receive supported messages sent to its assigned address;
preserve the sender, recipients, subject, thread, reply, and attachment metadata for the agent; and
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

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

Open Integrations, then select Email.
Select Create email inbox.
Enter the Inbox name. Enter only the part before @; the displayed domain cannot be changed.
Select Create Inbox and wait for the inbox to become ready.
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.

Open the Project in Composer.
Select the Email Distribution Ion and open its Identity tab.
Select the ready inbox under Email.
To make this endpoint part of an Aion, select its Principal Identity.
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.

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.

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 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, Event, and Distribution/Messaging.

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.

LangGraph
Google ADK
A2A

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}")
        ]
    }

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}"}]},
        )

{
  "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"
    }
  }
}

For framework-specific request access, see LangGraph message mapping and 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.

Guides

Core Concepts

Ions

Resources

Distributions

Tools

Other

Overview

Default request loop

Configuration

Before you begin

Create an email inbox

Assign the inbox to a Distribution

Configure automated messages

Activate the Distribution

Message mapping

Features

Messages and thread replies

Filtering

Attachments

Streaming and structured actions

Email tools

​Overview

​Default request loop

​Configuration

​Before you begin

​Create an email inbox

​Assign the inbox to a Distribution

​Configure automated messages

​Activate the Distribution

​Message mapping

​Features

​Messages and thread replies

​Filtering

​Attachments

​Streaming and structured actions

​Email tools

Overview

Default request loop

Configuration

Before you begin

Create an email inbox

Assign the inbox to a Distribution

Configure automated messages

Activate the Distribution

Message mapping

Features

Messages and thread replies

Filtering

Attachments

Streaming and structured actions

Email tools