main

Extract Workflow

Extract attachments from emails using mu extract.

Workflow Steps

1. Identify Target Emails

Determine which emails contain the desired attachments:

  • Search for attachments: Use attach: in mu find
  • Specific file types: attach:*.pdf, attach:*.jpg
  • File name patterns: attach:report, attach:invoice
  • From specific senders: Combine with from: query

2. List Attachments

Show available attachments before extracting:

# View email with attachment info
mu view /path/to/email

# Extract attachment list using JSON
mu find <query> --format=json | jq -r '.attachments[]?.name'

# Count attachments
mu find attach:* | wc -l

3. Extract Attachments

Use mu extract to save attachments:

# Extract all attachments from an email
mu extract /path/to/email

# Extract to specific directory
mu extract --target-dir=/path/to/save /path/to/email

# Extract specific attachment by index
mu extract --parts=2 /path/to/email

# Save attachments and show filenames
mu extract --save-all /path/to/email

mu extract Options:

  • --target-dir=DIR - Save to specific directory (default: current)
  • --parts=N - Extract specific MIME part number
  • --save-all - Save all attachments
  • --overwrite - Overwrite existing files
  • --play - Play/view attachment (opens with default app)

4. Verify Extraction

After extraction:

  • List extracted files
  • Verify file sizes and types
  • Check for corruption
  • Confirm all expected files extracted

5. Organize Files

Optionally organize extracted files:

  • Group by sender or subject
  • Rename for clarity
  • Move to appropriate directories
  • Create index or catalog

Best Practices

File Organization

  • Extract to temporary directory first
  • Use meaningful directory names (sender, date, topic)
  • Avoid overwriting without confirmation
  • Keep track of source emails

Safety

  • Verify file types before opening
  • Be cautious with executable attachments
  • Scan large archives before extracting
  • Respect personal vs work file separation

Batch Operations

For multiple emails:

# Extract from all matching emails
mu find attach:*.pdf --format=links | while read email; do
  mu extract --target-dir=./pdfs "$email"
done

Naming Conflicts

Handle duplicate filenames:

  • Use –target-dir with unique paths
  • Rename files after extraction
  • Add timestamps or sender info to filenames

Common Use Cases

Extract PDFs from Work Emails

# Find and extract all PDFs from work account
mkdir -p ~/extracted/work-pdfs
mu find maildir:/redhat/* attach:*.pdf --format=links | while read email; do
  mu extract --target-dir=~/extracted/work-pdfs "$email"
done

Extract Attachments from Specific Thread

# Find thread by subject and extract all attachments
mkdir -p ~/extracted/project-files
mu find subject:"Project Proposal" --format=links | while read email; do
  mu extract --target-dir=~/extracted/project-files "$email"
done

Extract Specific File Type from Sender

# Extract all images from specific sender
mkdir -p ~/extracted/images
mu find from:alice@example.com attach:*.jpg --format=links | while read email; do
  mu extract --target-dir=~/extracted/images "$email"
done

Extract Attachments from Date Range

# Extract all attachments from last month
mkdir -p ~/extracted/last-month
mu find date:1m..30d attach:* --format=links | while read email; do
  mu extract --target-dir=~/extracted/last-month "$email"
done

Extract and Catalog

# Extract attachments and create catalog
output_dir=~/extracted/catalog
mkdir -p "$output_dir"
mu find attach:* --format=json | while read -r email_json; do
  path=$(echo "$email_json" | jq -r '.path')
  subject=$(echo "$email_json" | jq -r '.subject')
  from=$(echo "$email_json" | jq -r '.from')

  # Create subdirectory with email info
  safe_name=$(echo "$subject" | tr '/' '-' | cut -c1-50)
  target="$output_dir/$safe_name"
  mkdir -p "$target"

  # Extract attachments
  mu extract --target-dir="$target" "$path"

  # Create metadata file
  echo "Subject: $subject" > "$target/metadata.txt"
  echo "From: $from" >> "$target/metadata.txt"
done

MIME Part Numbers

Emails are structured as MIME parts:

  • Part 1: Usually the email body (text/plain)
  • Part 2: Alternative body (text/html) or first attachment
  • Part 3+: Additional attachments

To extract specific part:

mu extract --parts=3 /path/to/email  # Extract 3rd MIME part

View part structure:

mu view /path/to/email  # Shows part numbers and types

Alternative: Manual Extraction

If mu extract is unavailable, use mblaze:

# Using mblaze (if available)
mshow -A /path/to/email  # List attachments
mshow -O /path/to/email  # Extract all attachments

Or parse MIME manually (advanced):

# Find attachment boundaries in email
grep -n "Content-Type: application" /path/to/email
# Extract base64 encoded attachment
sed -n '/^Content-Transfer-Encoding: base64/,/^--/p' /path/to/email | \
  grep -v "^Content" | grep -v "^--" | base64 -d > attachment.bin

Error Handling

Common issues:

No attachments found:

  • Verify email has attachments: mu view /path/to/email
  • Check inline vs attached (inline images may not extract)
  • Some emails have attachments as links, not files

Permission denied:

  • Check write permissions on target directory
  • Ensure target directory exists
  • Use absolute paths

File already exists:

  • Use different –target-dir
  • Add –overwrite flag
  • Rename existing files first

Corrupted extraction:

  • Verify original email integrity
  • Check disk space
  • Try extracting specific parts individually

Integration

Typical workflow:

  1. Search workflow - Find emails with attachments
  2. User confirms which attachments to extract
  3. Extract workflow - Save attachments
  4. Verify and organize files
  5. Optionally Analyze workflow - Catalog attachments

Tool Script

For convenience, create an extraction helper:

#!/usr/bin/env nix-shell
#! nix-shell -i bash -p mu jq

# extract-email-attachments.sh
# Usage: ./extract-email-attachments.sh "query" /output/dir

query="$1"
output_dir="$2"

if [ -z "$query" ] || [ -z "$output_dir" ]; then
  echo "Usage: $0 <mu-query> <output-directory>"
  exit 1
fi

mkdir -p "$output_dir"

echo "Searching for emails matching: $query"
count=$(mu find "$query" attach:* --format=links | wc -l)
echo "Found $count emails with attachments"

mu find "$query" attach:* --format=links | while read -r email_path; do
  echo "Extracting from: $email_path"
  mu extract --target-dir="$output_dir" "$email_path"
done

echo "Extraction complete. Files saved to: $output_dir"
ls -lh "$output_dir"

Save this to /home/vincent/.config/claude/skills/Email/tools/ExtractAttachments.sh.