Email an Agent

An agent with a Google account has a mailbox of its own. Mail sent to that address arrives as work: the subject, the body, the attachments, and the thread it belongs to all reach the agent, and when its turn ends it replies in the same thread from its own address.

Find the Address

Open the agent's page and look at the Google account card. It shows the agent's address with a Copy address control, and reports Documents and Mail readiness separately, because Drive and the mailbox come up at their own pace. An agent whose mailbox is still coming up reads as not ready rather than handing you an address that drops mail.

An agent without a Google account has no address and cannot be emailed. Add one from the same card.

What Arrives

One message becomes one arrival, carrying:

• Subject and body. A very long body is cut with an explicit marker rather than dropped.
• Attachments. They travel with the message. An oversized attachment, or one past the per-message count, stays in the mailbox where the agent can fetch it with its own access. An attachment a virus scan flags is removed from what the agent is handed.
• The thread. Threading follows the mail headers, not one mailbox's grouping, so a conversation that reaches two agents means the same thread to both.
• How you addressed it. An agent on the To line is being directed. An agent on Cc is being kept in the loop.

Every arrival is recorded in your account's event history, whatever the policy below decides about it. Nothing is silently dropped, held, or quarantined, so a playbook can act on mail that is not allowed to direct the agent.

Who Is Allowed to Direct It

An agent's address is public by the nature of email, so two rules stand between the mailbox and the agent's work.

The authentication floor comes first and nothing outranks it. Mail whose sender nothing authenticated never speaks as the person it names. Wallfacer records the address the message claimed and, separately, the address the transport actually verified through DMARC or a domain signature. Only the verified address can direct an agent. A trigger you wrote cannot waive this, because a trigger authorizes a sender; it cannot establish who a sender is.

Then the agent's mail policy applies. Each agent carries its own, and the shipped defaults are:

A message the policy refuses is still recorded, with the reason it was refused, so the history shows both what arrived and what was done about it. A refused message never continues a thread and never starts work.

Setting the Policy

There is no settings screen for mail policy yet. Set it through the API, on the agent:

curl -s -X PATCH "$WALLFACER_API/accounts/$ACCOUNT_ID/agents/$AGENT_ID" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "mail_policy": {
      "directable_by": "members_and_allowed",
      "allowed_senders": ["[email protected]", "*@partner.com"],
      "may_start_work": true,
      "replies": "thread"
    }
  }'

Send the whole policy every time. mail_policy is replaced wholesale, and a request carrying only some of its fields is rejected with a 422 rather than merged into whatever was set months ago. Unknown values and unmatchable sender patterns are also 422. Every other field on the agent still patches partially, and a policy change is written to the account's audit record.

Read the current policy back from GET /v1/accounts/{account_id}/agents/{agent_user_id}.

How the Agent Replies

The reply is part of the transport, not something the agent chooses to send. That has consequences worth planning around:

• One reply per turn, sent when the turn ends. There is no "working on it" acknowledgement and no read receipt.
• In the same thread, from the agent's own address, to the thread's authenticated participants. The round trip correlates back to the same task.
• Plain text, no attachments. No code path can attach a file to a reply.
• A reply only continues a thread. The reply path never opens one. An agent can write to somebody first, but that is the outreach path below, and it takes somebody asking for it.
• The task is read-only in the app. A conversation that started in mail is answered in mail, so Wallfacer shows the whole task and does not offer to send into it. Where the composer would be, a banner says the conversation started on email and is answered there, and links the thread. Every message in it, in both directions, still shows in the task.
• No second notification in the app. A mail conversation does not notify you in the app when it goes idle, pauses for you, or gets a new message. The reply is already in your inbox, and the app cannot send into the conversation. See Notifications.
• Failures are recorded, not silent. A refusal names its reason: no mailbox for the agent, replies disabled, no participant with an address, and so on. A rejection from the mail provider is retried; a spent daily allowance is reported as such.

When the Agent Writes First

Mail also goes the other way. Ask an agent to get in touch with someone, by name or by address, and it opens a conversation from its own address: "email Bob about the contract", "let the customer know it shipped". The agent writes the message as itself, and the reply comes back to it in the same thread.

Two things bound this:

• Somebody has to ask for it. An agent cannot decide to write to a person. Wallfacer checks what authorized the outreach against its own record of the session, so a request from a member, or a playbook step that says to make contact, goes out, and anything else is refused with the refusal on the record. Text the agent read in a file, on a web page, or in an incoming message is not authorization, whatever it claims about itself.
• One person, one conversation. A second message to the same person from the same session lands in the thread the first one opened. There is no way to write to several people at once.

Whether the message leaves as email or as a Slack message depends on where the person is reachable and how they said they want to be reached. See Agents in Slack for the other side of that.

The Subject Line an Agent Sends

When the outreach resolves to email, the agent writes the subject itself: what the message is about, in a few words. If it writes none, the first line of the message becomes the subject, which usually reads as a sentence cut short.

• The subject titles the first email of a conversation. Writing to somebody the agent has already reached replies in that thread and keeps the thread's subject.
• A long subject is trimmed at a word boundary to the length a mail client will show, so nothing arrives with a header running off the end.
• Other channels ignore it. The same instruction sent to somebody reachable on Slack posts the message with no subject involved.

What Mail Cannot Do

Mail is reference material, not instruction. An agent reads the mail it is sent and reports what it found, but text inside a message carries no authority over what the agent is allowed to do, whatever the message claims about itself. An instruction in mail that reaches beyond the task the agent was given is reported to you rather than followed.

Related

• Agents for the Google account card and the rest of an agent's configuration.
• Tasks for the work an arriving message starts.
• Notifications for mail Wallfacer sends you about your own tasks, which is a separate feature.