Skip to main content

Gmail - Delete Draft

Permanently delete draft emails from Gmail. WARNING: Deleted drafts cannot be recovered.

Overview​

The Gmail Delete Draft tool permanently removes a draft email from your Gmail account. This is useful for cleaning up unwanted drafts, removing outdated draft content, or managing your drafts folder.

Key Features:

  • Delete one draft at a time by draft_id
  • Permanent deletion (cannot be undone)
  • Returns simple confirmation
  • OAuth authentication only

Common Use Cases:

  • Clean up old or outdated drafts
  • Remove AI-generated drafts that weren't approved
  • Delete duplicate drafts
  • Clear test drafts created during development
  • Manage drafts folder organization

⚠️ WARNING: This action is permanent. Once a draft is deleted, it cannot be recovered. Always verify the draft_id before deleting.

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:

  1. Create a Google Cloud project
  2. Enable Gmail API
  3. Create OAuth credentials
  4. Connect your account to Reeva

App Password authentication is not supported for Delete Draft because Gmail's IMAP protocol doesn't reliably support draft deletion.

Using the Tool​

1. Create a Delete Draft Tool Instance​

  1. Navigate to My Tools in Reeva
  2. Click Create New Tool
  3. Select Gmail - Delete Draft from the base tools
  4. Give your tool a name (e.g., "Delete Gmail Draft")
  5. Select your OAuth Gmail account (not App Password)
  6. Click Create

2. Delete a Draft​

Delete a draft permanently:

{
  "draft_id": "r-1234567890123456789"
}

The draft is immediately and permanently deleted.

Getting the draft_id​

You can get the draft_id from:

  • Create Draft tool response
  • List Drafts tool response

Best Practice: Use List Drafts with format: "summary" to review drafts before deleting them.

Tool Parameters​

ParameterTypeRequiredDescription
draft_idstringYesGmail draft ID to delete

Parameter Details​

draft_id (required):

  • Gmail draft ID from Create Draft or List Drafts
  • Format: r-XXXXXXXXXXXXXXXXX (typically 19 digits prefixed with r-)
  • Example: "r-1234567890123456789"
  • WARNING: Deletion is permanent - verify this is the correct draft_id

Response Format​

Successful Deletion​

{
  "success": true,
  "draft_id": "r-1234567890123456789",
  "message": "Draft deleted successfully"
}

Response Fields​

  • success: Whether the draft was deleted successfully
  • draft_id: The draft ID that was deleted (for confirmation)
  • message: Confirmation message

Important Behavior​

Permanent Deletion​

When you delete a draft:

  • The draft is permanently removed from Gmail
  • The deletion cannot be undone
  • The draft cannot be recovered - not in Trash, not anywhere
  • The draft_id becomes invalid immediately

Best Practices​

  1. Verify First: Always use List Drafts to confirm you have the correct draft_id
  2. Review Content: Use List Drafts with format: "full" to see the draft content before deleting
  3. Double-Check: Verify the draft_id matches the draft you want to delete
  4. No Undo: There is no trash/recovery for drafts - deletion is immediate and permanent

OAuth vs App Password​

FeatureOAuthApp Password
Delete drafts✅❌ Not supported
ReasonGmail API supports draft deletionIMAP draft deletion is unreliable

Why OAuth only? Gmail's IMAP protocol doesn't provide reliable draft deletion. While technically possible, it's error-prone and may leave artifacts or fail silently.

Use Cases​

1. Clean Up Old Drafts​

Find and delete drafts older than a certain date:

Step 1: List old drafts
{
  "before_date": "2024/01/01",
  "format": "summary"
}

Step 2: Review the list

Step 3: Delete each unwanted draft
{
  "draft_id": "r-1234567890123456789"
}

2. Remove Rejected AI Drafts​

Workflow:
1. AI creates draft with Create Draft
2. Human reviews draft and rejects it
3. Delete Draft removes the unwanted draft

3. Delete Duplicate Drafts​

Step 1: List drafts with subject filter
{
  "subject_filter": "Duplicate Subject",
  "format": "summary"
}

Step 2: Identify duplicates by reviewing dates/snippets

Step 3: Delete duplicates
{
  "draft_id": "r-1111111111111111111"
}
{
  "draft_id": "r-2222222222222222222"
}

4. Clear Test Drafts​

After testing email composition:

{
  "draft_id": "r-test-draft-id"
}

5. Automated Draft Cleanup​

Workflow:
1. List Drafts with before_date filter (e.g., older than 90 days)
2. Review returned drafts
3. Delete drafts that are no longer needed
4. Repeat for each old draft

Error Handling​

Draft Not Found​

{
  "error": "Draft with ID 'r-1234567890123456789' not found. It may have been deleted already or sent."
}

Causes:

  • Draft was already deleted
  • Draft was sent (no longer exists as draft)
  • Invalid draft_id
  • Draft_id from a different account

Solution:

  • Verify draft exists with List Drafts first
  • Check if email is in Sent folder (it was sent, not deleted)
  • Confirm you're using the correct draft_id

Invalid Draft ID​

{
  "error": "Draft ID is required"
}

Cause: Empty or missing draft_id

Solution: Provide a valid draft_id from Create Draft or List Drafts

App Password Authentication​

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

Cause: Using App Password account instead of OAuth

Solution: Set up OAuth authentication: OAuth Setup Guide

Gmail API Error​

{
  "error": "Gmail API error deleting draft: [error details]"
}

Causes:

  • OAuth token expired (should auto-refresh)
  • Gmail API quota exceeded
  • Account permissions issue
  • Network connectivity issue

Solution:

  • Reconnect Gmail account in Reeva
  • Wait and retry if quota issue
  • Check Gmail API is enabled in Google Cloud Console
  • Verify network connection

Tips​

  1. Verify Before Deleting: Always use List Drafts to confirm you have the correct draft_id before deleting

  2. Review Content First: Use List Drafts with format: "full" to review the draft content before permanent deletion

  3. No Undo Exists: Unlike Gmail's Trash folder for emails, deleted drafts are gone forever

  4. Save draft_id: If you might need to reference the draft later, save the draft_id before deleting (though the content will be lost)

  5. Batch Deletion: To delete multiple drafts, call this tool multiple times with different draft_ids

  6. Check Response: Always check success: true in the response to confirm deletion

  7. Alternative to Delete: Consider using Update Draft if you just want to change the content rather than delete

Limitations​

  1. OAuth Only: App Password authentication is not supported

  2. No Undo: Deletion is permanent and immediate - no recovery option

  3. One at a Time: Deletes one draft per call - no bulk deletion

  4. No Soft Delete: Draft is permanently removed, not moved to Trash

  5. Cannot Delete Sent Emails: This tool only deletes drafts. For sent emails, use different Gmail API operations.

Troubleshooting​

Deleted Draft Still Appears​

Cause: Gmail sync delay

Solution:

  • Refresh Gmail (press F5 or Cmd+R)
  • Wait 2-3 seconds for sync
  • Verify success: true in response

Wrong Draft Deleted​

Cause: Used incorrect draft_id

Solution:

  • No recovery is possible - draft is permanently gone
  • Always verify draft_id with List Drafts before deleting
  • Consider creating a new draft with the intended content

Can't Delete Draft​

Cause: Draft may have been sent or already deleted

Solution:

  • Use List Drafts to verify the draft still exists
  • Check Sent folder - draft may have been sent
  • Verify you're using the correct Gmail account

Permission Denied​

Cause: OAuth token lacks necessary permissions

Solution:

  1. Reconnect Gmail account in Reeva
  2. Ensure Gmail API is enabled in Google Cloud Console
  3. Grant all requested permissions during OAuth flow
  4. Verify https://www.googleapis.com/auth/gmail.modify scope is included

Workflow Examples​

Safe Deletion Workflow​

Step 1: List Drafts
Request: { "format": "summary" }
Response: { "drafts": [{ "draft_id": "r-123...", "subject": "Old Draft", ... }] }

Step 2: Review the draft list and identify draft to delete

Step 3: (Optional) Get full content to verify
Request: { "format": "full", "subject_filter": "Old Draft" }
Response: Full draft details including body

Step 4: Delete the draft
Request: { "draft_id": "r-1234567890123456789" }
Response: { "success": true, "draft_id": "r-123...", "message": "Draft deleted successfully" }

Step 5: Verify deletion (optional)
Request: { "format": "summary" } to List Drafts
Confirm the draft no longer appears in the list

Cleanup Workflow​

Step 1: Find old drafts
Request: { "before_date": "2024/01/01", "format": "summary" }

Step 2: Review which ones to delete

Step 3: Delete each unwanted draft
Request: { "draft_id": "r-111..." }
Request: { "draft_id": "r-222..." }
Request: { "draft_id": "r-333..." }

Support​

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