Skip to main content

Outlook Mail

Work a Microsoft 365 mailbox from an agent: list and search Outlook messages, read full bodies and attachments, file mail into folders, and draft or send as the connected account.

Every tool type on this page requires an Outlook connector — an OAuth connection to the Microsoft account whose mailbox the agent should work in. Calls go through the Microsoft Graph API, and Autessa refreshes the OAuth token automatically before each request. See Connectors for how to link an account.

One family-wide convention: listing and search tools return compact six-character message IDs instead of Graph's very long native IDs. These short IDs are valid for four hours — if a downstream call reports that a short ID has expired, re-run the list or search to get fresh ones. Folder fields accept both real folder IDs and well-known names such as inbox, sentitems, drafts, and deleteditems.

List Unread TOOLOUTLOOK_LIST_UNREAD​

Lists unread messages in one folder — the inbox by default, or whatever folderId names. The response contains totalResults and a messages array where each entry carries the short id, subject, from, to and cc recipient lists, receivedDateTime, a bodyPreview excerpt, and hasAttachments. Previews keep the listing light; follow up with Get Message by ID when the agent needs a full body. maxResults defaults to 10.

Example​

Tool config
{
  "toolType": "OUTLOOK_LIST_UNREAD",
  "connectorId": "V1StGXR8Z5",
  "maxResults": 25,
  "folderId": "inbox"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    maxResults
    Type
    integer
    Description
    Required integer value.
  • Name
    folderId
    Type
    string
    Description
    Required string value.

Mark as Read TOOLOUTLOOK_MARK_AS_READ​

Sets isRead on a single message, marking it read in the connected mailbox. Agents typically call this after handling a message surfaced by List Unread so the same email is not processed twice. Accepts either a short ID from a previous listing or a raw Graph message ID, and echoes the messageId back on success.

Example​

Tool config
{
  "toolType": "OUTLOOK_MARK_AS_READ",
  "connectorId": "V1StGXR8Z5",
  "messageId": "@@{messageId}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    messageId
    Type
    string
    Description
    Required string value.

Move to Folder TOOLOUTLOOK_MOVE_TO_FOLDER​

Moves a message into another mail folder — how an agent archives, files, or triages Outlook mail. destinationFolderId accepts a real folder ID or a well-known name like archive or deleteditems. Note that Microsoft Graph assigns a moved message a new identity: the result returns newMessageId, and any earlier ID for that message stops referring to the moved copy.

Example​

Tool config
{
  "toolType": "OUTLOOK_MOVE_TO_FOLDER",
  "connectorId": "V1StGXR8Z5",
  "messageId": "@@{messageId}",
  "destinationFolderId": "archive"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    messageId
    Type
    string
    Description
    Required string value.
  • Name
    destinationFolderId
    Type
    string
    Description
    Required string value.

Create Draft Reply TOOLOUTLOOK_CREATE_DRAFT_REPLY​

Drafts a threaded reply to an existing message using Graph's native reply machinery, so the subject, conversation, and quoting behave exactly as if the user hit Reply in Outlook. With replyAll unset or true the original To and Cc recipients are kept; the connected mailbox's own address is always filtered out of the recipient lists. If the conversation already ends in a draft, that draft is updated in place instead of duplicated and the result carries updated: true. The result returns the draftId plus the resolved toRecipients and ccRecipients; provide the reply text in body or bodyHtml (HTML wins when both are set), and nothing is sent until a Send Draft call.

Example​

Tool config
{
  "toolType": "OUTLOOK_CREATE_DRAFT_REPLY",
  "connectorId": "V1StGXR8Z5",
  "messageId": "@@{messageId}",
  "body": "@@{replyText}",
  "replyAll": true
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    messageId
    Type
    string
    Description
    Required string value.
  • Name
    body
    Type
    string
    Description
    Required string value.
  • Name
    bodyHtml
    Type
    string
    Description
    Required string value.
  • Name
    replyAll
    Type
    boolean · optional
    Description
    Optional; null is treated as true (reply all)
  • Name
    attachments
    Type
    array<object> · optional
    Description
    Optional; replaced in full when the draft is updated

Create Draft TOOLOUTLOOK_CREATE_DRAFT​

Creates a fresh draft in the mailbox's Drafts folder addressed from the connected account. to, cc, and bcc take comma-separated address lists; the message is sent as HTML when bodyHtml is set, otherwise as plain text from body. The result returns the draft's short draftId to pass to Send Draft, leaving the draft available for human review in Outlook before anything goes out.

Example​

Tool config
{
  "toolType": "OUTLOOK_CREATE_DRAFT",
  "connectorId": "V1StGXR8Z5",
  "to": "@@{recipientEmail}",
  "subject": "Your onboarding checklist",
  "body": "@@{draftText}",
  "cc": "success@acme.example"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    to
    Type
    string
    Description
    Required string value.
  • Name
    subject
    Type
    string
    Description
    Required string value.
  • Name
    body
    Type
    string
    Description
    Required string value.
  • Name
    bodyHtml
    Type
    string
    Description
    Required string value.
  • Name
    cc
    Type
    string
    Description
    Required string value.
  • Name
    bcc
    Type
    string
    Description
    Required string value.
  • Name
    attachments
    Type
    array<object> · optional
    Description
    Optional

Send Draft TOOLOUTLOOK_SEND_DRAFT​

Sends an existing draft — the counterpart to Create Draft and Create Draft Reply in a review-then-send workflow. Pass the draft's ID in messageId (short IDs and raw Graph IDs both work); Outlook delivers the draft exactly as it stands, including any human edits made since the agent created it, and files it in Sent Items.

Example​

Tool config
{
  "toolType": "OUTLOOK_SEND_DRAFT",
  "connectorId": "V1StGXR8Z5",
  "messageId": "@@{draftId}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    messageId
    Type
    string
    Description
    Required string value.

Send Email TOOLOUTLOOK_SEND_EMAIL​

Sends a message immediately from the connected account with no draft step and no human checkpoint — reserve it for agents trusted to send autonomously, and prefer the draft tools when a review step is wanted. At least one of body or bodyHtml is required (HTML wins when both are set), recipients are comma-separated lists, and a copy is saved to Sent Items. The result confirms the to and subject that were sent.

Example​

Tool config
{
  "toolType": "OUTLOOK_SEND_EMAIL",
  "connectorId": "V1StGXR8Z5",
  "to": "@@{recipientEmail}",
  "subject": "@@{subject}",
  "body": "@@{messageText}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    to
    Type
    string
    Description
    Required string value.
  • Name
    subject
    Type
    string
    Description
    Required string value.
  • Name
    body
    Type
    string
    Description
    Required string value.
  • Name
    bodyHtml
    Type
    string
    Description
    Required string value.
  • Name
    cc
    Type
    string
    Description
    Required string value.
  • Name
    bcc
    Type
    string
    Description
    Required string value.
  • Name
    attachments
    Type
    array<object> · optional
    Description
    Optional

Get Message by ID TOOLOUTLOOK_GET_MESSAGE_BY_ID​

Fetches one message in full — the only Outlook mail tool that returns the complete body rather than a preview. The result's email object carries the subject, from, the to/cc/bcc recipient lists, receivedDateTime, bodyPreview, the full bodyContent (HTML or text as stored), conversationId, isRead, hasAttachments, and any follow-up flag. Use it after a list or search call when the agent needs everything about a specific message.

Example​

Tool config
{
  "toolType": "OUTLOOK_GET_MESSAGE_BY_ID",
  "connectorId": "V1StGXR8Z5",
  "messageId": "@@{messageId}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    messageId
    Type
    string
    Description
    Required string value.

Get Attachment Content TOOLOUTLOOK_GET_ATTACHMENT_CONTENT​

Fetches a single attachment and returns its bytes decoded as UTF-8 text in content, alongside name, contentType, and size. This is the right tool for text-based attachments — CSV exports, logs, plain-text or HTML files — where the agent should read the content inline. Binary formats (PDF, Office documents, images) are not text-decoded meaningfully; use Get Attachment Download Link to hand those off as base64 data instead. Attachment IDs come from Search Messages results on messages with hasAttachments: true.

Example​

Tool config
{
  "toolType": "OUTLOOK_GET_ATTACHMENT_CONTENT",
  "connectorId": "V1StGXR8Z5",
  "messageId": "@@{messageId}",
  "attachmentId": "@@{attachmentId}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    messageId
    Type
    string
    Description
    Required string value.
  • Name
    attachmentId
    Type
    string
    Description
    Required string value.

Get Attachment Download Link TOOLOUTLOOK_GET_ATTACHMENT_DOWNLOAD_LINK​

Fetches a single attachment and returns its raw data for downstream use: the result carries name, contentType, size, and the file's unmodified base64 payload in contentBase64. Unlike the Gmail equivalent, this tool currently returns the base64 data directly rather than a hosted download URL — suitable for passing the file to another tool or storing it, less so for handing a clickable link to a person.

Example​

Tool config
{
  "toolType": "OUTLOOK_GET_ATTACHMENT_DOWNLOAD_LINK",
  "connectorId": "V1StGXR8Z5",
  "messageId": "@@{messageId}",
  "attachmentId": "@@{attachmentId}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.
  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    messageId
    Type
    string
    Description
    Required string value.
  • Name
    attachmentId
    Type
    string
    Description
    Required string value.
  • Name
    saveToTableId
    Type
    string (ID) · optional
    Description
    Optional: store the attachment as a file in this AutessaDB table (same company) instead of returning it; the result's `s3Uri` is what to write into that column's filePath. Lets a script (which has no IO) put email attachments into a table. Set together with saveToColumnName. References an AutessaDB table by ID.
  • Name
    saveToColumnName
    Type
    string · optional
    Description
    Optional (required with saveToTableId): the FILE, IMAGE, VIDEO or AUDIO column the file is stored for. It must accept the file's type; a FILE column takes any type.

Search Messages TOOLOUTLOOK_SEARCH_MESSAGES​

Searches the mailbox in one of two modes. When query is set, it runs a Graph full-text search with that string and the structured fields are ignored. Otherwise the structured fields are combined into a filter: exact sender match on from, substring match on subject, hasAttachment, an after/before received-date window (dates in yyyy-MM-dd), and isUnread. Scope the search to one folder with folderId, or leave it unset to search the whole mailbox. Results mirror List Unread (short id, subject, from, recipients, receivedDateTime, bodyPreview, isRead, hasAttachments), and messages with attachments additionally include an attachments array of {id, name, contentType, size} metadata for the attachment tools. maxResults defaults to 10.

Example​

Tool config
{
  "toolType": "OUTLOOK_SEARCH_MESSAGES",
  "connectorId": "V1StGXR8Z5",
  "from": "@@{senderEmail}",
  "subject": "invoice",
  "hasAttachment": true,
  "after": "2026-06-01",
  "isUnread": true,
  "maxResults": 20
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    from
    Type
    string
    Description
    Required string value.
  • Name
    to
    Type
    string
    Description
    Required string value.
  • Name
    subject
    Type
    string
    Description
    Required string value.
  • Name
    query
    Type
    string
    Description
    Required string value.
  • Name
    hasAttachment
    Type
    boolean
    Description
    Required boolean value.
  • Name
    after
    Type
    string
    Description
    Required string value.
  • Name
    before
    Type
    string
    Description
    Required string value.
  • Name
    folderId
    Type
    string
    Description
    Required string value.
  • Name
    isUnread
    Type
    boolean
    Description
    Required boolean value.
  • Name
    maxResults
    Type
    integer
    Description
    Required integer value.