mirror of
https://github.com/suitenumerique/messages.git
synced 2026-08-30 11:49:46 +02:00
Sylvain ZimmerandGitHub
e5ce447905
This also makes sure we can reimport X-Keywords later. For now it's admin-side only, we'll add a user-facing UI. First part of #211.
153 lines
5.0 KiB
Markdown
153 lines
5.0 KiB
Markdown
# MBOX Import/Export Format
|
|
|
|
This document describes how Messages handles MBOX files for importing and exporting emails, including how labels, flags, and metadata are preserved.
|
|
|
|
## Overview
|
|
|
|
MBOX is a standard format for storing email messages in a single file. Messages uses the mboxrd variant, which is compatible with most email clients and tools including:
|
|
|
|
- Google Takeout
|
|
- Thunderbird (via ImportExportTools NG)
|
|
- Dovecot
|
|
- OfflineIMAP
|
|
- Apple Mail
|
|
- mu4e / notmuch
|
|
|
|
## Export Format
|
|
|
|
When exporting a mailbox, Messages creates a gzip-compressed MBOX file (`.mbox.gz`) containing all messages with their metadata preserved in standard headers.
|
|
|
|
### Message Flags
|
|
|
|
Message flags are exported using the standard mbox `Status` and `X-Status` headers:
|
|
|
|
| Header | Flag | Meaning |
|
|
|--------|------|---------|
|
|
| `Status: R` | R | Read (seen) |
|
|
| `Status: O` | O | Old (not recent) - always set for exports |
|
|
| `X-Status: A` | A | Answered (sent messages) |
|
|
| `X-Status: F` | F | Flagged (starred) |
|
|
| `X-Status: T` | T | Draft |
|
|
|
|
**Examples:**
|
|
```text
|
|
Status: RO # Read message
|
|
Status: O # Unread message
|
|
X-Status: F # Starred message
|
|
X-Status: AF # Sent and starred message
|
|
X-Status: T # Draft message
|
|
```
|
|
|
|
### Labels
|
|
|
|
Labels are exported using the `X-Keywords` header, which is recognized by Dovecot, OfflineIMAP, mu4e, and other Unix mail tools.
|
|
|
|
**Format:** Comma-separated list with quoted strings for labels containing spaces or commas.
|
|
|
|
```text
|
|
X-Keywords: work, important, "project alpha"
|
|
```
|
|
|
|
### Complete Example
|
|
|
|
A read, starred message with labels would have these headers injected:
|
|
|
|
```text
|
|
Status: RO
|
|
X-Status: F
|
|
X-Keywords: work, important
|
|
```
|
|
|
|
## Import Format
|
|
|
|
When importing MBOX files, Messages recognizes and processes the following headers:
|
|
|
|
### Labels Headers
|
|
|
|
| Header | Source | Format |
|
|
|--------|--------|--------|
|
|
| `X-Gmail-Labels` | Google Takeout | Comma-separated, quoted strings |
|
|
| `X-Keywords` | Dovecot/OfflineIMAP/mu4e | Comma or space-separated |
|
|
|
|
Both headers are parsed and combined. The importer handles:
|
|
- Comma-separated values: `label1, label2, label3`
|
|
- Space-separated values: `label1 label2 label3` (Dovecot format)
|
|
- Quoted strings: `"label with spaces", simple-label`
|
|
|
|
### Special Label Handling
|
|
|
|
Certain labels are mapped to message flags instead of being stored as labels:
|
|
|
|
| Label Names | Maps To |
|
|
|-------------|---------|
|
|
| `Drafts`, `[Gmail]/Drafts`, `DRAFT` | `is_draft` flag |
|
|
| `Sent`, `[Gmail]/Sent Mail`, `OUTBOX` | `is_sender` flag |
|
|
| `Starred`, `[Gmail]/Starred` | `is_starred` flag |
|
|
| `Trash`, `[Gmail]/Corbeille` | `is_trashed` flag |
|
|
| `Spam`, `QUARANTAINE` | `is_spam` flag |
|
|
| `Archived` | `is_archived` flag |
|
|
|
|
Labels like `INBOX`, `Promotions`, `Social`, `[Gmail]/Important`, and `[Gmail]/All Mail` are ignored.
|
|
|
|
### IMAP Flags
|
|
|
|
When importing via IMAP, standard IMAP flags are also recognized:
|
|
- `\Seen` - marks message as read
|
|
- `\Draft` - marks message as draft
|
|
- `\Flagged` - marks message as starred
|
|
|
|
## Roundtrip Compatibility
|
|
|
|
Messages exported from this system can be re-imported with full fidelity:
|
|
|
|
1. **Labels** are preserved via `X-Keywords` header
|
|
2. **Read/unread status** is preserved via `Status: R` header
|
|
3. **Starred status** is preserved via `X-Status: F` header
|
|
4. **Draft status** is preserved via `X-Status: T` header
|
|
5. **Sent status** is preserved via `X-Status: A` header
|
|
|
|
## Compatibility Notes
|
|
|
|
### Google Takeout
|
|
|
|
Google Takeout exports use the `X-Gmail-Labels` header. When importing Google Takeout files:
|
|
- All Gmail labels are recognized and imported
|
|
- System labels like `[Gmail]/Drafts` are mapped to flags
|
|
- Custom labels are preserved as-is
|
|
|
|
### Thunderbird
|
|
|
|
Thunderbird's native tags use IMAP keywords (`$Label1`, `$Label2`, etc.) which are not directly compatible. However:
|
|
- Thunderbird can import our MBOX files
|
|
- Use ImportExportTools NG for best results
|
|
- Labels will appear in the `X-Keywords` header but may not display as Thunderbird tags
|
|
|
|
### Dovecot
|
|
|
|
Dovecot uses `X-Keywords` with space-separated values. Our importer handles both formats:
|
|
- Space-separated: `X-Keywords: work important urgent`
|
|
- Comma-separated: `X-Keywords: work, important, urgent`
|
|
|
|
### Apple Mail
|
|
|
|
Apple Mail's export format (`.mbox` packages) can be imported. However, Apple Mail does not preserve labels in its exports, so label information may be lost when migrating from Apple Mail.
|
|
|
|
## Technical Details
|
|
|
|
### MBOX Variant
|
|
|
|
We use the mboxrd format where:
|
|
- Messages are separated by "From " lines at the start of a line
|
|
- "From " at the beginning of body lines is escaped as ">From "
|
|
- Each message ends with a blank line
|
|
|
|
### Header Injection
|
|
|
|
When exporting, metadata headers (`Status`, `X-Status`, `X-Keywords`) are injected at the end of the existing email headers, just before the blank line that separates headers from the body. This preserves the original email structure while adding metadata.
|
|
|
|
### Character Encoding
|
|
|
|
- Labels are UTF-8 encoded
|
|
- Labels containing commas, spaces, or quotes are enclosed in double quotes
|
|
- Labels containing double-quote characters are not currently supported for round-trip import
|