π«π· Version franΓ§aise
Give your agents a mailbox
See also: E-mail tools Β· Write a crew in TypeScript Β· CLI reference Β· Back to the index
In about fifteen minutes you will run an agent that triages a real Gmail inbox: it reads the unread mail, files each message into a folder by kind, and writes the replies as drafts a human reviews and sends. Nothing is sent. This page is the short path through one bundled example; the E-mail tools guide is the full reference.
What you get
The example is 13-email-triage.ork.ts
and its settings file 13-email-triage.appsettings.json.
Three rules hold the e-mail tools together, and the example leans on all three:
- An agent only names an account. Servers, credentials and rights are the operator's settings (
Orkeon:Tools:Email). - The account's
Rightsdecide what an agent may do, and sending stays closed untilSend:AllowedRecipientslists who may receive mail. - Received mail is data, never instructions. Every read result carries the verdict of a prompt-injection screen.
Prerequisites
| You need | Notes |
|---|---|
| Orkeon | A clone of the repository, or the installed orkeon tool β see Three ways to run Orkeon. A .ork.ts script also needs esbuild: the release archives ship it, a clone installs it on its first build, and the dotnet tool does not ship it β npm install -g esbuild (where it is looked up; orkeon doctor checks it). |
| A model | The example's settings point at a local Docker Model Runner (ai/granite-4.0-h-tiny on localhost:12434). Any profile of examples/appsettings/ works: a run resolves one settings file, so copy that profile's Llm section into the example's file. |
| A Gmail account | With 2-Step Verification turned on β app passwords do not exist without it. |
1. Create a Gmail app password
Open https://myaccount.google.com/apppasswords, create an app password named
Orkeon, and copy the 16 letters Google shows β without the spaces between the groups. If Google says app passwords are not available for your account, use Gmail with OAuth2 instead.Export it in the shell that will run the example:
export TRIAGE_GMAIL_APP_PASSWORD='abcdefghijklmnop' # bash / zsh$env:TRIAGE_GMAIL_APP_PASSWORD = 'abcdefghijklmnop' # PowerShell
2. The settings
The example's settings file declares one account under Orkeon:Tools:Email (its Llm
section, and the Scripting time limit covered in step 4, are left out here). Replace the address with yours:
"Orkeon": {
"Tools": {
"Email": {
"DefaultAccount": "triage",
"Accounts": {
"triage": {
"Provider": "Gmail",
"Address": "your.name@gmail.com",
"Rights": "Read, Organize, Draft",
"Auth": {
"Method": "Password",
"PasswordEnvVar": "TRIAGE_GMAIL_APP_PASSWORD"
}
}
}
}
}
}
Provider: Gmailis a preset: it fills inimap.gmail.com:993for reading andsmtp.gmail.com:465for sending, both TLS.PasswordEnvVarnames the environment variable that holds the password. The secret is never in the file, and never a tool argument β tool arguments are logged. The variable may have any name.Rightsis mandatory.Read, Organize, Draftlets the agent search and read, create folders and move mail, and save drafts β exactly what the script uses. It cannot send, delete or purge anything; a call outside the rights fails with a message naming the missing right.DefaultAccountis the account a call that names none uses. With a single account it could be left out; the script names no account at all.
3. Check the account from the terminal
The orkeon email commands are the operator's side of the family β agents never run them.
From a clone, replace orkeon with dotnet run --project src/scripting/Orkeon.Scripting.Cli --.
orkeon email accounts --settings examples/scripting/13-email-triage.appsettings.json
orkeon email check triage --settings examples/scripting/13-email-triage.appsettings.json
accountsopens no connection: it liststriage (default), its address, how it reads and sends, its rights, and saysreadyβ orNOT READY:followed by what to fix (typically the variable that is not set in this shell).checkconnects, authenticates and lists the folders, then printsE-mail account 'triage' is reachable:with the number of folders and the inbox counts.
Exit codes: 0 success, 1 something you fix (the settings, an unknown account, a variable
not set), 2 what the server or the network did (a refused password, a connection failure),
130 Ctrl+C. The settings file in use is named on stderr (Using settings: β¦).
4. Run the triage
From a clone, at the repository root:
dotnet run --project src/scripting/Orkeon.Scripting.Cli -- run examples/scripting/13-email-triage.ork.ts \
--settings examples/scripting/13-email-triage.appsettings.json
With the installed tool, put the two example files side by side and run:
orkeon run 13-email-triage.ork.ts --settings 13-email-triage.appsettings.json
What the script does, in order:
- It stops at once if the settings declare no model β the echo that answers without one cannot sort mail.
- It creates the folders
Triage/Reply,Triage/Read,Triage/NewslettersandTriage/Review(labels on Gmail). An existing folder is left as it is, so every run can do this. - It takes one page of the inbox: the ten newest unread messages (
email_search). Reading them (email_read) leaves them unread. - A message the prompt-injection screen does not rate
cleannever reaches the model: it goes toTriage/Review. The others are handed to the model fenced, as data, and sorted intoreply,readornewsletter; any other answer also goes toTriage/Review. - For a
reply, the model writes a short answer and the script saves it as a reply draft (email_draft) β it waits in Gmail's Drafts. - Each message is then moved to its folder (
email_move), one at a time: a run that stops half-way has filed what it finished, and the next run starts on the rest.
The run ends by printing its result as JSON on stdout β the agent's summary line, the count filed per kind, and the number of drafts:
{
"result": {
"output": "sorted 10 message(s), 3 draft(s) to review",
"filed": { "reply": 3, "read": 4, "newsletter": 2, "review": 1 },
"drafts": 3
}
}
The numbers above are illustrative. Open Gmail: the inbox has lost those messages, the
Triage/β¦ labels hold them, and Drafts holds the replies, for you to edit and send β or not.
A time limit applies. The scripting sandbox bounds a whole run to 30 seconds of wall-clock time by default, the awaited mail and model calls included, and ten messages through a local model take longer. The example's settings file raises the bound to ten minutes,
"Orkeon": { "Scripting": { "Limits": { "ExecutionTimeout": "00:10:00" } } }next toTools; keep that block when you write your own settings file. Messages filed before a stop stay filed.
5. Adapt it
Other folders, other kinds. The
foldersobject at the top of the script maps each kind to a folder, andkindslists what the model may answer; change both, and the prompt that names the kinds.emailSearchtakes more criteria (from,subject,since,limitup to 50β¦) β the parameters list them. In a script, tool names are camelCased (tools.emailSearch) but argument keys keep the tools' snake_case (unread_only,reply_to_id).Let it send β safely. Add
SendtoRightsand list the recipients: untilSend:AllowedRecipientsholds at least one entry,email_sendrefuses every message. Entries are addresses,*@domainor*; To, Cc and Bcc are all checked, andMaxRecipients/MaxPerHourcap the volume. Drafts stay the better path for anyone outside your own addresses. See Rights and the send allow-list."Rights": "Read, Organize, Draft, Send", "Send": { "AllowedRecipients": [ "your.name@gmail.com" ], "MaxPerHour": 10 }From a YAML crew instead. The runner host behind
orkeon runregisters the thirteenemail_*tools, so a YAML agent lists them by name βtools: [email_accounts, email_search, email_read, email_move, email_draft]β and the model decides the calls. Declare the accounts in that crew's own settings file (it holds the crew'sLlmsection too), not in anappsettings.jsonof the directory you run from, nor in environment variables: those reach every run. See From a YAML crew.orkeon forgeoffers the mailbox tools to the crews it forges and tries them on a fictitious mailbox: see Forged crews.
Other mailboxes
- Hotmail and Outlook.com go through Microsoft Graph with OAuth2: register an application once, then sign in once with
orkeon email login <account>β Hotmail and Outlook.com (Microsoft Graph). - Gmail without an app password: Gmail with OAuth2.
- Your own server, over IMAP or POP3 and SMTP, with the
Custompreset: Your own server (IMAP, POP3, SMTP). - Where OAuth tokens are stored, and what that protects: Where the tokens live.
- Something refuses? Every error names its fix; the usual ones are in Troubleshooting.
Gmail and Hotmail are campaigned. The path of this tutorial β a Gmail app password β was run against a real account on 2026-10-04, and Gmail with OAuth2 on 2026-10-05: see What the Gmail campaign established. Hotmail through Microsoft Graph was run against a real account on 2026-10-12.