Email

Email

You can read the connected mailbox, search it with structured filters, and create drafts. Reading an email also surfaces its attachments — you can download one into your workspace with email_get_attachment for other tools to use. Whether you can also send email depends on this agent's configured permissions — sending is a distinct, explicitly granted capability (email.send), separate from reading, searching, and drafting. Do not assume you have it. Only use email_send if it appears in your available tools, and even then, treat it as a real, immediate, irreversible action, not a formality.

Capabilities

• email_list — List emails from a mailbox folder. Parameters: folder (optional, one of INBOX, SENT, DRAFTS, TRASH, SPAM; defaults to INBOX), limit (optional number, defaults to 20), unreadOnly (optional boolean, defaults to false). Returns summaries (sender, subject, date, snippet) — use this for a general overview.
• email_read — Read the full content of one email. Parameters: id (required string, the message ID). Returns the complete body, headers, and metadata, including a list of any attachments (id, filename, mimeType, size) with a hint to use email_get_attachment if you need one of them. Always use this before drafting a reply so you're working from the real content, not a snippet.
• email_get_attachment — Download an attachment surfaced by email_read and save it into the agent's workspace uploads/ directory. Parameters: messageId (required string, the message that has the attachment), attachmentId (required string, an attachment id shown by email_read). This is part of the read scope — no separate permission is needed beyond email read access. It does not return the file's content: it returns the saved filename, size, and mime type once the file is written to disk, so other tools (like pinchy_read or odoo_attach_file) can then read it from the workspace. The saved filename may be sanitized or de-duplicated and can differ from the original attachment name — always use the filename the tool returns, not the one you saw in email_read. Attachments larger than 25 MB are rejected (the cap matches odoo_attach_file, so anything saved can be handed off) — check the size shown by email_read before downloading.
• email_search — Search the mailbox using a structured set of fields, not a query string. Parameters: from (optional string, sender email address), to (optional string, recipient email address), subject (optional string, subject text match), text (optional string, free-text search across sender, subject, AND body — use this for content matches, like an invoice number, an order ID, or a phrase mentioned in the message body; subject only matches the subject line), unread (optional boolean), sinceDays (optional number, emails newer than this many days), folder (optional, one of INBOX, SENT, DRAFTS, TRASH, SPAM), limit (optional number, defaults to 20). At least one of from, to, subject, text, unread, or sinceDays must be set — folder and limit only scope the results and do not count as filters. You pass these fields as plain values — you never write Gmail search syntax or Microsoft Graph OData/$search syntax; the underlying adapter translates your structured fields into whatever query language the connected provider needs. When text is combined with unread or sinceDays on a Microsoft 365 mailbox, those two are applied as best-effort filters on the results rather than the server-side date sort you get otherwise — full-text search and structural date/unread filtering can't be combined server-side on that provider — so treat matches as relevance-ranked, not guaranteed complete for a narrow date window.
• email_draft — Create a draft email. Parameters: to (required string), subject (required string), body (required string, plain text), replyTo (optional string, a message ID to reply to). The draft is saved to the mailbox's Drafts folder for a human to review and send — prefer this over email_send whenever the user hasn't clearly asked you to send immediately.
• email_send — Only available if this agent has been explicitly granted the email.send permission; most email agents are not. Takes the same parameters as email_draft (to, subject, body required; replyTo optional). Sends an email immediately and cannot be undone. If this tool is not in your available tools, you cannot send email — say so plainly rather than claiming a draft was sent.

Do not assume email_send exists just because this skill is attached. Check your actual available tools before telling the user what you can do.

When to use

• The user asks what's in their inbox, or wants unread messages summarized
• The user asks to find a specific email or set of emails ("did X email me about Y", "find the invoice from last week") — a content/topic lookup like this is email_search with text set, not subject, unless the user specifically says it's in the subject line
• The user wants a thread or message summarized
• The user wants a reply or new message drafted for them to review

When NOT to use

• To send an email when you don't have the email_send tool available — draft instead, and tell the user plainly that you can't send from this agent
• Anything requiring real-time delivery guarantees or confirmation of receipt beyond what the tool result reports
• General knowledge questions unrelated to the mailbox