search_emails
Search email messages by keywords, sender, subject, or body. Returns matching emails with summary information, and supports filtering by folder, time range, and Focused Inbox.
Instructions
SEARCH EMAIL MESSAGES ONLY. Search or list email messages by keywords, sender, subject, or body. Returns matching email messages with summary information. DO NOT use this to find people/contacts - use search_contacts for that. If no search_type and query are provided, lists emails within the specified time range. All time parameters use your local timezone. PARAMETER PRECEDENCE (highest to lowest): 1) time_range (overrides all other time parameters), 2) start_date/end_date (overrides days), 3) days (used only if no other time parameters provided). IMPORTANT FOR OLD EMAILS: The 'days' parameter has a maximum limit (default 90 days). To search emails older than this limit, use start_date/end_date parameters instead - they have NO date range restriction and can search any historical emails. Example: start_date='2023-01-01', end_date='2023-12-31'. FOCUSED INBOX: By default, searches only 'focused' emails (Outlook's Focused Inbox). Use inference_classification='other' to search 'other' emails, or inference_classification='all' to search both. Returns: {success: boolean, emails: array, count: integer, date_range: string, filter_date_range: string, timezone: string}. Note: Rate limit errors (HTTP 429) return retry_after field with seconds to wait. Invalid folder paths return appropriate error messages.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days to look back. Default: 7, maximum: 90. LOWEST PRIORITY: Used only when no time_range, start_date, or end_date are provided. **TIP**: For searching emails older than 90 days, use start_date and end_date parameters instead. | |
| query | No | Search query for email messages. For 'sender': email address only. For 'subject': subject text. For 'body': body text content. Required when search_type is provided. Optional - if not provided with search_type, lists emails within the time range | |
| folder | No | Optional folder path to search (e.g., 'Inbox', 'Inbox/Projects', 'Archive/2024'). Default: Inbox | Inbox |
| end_date | No | End date in your local timezone (e.g., '2024-12-31' or '2024-12-31T23:59'). Overridden by time_range if both are provided. **NO DATE RANGE LIMIT**: Unlike 'days' parameter, end_date has no restriction - use this to search old emails beyond the default 90-day limit. **SPECIAL VALUE**: Use 'now' to search from start_date until current time (e.g., start_date='2024-01-01', end_date='now' searches from Jan 1 to now). | |
| start_date | No | Start date in your local timezone (e.g., '2024-01-01' or '2024-01-01T14:30'). Overridden by time_range if both are provided. **NO DATE RANGE LIMIT**: Unlike 'days' parameter, start_date has no restriction - use this to search old emails beyond the default 90-day limit. | |
| time_range | No | Time range type (case-insensitive). Optional, in your local timezone. Accepted values: 'today', 'tomorrow', 'this_week', 'next_week', 'this_month', 'next_month' (any case). HIGHEST PRIORITY: If provided, overrides start_date, end_date, and days. Returns a user-friendly display string in the response. Examples: 'today', 'Today', 'THIS_WEEK', 'Next_Month' | |
| search_type | No | Type of search to perform (optional). Options: 'sender' (search by sender email address only), 'subject' (search by subject text with exact substring matching), 'body' (search by body content with exact substring matching). If not provided, lists emails within the time range without filtering | |
| inference_classification | No | Filter by Outlook Focused Inbox classification. 'focused' (default): important emails shown in Focused tab. 'other': less important emails shown in Other tab. 'all': search both focused and other emails. Default: focused | focused |