Email mailboxes

A mailbox connection lets workflows, compositions and agents work in your own inbox: list and search messages, read one with its attachments, mark messages read, watch a folder for new mail, and send from your address once a person has approved the exact message. Each mailbox is its own org-scoped connection, so an organization can connect as many as it needs.

There are two kinds, because the providers sign in differently:

Both kinds run the same email.* workflows. You name the mailbox in every run by its connection_uuid. There is no default mailbox.

Connect an IMAP/SMTP mailbox

In the console, open Connections, go to the Email category and choose Mailbox (IMAP/SMTP). Pick the provider, enter the address and the app password, select Test connection, then Connect.

An app password is a separate password your provider issues for one app. You can revoke it without changing your real password, and revoking it disconnects the mailbox. Never enter your account password.

For Other, IMAP must use port 993 (TLS) and SMTP must use 465 (SSL) or 587 (STARTTLS). Hosts must be public mail servers: names that resolve to loopback, private, link-local, multicast or reserved addresses are refused on every connect. Set Login username only when the server does not log in with the email address.

Test connection logs in to IMAP and to SMTP and never sends a message. Connect runs the same test and saves only if it passes.

From an assistant or the API

The same flow is connection.setup with provider_type email:

Pass dry_run: true to test without saving. get_workflow_prerequisites("connection.setup", variant="email") returns the full per-provider guide.

Connect a Microsoft 365 or Outlook.com mailbox

Microsoft retired password sign-in for IMAP and SMTP, so Microsoft mailboxes do not work as IMAP/SMTP connections. Use Microsoft 365 / Outlook instead:

1. In Connections → Email, choose Microsoft 365 / Outlook and select Sign in with Microsoft.
2. Microsoft always shows the account picker, so one person can connect several mailboxes. Pick the account.
3. Consent to the permissions below. You return to the console and the connection is saved, named after the mailbox address.

Orkestia asks for these delegated Microsoft Graph permissions, and only these:

You never paste a client ID, secret or token. Orkestia keeps the access and refresh tokens encrypted on the connection and refreshes them on its own.

Over the API this is connection.oauth-start then connection.oauth-exchange with provider_type microsoft_mail and the redirect URI https://app.orkestia.dev/connections/microsoft_mail/callback. get_workflow_prerequisites("connection.setup", variant="microsoft_mail") returns the guide.

Workflows

Every workflow takes connection_uuid (the mailbox) and refuses any connection that is not a mailbox of your organization. None of the read workflows mark anything read.

A message summary is {id, internet_message_id, folder, from, to, cc, subject, date, received_at, is_read, has_attachments, size_bytes, snippet, in_reply_to}. Pass its id to get or mark-read; both also accept an RFC Message-ID such as <abc@example.com>. Over IMAP, snippet is empty and folder counts are not reported.

Search takes plain words, not IMAP or Microsoft query syntax. Over IMAP it searches INBOX unless you name a folder; on Microsoft it searches the whole mailbox when folder is omitted.

Attachments go to your bucket

email.message.get never puts attachment bytes in the run. Give it a storage connection and a bucket and it copies each attachment there, returning a storage_object_uuid, bucket and key per file. Without a storage target you get the metadata only (file name, type, size). See object storage for the storage.* side.

When a message contains a meeting invite (a calendar part, an .ics attachment or an Outlook meeting request), get also returns it parsed as invite: title, start and end, time zone, organizer, attendees, location and meeting link.

Watching for new mail

email.inbox.poll is a bounded, read-only batch built to be fired by schedule.*. It returns next_cursor. Store it and pass it back on the next poll. On the first run, with no cursor, it starts from now and returns nothing unless you give since. has_more: true means more new mail is waiting; cursor_reset: true means the stored cursor no longer applied and was re-anchored. message_ids gives you idempotency keys, so a message seen twice can be skipped.

Sending needs a human approval

No workflow sends mail on the say-so of a script or an agent alone. Sending takes two runs:

1. email.message.send-with-approval validates the message and opens a review in the Staff inbox of the actor you name in actor_uuid. It returns approval_envelope_uuid and status: review_requested. Nothing is sent yet.
2. A person reviews the exact message (recipients, subject, body, attachments, mailbox) and approves it.
3. email.message.send with the same connection_uuid and that approval_envelope_uuid sends exactly the reviewed message. It takes no recipients, subject or body of its own, refuses an envelope approved for a different mailbox, and sends once: calling it again returns the first result with deduped: true.

Optional fields on the request: cc, bcc, reply_to, from_name, attachment_storage_object_uuids (storage objects of your organization), reply_to_message_id (threads the message as a reply), review_title, review_reason, and connector_uuid to notify an inbox connector.

On IMAP/SMTP mailboxes, save_to_sent (default on) files a copy in the Sent folder. Gmail files its own copy, so Orkestia skips it there.

Limits

Security and what is stored

• One credential per mailbox, encrypted. An IMAP/SMTP connection stores the address, the provider preset or server settings, and the app password (encrypted). A Microsoft connection stores the address, the account kind (work or personal) and the access and refresh tokens (encrypted). Workflow inputs never carry the credential.
• TLS only. IMAP on 993, SMTP on 465 or 587 with STARTTLS. Server addresses are checked on every connect.
• Orkestia does not copy your mailbox. A run reads what it asked for and returns it as that run's output, within the caps above. Attachments only leave the mailbox when you name a bucket in your own storage.
• Revoke at the source. Revoke the app password in the mail account, or remove Orkestia from the Microsoft account, and the next run fails. Deleting the connection in the console removes it from Orkestia.

Managing a mailbox connection

• Rotate an app password: edit the connection, paste a new app password made in the same mail account, then revoke the old one there.
• Microsoft grant expired or revoked: edit the connection and select Sign in with Microsoft again.
• Check it still works: run email.mailbox.verify.

Troubleshooting