---
title: "Paperless-NGX Mail Rule — Attachment-Only Processing and Mark-as-Read Gotcha"
aliases: [paperless-mail-rule, paperless-attachment-only, paperless-mark-as-read, paperless-duplicate-detection]
tags: [paperless-ngx, email, mail-fetcher, homelab, selfhosted, imap]
sources:
  - "daily/2026-05-01.md"
created: 2026-05-01
updated: 2026-05-01
---

# Paperless-NGX Mail Rule — Attachment-Only Processing and Mark-as-Read Gotcha

Paperless-NGX mail rules have two non-obvious behaviors: (1) emails already marked as read by a previous fetcher run are permanently skipped even when the attachment filter is later expanded, and (2) the default attachment processing mode imports the email body alongside attachments, causing duplicate detection failures when a later fetch tries to import the same attachment standalone.

## Key Points

- **Mark-as-read is permanent for fetcher purposes** — once a mail rule marks an email as read (Action: 1), expanding the attachment filter later won't re-process those emails; must mark them as unread in the mail client
- **Default attachment mode processes body + attachments** — email body is merged with attachment content into a single document; if the same attachment arrives without body context, it's rejected as a duplicate
- **Attachment-only mode (`0`) is safer** — imports only the actual attachments, no email body noise; prevents duplicate detection issues
- **Junk documents from body processing** must be deleted manually before clean re-import of the same attachment as a standalone document
- **Celery-beat runs every 10 minutes by default** — changes to mail rules take effect on the next scheduled run

## Details

### The Mark-as-Read Trap

When a mail rule runs with `*.pdf` as the attachment filter and Action = "Mark as read":

1. Fetcher runs → finds emails with PDF attachments → imports PDFs → marks emails as read
2. Developer updates filter to `*.pdf, *.doc, *.docx`
3. Fetcher runs again → emails are already read → **fetcher skips them entirely**
4. Word attachments are never imported

**Fix:** Mark the relevant emails as unread in the mail client (Gmail, Outlook) before the next celery-beat run.

```bash
# Force an immediate re-run after marking emails as unread
docker exec -u paperless paperless-ngx python manage.py mail_fetcher
```

### Default Mode — Body + Attachment Merging

The default `Attachment type` in a Paperless mail rule includes the email body with each attachment. The imported document contains the email subject, body text, and the attachment content all merged.

Problem scenario:

1. First fetch: `Invoice Q1.pdf` arrives in email. Paperless imports it as "Re: Invoice Q1" containing body + PDF content.
2. Second fetch attempt (after filter change): same `Invoice Q1.pdf` encounters the email again — fetcher tries to import just the PDF.
3. Paperless detects the PDF content already exists in document #83 → rejects as duplicate.

The "document" (#83) is actually the email body + PDF merged — a junk document that prevents clean import.

### Attachment-Only Mode Fix

In the mail rule configuration:

| Setting | Value | Effect |
|---------|-------|--------|
| Attachment type (default) | Process documents + attachments | Imports email body merged with each attachment |
| Attachment type = `0` | Attachments only | Imports attachment files only; no email body |

Set `Attachment type` to `0` (or the "Attachments only" option in the UI) to prevent body merging.

### Cleaning Up Junk Documents

After switching to attachment-only mode, junk documents (email body imports) must be deleted before the attachment can re-import cleanly:

1. In Paperless UI → Documents → find documents with email notification subject lines (e.g., "Re: Support Case Update", "Invoice Notification")
2. Delete them
3. Mark the source emails as unread in the mail client
4. Wait for next celery-beat run (or trigger manually)

The clean re-import will then succeed with just the attachment file, properly titled.

### Mail Rule Configuration Reference

```
Action: Mark as read (1)          # Mark emails as read after processing
Attachment type: 0                # Attachments only — no email body
Filter attachment filename: *.pdf, *.doc, *.docx  # Comma-separated globs
```

## Related Concepts

- [[wiki/concepts/paperless-ngx-docker-exec-permission-bug]] — related Paperless-NGX gotcha: docker exec running as root breaks mail fetcher testing
- [[wiki/concepts/celery-redis-queue-flush-on-deterministic-error]] — Celery queue management when deterministic errors cause retry loops
- [[wiki/concepts/docker-compose-restart-no-code-reload]] — Docker testing patterns

## Sources

- [[daily/2026-05-01.md]] — Paperless-NGX mail rule: Word files not imported because previous fetch already marked emails as read; attachment type changed to `0` (attachments only) to prevent body+attachment merging and duplicate detection; documents #83–90 identified as junk from body processing, deleted for clean re-import
