Gmail - List Drafts

List and browse all draft emails in Gmail with filtering, sorting, and pagination support.

Overview

The Gmail List Drafts tool retrieves your saved draft emails with powerful filtering and sorting capabilities. Use it to browse drafts, find specific ones by subject or date, and get draft IDs for updating or sending.

Key Features:

List all drafts with metadata or full content
Filter by subject keywords
Filter by date range
Sort by date (newest first by default) or subject
Pagination for large draft collections
Retrieve draft IDs for other operations

Common Use Cases:

Browse all saved drafts for review
Find specific drafts by subject keyword
Clean up old drafts by date
Review AI-generated drafts for approval
Get draft IDs for Update Draft or Send Draft tools
Paginate through large draft collections

Prerequisites

OAuth Authentication Required: This tool only works with OAuth authentication. App Password accounts will return an error.

Setup OAuth

Follow our Google Account OAuth Setup Guide to:

Create a Google Cloud project
Enable Gmail API
Create OAuth credentials
Connect your account to Reeva

App Password authentication is not supported for List Drafts.

Using the Tool

1. Create a List Drafts Tool Instance

Navigate to My Tools in Reeva
Click Create New Tool
Select Gmail - List Drafts from the base tools
Give your tool a name (e.g., "Browse Gmail Drafts")
Select your OAuth Gmail account (not App Password)
Click Create

2. List All Drafts (Simple)

Get your most recent drafts with basic metadata:

{}

This returns up to 100 drafts sorted by date (newest first).

3. Summary vs Full Format

Summary format (default) - Fast, returns metadata only:

{
  "format": "summary"
}

Full format - Slower, includes complete email body:

{
  "format": "full"
}

4. Filter by Subject

Find drafts with specific subject keywords:

{
  "subject_filter": "project update"
}

This is a case-insensitive substring match.

5. Filter by Date Range

Find drafts within a date range:

{
  "after_date": "2024/12/01",
  "before_date": "2024/12/31"
}

Flexible date formats are accepted (YYYY/MM/DD, YYYY-MM-DD, MM/DD/YYYY, etc.).

6. Sort Options

Sort by date (default), newest first:

{
  "sort_by": "date",
  "sort_order": "desc"
}

Sort by date, oldest first:

{
  "sort_by": "date",
  "sort_order": "asc"
}

Sort by subject alphabetically (A-Z):

{
  "sort_by": "subject",
  "sort_order": "asc"
}

7. Pagination

For accounts with many drafts, use pagination:

First request:

{
  "max_results": 50
}

Response includes next_page_token:

{
  "drafts": [...50 drafts...],
  "count": 50,
  "next_page_token": "CAEQAA"
}

Next page:

{
  "max_results": 50,
  "page_token": "CAEQAA"
}

Continue until next_page_token is null.

8. Combined Filters

Combine multiple filters for precise searches:

{
  "format": "summary",
  "max_results": 25,
  "subject_filter": "meeting",
  "after_date": "2024/11/01",
  "sort_by": "date",
  "sort_order": "desc"
}

Tool Parameters

Parameter	Type	Required	Default	Description
`format`	string	No	`"summary"`	Detail level: `"summary"` or `"full"`
`max_results`	integer	No	`100`	Max drafts per page (1-500)
`page_token`	string	No	-	Pagination token from previous response
`subject_filter`	string	No	-	Filter by subject keywords
`after_date`	string	No	-	Filter drafts after this date
`before_date`	string	No	-	Filter drafts before this date
`sort_by`	string	No	`"date"`	Sort field: `"date"` or `"subject"`
`sort_order`	string	No	`"desc"`	Sort order: `"asc"` or `"desc"`

Parameter Details

format:

"summary" (default): Returns metadata only (draft_id, subject, to, date, snippet) - faster
"full": Returns complete content including body_plain and body_html - slower

max_results:

Number of drafts per page (1-500)
Default: 100
Use with page_token for pagination

page_token:

Token from next_page_token in previous response
Use to fetch next page of results

subject_filter:

Case-insensitive substring match
Example: "meeting" matches "Team Meeting Notes", "Q4 Meeting Agenda"

after_date / before_date:

Flexible date formats: YYYY/MM/DD, YYYY-MM-DD, MM/DD/YYYY, etc.
Filter is inclusive

sort_by:

"date": Sort by draft creation date
"subject": Sort alphabetically by subject

sort_order:

"desc": Descending (newest first for date, Z-A for subject)
"asc": Ascending (oldest first for date, A-Z for subject)

Response Format

Summary Format Response

{
  "drafts": [
    {
      "draft_id": "r-1234567890123456789",
      "message_id": "18d5f2a3b4c5d6e7",
      "subject": "Project Update - Q4 2024",
      "to": "team@example.com",
      "from": "sender@gmail.com",
      "date": "Mon, 6 Dec 2024 10:30:00 -0800",
      "snippet": "Hi team, here's the latest project update..."
    }
  ],
  "count": 1,
  "next_page_token": null,
  "format": "summary",
  "applied_filters": {
    "subject_filter": null,
    "after_date": null,
    "before_date": null,
    "sort_by": "date",
    "sort_order": "desc"
  }
}

Full Format Response

{
  "drafts": [
    {
      "draft_id": "r-1234567890123456789",
      "message_id": "18d5f2a3b4c5d6e7",
      "subject": "Project Update - Q4 2024",
      "to": "team@example.com",
      "from": "sender@gmail.com",
      "date": "Mon, 6 Dec 2024 10:30:00 -0800",
      "snippet": "Hi team, here's the latest project update...",
      "body_plain": "Hi team,\n\nHere's the full project update...\n\nBest regards",
      "body_html": "<p>Hi team,</p><p>Here's the full project update...</p>"
    }
  ],
  "count": 1,
  "next_page_token": null,
  "format": "full",
  "applied_filters": { ... }
}

Response Fields

Per draft:

draft_id: Gmail draft ID (use with Update Draft or Send Draft)
message_id: Gmail message ID
subject: Email subject line
to: Recipients
from: Sender (your email)
date: Draft creation/modification date
snippet: Short preview of email content
cc: CC recipients (if present)
bcc: BCC recipients (if present)
body_plain: Full plain text body (full format only)
body_html: Full HTML body (full format only)

Response metadata:

count: Number of drafts returned
next_page_token: Token for next page (null if no more pages)
format: Format used ("summary" or "full")
applied_filters: Filters that were applied

OAuth vs App Password

Feature	OAuth	App Password
List drafts	✅	❌ Not supported
Reason	Gmail API supports draft listing	IMAP limitation

Why OAuth only? Gmail's IMAP protocol has limited draft support and doesn't provide the rich filtering and metadata that the Gmail API offers.

Use Cases

1. Browse All Drafts for Review

{
  "format": "summary",
  "max_results": 50,
  "sort_by": "date",
  "sort_order": "desc"
}

2. Find AI-Generated Drafts

{
  "subject_filter": "[AI Draft]",
  "format": "full"
}

3. Clean Up Old Drafts

Find drafts older than a certain date:

{
  "before_date": "2024/01/01",
  "sort_by": "date",
  "sort_order": "asc"
}

4. Get Draft Content Before Updating

{
  "format": "full",
  "subject_filter": "Q4 Planning"
}

Use the returned content to make targeted updates.

5. Paginate Through All Drafts

Step 1: { "max_results": 100 }
Step 2: { "max_results": 100, "page_token": "CAEQAA" }
Step 3: { "max_results": 100, "page_token": "CAIQAA" }
... until next_page_token is null

Error Handling

App Password Authentication

{
  "error": "List Drafts requires OAuth authentication. App Password is not supported for this operation."
}

Solution: Set up OAuth authentication

Invalid Format Parameter

{
  "error": "Format must be 'summary' or 'full'"
}

Solution: Use "summary" or "full" for format

Invalid max_results

{
  "error": "max_results must be between 1 and 500"
}

Solution: Use a value between 1 and 500

Invalid Sort Parameters

{
  "error": "sort_by must be 'date' or 'subject'"
}

Solution: Use "date" or "subject" for sort_by

No Drafts Found

{
  "drafts": [],
  "count": 0,
  "next_page_token": null,
  "message": "No drafts found"
}

This is not an error - it means no drafts match your criteria.

Tips

Start with Summary Format: Use format: "summary" for faster responses, only use "full" when you need the complete email body
Default is Most Recent: By default, drafts are sorted by date descending (newest first)
subject_filter is Case-Insensitive: "MEETING" and "meeting" will match the same drafts
Combine Filters: Use multiple filters together for precise searches
Save draft_id: The draft_id field is what you need for Update Draft and Send Draft tools
Handle Pagination: For accounts with many drafts, always check next_page_token and fetch more pages if needed
Date Format Flexibility: Various date formats are accepted - YYYY/MM/DD, YYYY-MM-DD, MM/DD/YYYY, etc.

Limitations

OAuth Only: App Password authentication is not supported
Max 500 Per Page: Gmail API limits results to 500 per request
Client-Side Filtering: Subject and date filters are applied after fetching from Gmail API
No Full-Text Search: subject_filter only searches subject lines, not email body
Date Parsing: Dates are parsed using draft headers, which may vary in format

Troubleshooting

Slow Response with Full Format

Cause: Full format requires fetching complete email content for each draft

Solution: Use format: "summary" for faster responses, only request full format when needed

Missing Drafts

Cause: Filters may be excluding drafts

Solution:

Remove filters and list all drafts
Check date range is correct
subject_filter is case-insensitive but must be substring match

Pagination Issues

Cause: Invalid page_token

Solution:

Only use page_token from the immediate previous response
Tokens may expire - start from beginning if issues occur

Gmail - Create Draft - Create new draft emails
Gmail - Update Draft - Modify existing drafts
Gmail - Send Draft - Send existing drafts
Gmail - Delete Draft - Permanently delete drafts
Gmail - Send Email - Send emails immediately
Gmail - Simple Search - Search inbox
Gmail - Read Email - Read email content
Gmail - Summarize Thread - AI summary of email threads

Support

Need help? Reach out to our support team or join our Discord community.

Overview​

Prerequisites​

Setup OAuth​

Using the Tool​

1. Create a List Drafts Tool Instance​

2. List All Drafts (Simple)​

3. Summary vs Full Format​

4. Filter by Subject​

5. Filter by Date Range​

6. Sort Options​

7. Pagination​

8. Combined Filters​

Tool Parameters​

Parameter Details​

Response Format​

Summary Format Response​

Full Format Response​

Response Fields​

OAuth vs App Password​

Use Cases​

1. Browse All Drafts for Review​

2. Find AI-Generated Drafts​

3. Clean Up Old Drafts​

4. Get Draft Content Before Updating​

5. Paginate Through All Drafts​

Error Handling​

App Password Authentication​

Invalid Format Parameter​

Invalid max_results​

Invalid Sort Parameters​

No Drafts Found​

Tips​

Limitations​

Troubleshooting​

Slow Response with Full Format​

Missing Drafts​

Pagination Issues​

Related Tools​

Support​