Email Setup

Overview

The Email channel lets Anyy receive mail through IMAP and reply through SMTP. It is a messaging gateway adapter: incoming email becomes a resident Anyy session, and replies are sent back into the same email thread.

This page is only about the gateway channel. It does not document mailbox management or calendar connector tools.

Prerequisites

• A dedicated mailbox for Anyy.
• IMAP access enabled on that mailbox.
• SMTP access for the same address.
• An app password or service password when the mail provider requires it.
• The IMAP host and SMTP host.

Setup

Create credentials

Create the mailbox credentials with your mail provider. For providers with two-factor authentication, use an app password rather than the account password.

Anyy needs:

Value	Config field
Email address	address
IMAP host	imap_host
SMTP host	smtp_host
Mailbox password or app password	password_ref secret

Configure Anyy

Use the non-interactive setup helper:

anyy setup channels email \
  --set [email protected] \
  --set imap_host=imap.example.com \
  --set smtp_host=smtp.example.com \
  --secret password='app-password' \
  --write-config

The helper writes channels.email and stores the password as an Anyy secret. It also writes these defaults:

Field	Default
account_id	mailbox
imap_port	993
smtp_port	587
mailbox	INBOX
poll_interval_ms	15000
dm_policy	open
send_chunk_chars	50000

Edit config.yaml if your provider uses different ports or a different mailbox.

Start Gateway

anyy gateway start
anyy channels reload

Run doctor checks

anyy channels doctor email
anyy doctor

Doctor validates required fields and secret references. It does not log in to the mail provider.

Access Policy

Direct messages

Email is a direct-message channel. dm_policy supports the shared direct message policies:

Policy	Behavior
open	Any sender can start a session.
allowlist	Only senders in allow_from are accepted.
disabled	Incoming mail is ignored.

For personal deployments, use an allowlist:

channels:
  email:
    dm_policy: allowlist
    allow_from:
      - [email protected]

Groups

Email does not have group-channel support in Anyy. Use allow_from to control sender access.

Admins

Channel access and command authorization are separate. Email decides whether a message enters Anyy; command permissions are handled by the shared messaging command layer.

Sessions

Each accepted sender/thread maps to an Anyy messaging session. Replies keep the provider thread headers when available, so normal mail clients show the conversation as a thread.

Media Support

Inbound media

The Email channel currently handles text email. Attachments are not advertised as inbound media by the adapter.

Outbound media

The Email channel sends text replies. Generated artifacts remain available in the session, but this adapter does not advertise native outbound media.

Commands

Messaging commands use the same command dispatcher as other channels. Send a text command such as /status or /stop in the email body when command permissions allow it.

Cron Delivery

Email can be used as a delivery channel for scheduled jobs once the sender or default binding is configured:

anyy cron create \
  --name "Morning email" \
  --schedule "0 9 * * *" \
  --prompt "Send my morning summary" \
  --delivery-target current_user_default \
  --delivery-channel email

Troubleshooting

• No messages arrive: confirm imap_host, imap_port, mailbox name, and the provider's IMAP setting.
• Replies fail: confirm smtp_host, smtp_port, and whether the provider requires an app password.
• Unauthorized sender: check dm_policy and allow_from.
• Doctor passes but runtime fails: doctor checks config shape; provider login errors appear in gateway logs and channel status.