Tools: email

If an email account is configured, the assistant can search the mailbox, read messages and attachments, mark emails as processed or archive them, create reply drafts, and send messages. These tools only appear once an account is set up → Email mailboxes.

Tool	Purpose	Type	Available
Search mailbox (SearchMailbox)	Finds emails by sender, subject, date or content.	Read	when configured
Read email (ReadEmailBody)	Opens the body text of an email.	Read	when configured
Download attachment (DownloadEmailAttachment / DownloadMailAttachment)	Downloads an email attachment for further processing.	Read	when configured
Mark as processed (MarkEmailProcessed)	Flags an email as handled.	Write	when configured
Archive email (ArchiveEmail)	Moves an email to the archive.	Write	when configured
Create reply draft (CreateReplyDraft)	Stores a reply as a draft in the mailbox’s “Drafts” folder without sending it. Microsoft 365 and IMAP only.	Write	when configured
Send email (SendEmail)	Sends a message.	Write	when configured
File into the knowledge base (ImportToKnowledgeBase)	Files an email, or one of its attachments, as an article through the import pipeline. Agents only.	Write	when configured, agent with “Run as”

Where an attachment lands: In the desktop app, the assistant saves a downloaded attachment in the attached working folder, otherwise in the output folder; below the answer, a file chip shows it in its folder. An agent with a storage target saves the attachment in the target instead, with a vault target in the attachments/ subfolder. → Where does CompanyWizard save documents?, Chain agents

Send security: SendEmail runs through the secured org SMTP — a fixed sender address and a recipient allowlist; the assistant cannot write to arbitrary addresses.

Reply drafts: CreateReplyDraft stores the reply in the “Drafts” folder, linked to the original email as a reply and with the original quoted below. Nothing is sent: you open the draft in your mail client, review it and send it yourself. With PII protection on, the draft contains the real names and addresses, not the placeholders. A POP3 or Exchange (EWS) mailbox, and an IMAP server that reports no drafts folder, cannot hold drafts; the assistant tells you so. In an agent’s dry run no draft is created; the call only shows up in the plan.

Assessing many emails one by one: If several emails each have to be read and assessed, the assistant reads each one in a run of its own and gets a table with one row per email. → Tools: Process many files or mails one by one

Distinction: These are the assistant’s built-in email tools. Not to be confused with the configurable mailbox tool that administrators connect as a separate data source — its setup is covered in a dedicated article (wz-11).

Filing emails and attachments in the knowledge base

An agent with a mail source can file emails or attachments into a knowledge vault with ImportToKnowledgeBase. The model never sees the content: it only names source and target, and the answer is one line (the path, “already filed”, or the reason it was refused).

Parameter	Meaning
sourceKind	mail (the email itself as one article, attachments kept as linked files) or attachment (one attachment as its own article; the email itself is not filed).
mailAccountName, handle	Account and message handle, taken unchanged from the mail list.
attachmentName	attachment only: the file name as ReadEmailBody lists it.
vaultSlug, folder	Target vault and folder inside it (empty = vault root).
tags, classification	Optional. Without a classification the vault default applies.
converter	attachment only: standard (default) or ocr for scans.

Requirements and permissions

• The agent must run as a user (“Run as”). Without a user the tool is not offered.
• The agent files only where its user may also import manually. The tool refuses read-only vaults.
• If the agent has a “Vault” storage target, the target sets the vault; folder lies below the target folder (a folder already inside the target stays as it is). Without Allow subfolders the tool files directly into the target folder. → Chain agents
• Nothing is filed during the license grace period (the email stays open and does not use up an attempt).

Behaviour

• Duplicates: Anything already in the knowledge base is skipped (“already filed”). If the article was deleted, it is filed again next time.
• Attachment articles are named “YYYY-MM-DD file name.md” (the email’s date). If the name exists, “ (2)” is appended; nothing is overwritten.
• HTML emails are imported with the HTML part first, so links and images are kept. With a vault storage target, the agent’s Mail filing setting decides the form: Content files cleaned Markdown (newsletter layouts become text, online images stay), Presentation keeps the layout. ReadEmailBody also returns HTML-only emails as cleaned Markdown. → Chain agents
• Scans: A PDF without recognised text is not filed; the tool asks to retry with converter: "ocr". OCR needs a configured OCR model.
• IMAP folders: The mail tools also work in folders other than the default; the handle carries the folder.

When filing fails: The mail source keeps its read position and offers the email again on the next run. After 3 attempts it is skipped; one attempt is one run per email, not one tool call. The run stays “successful”; a warning block precedes the summary with two groups: retried next run and skipped after 3 attempts, please file by hand. Refusals caused by configuration (account, vault, read-only) do not count as an attempt; the mail source keeps its read position and offers the emails again on every run until the configuration is fixed.

Limits

• Emails without a Message-ID cannot be recognised as duplicates.
• Very short real attachments (under about 50 letters and digits) count as “no text”.
• Scheduled agents on the desktop app run only while the app is open.

Recipe 1: newsletter agent

Mail source with a sender filter (newsletter@a.de, info@b.de). Prompt template:

You sort incoming emails. For each email:
1. Decide from sender, subject and preview whether it is a newsletter or advertising.
2. Newsletter: call ImportToKnowledgeBase with sourceKind "mail", vaultSlug "default",
   folder from the table. Call MarkEmailProcessed only after filing succeeded
   or reported "already filed".
3. Advertising: only MarkEmailProcessed, file nothing.
4. Unsure: file it with tags ["pruefen"] (tags are lowercase kebab-case without umlauts, hence not "prüfen"). Better one ad too many than a lost newsletter.

Sender -> folder:
newsletter@a.de -> Newsletter/A
info@b.de       -> Newsletter/B

Recipe 2: receipts agent

Mail source without a sender filter. Prompt template:

For each email:
1. Call ReadEmailBody (you need the list of attachments).
2. Decide from sender, subject, text and file name: quote, invoice, or neither.
3. For each PDF attachment of an invoice: ImportToKnowledgeBase with sourceKind "attachment",
   attachmentName as listed, vaultSlug "default", folder "Rechnungen/2026".
   Quotes: folder "Angebote/2026".
4. If the tool reports "no text recognised", repeat the call with converter "ocr".
5. MarkEmailProcessed only after all attachments are filed or "already filed".
   If the email is neither invoice nor quote: only MarkEmailProcessed.

Create agents as in → Create and test an agent; mailboxes → Email mailboxes.