{"id":"0d6645eed9431d1bf5a0b2a4b28d399bd1d8f1f5803002e5ace6d9e8af71411a","pubkey":"b22b06b051fd5232966a9344a634d956c3dc33a7f5ecdcad9ed11ddc4120a7f2","created_at":1773149398,"kind":30817,"tags":[["d","nostr-mail-labels"],["title","Nostr mail labels"],["k","1985"],["k","5"],["client","nostrhub.io"]],"content":"# Nostr Mail Labels\n\nThis document defines the protocol for managing email metadata (folders, read state, stars, custom tags) in Nostr Mail using NIP-32 labels.\n\n## Overview\n\nEmail metadata is managed through NIP-32 label events (kind 1985). Each label is a separate event, allowing granular control and easy synchronization across clients.\n\n## Namespace\n\nAll Nostr Mail labels use the namespace: `mail`\n\n## Label Format\n\n### Adding a Label\n\nTo add a label to an email, publish a kind 1985 event:\n\n```json\n{\n  \"kind\": 1985,\n  \"pubkey\": \"<user_pubkey>\",\n  \"tags\": [\n    [\"L\", \"mail\"],\n    [\"l\", \"<label>\", \"mail\"],\n    [\"e\", \"<gift_wrap_event_id>\", \"\", \"labelled\"]\n  ],\n  \"content\": \"\"\n}\n```\n\n### Removing a Label\n\nTo remove a label, publish a NIP-09 deletion request (kind 5) targeting the label event:\n\n```json\n{\n  \"kind\": 5,\n  \"pubkey\": \"<user_pubkey>\",\n  \"tags\": [\n    [\"e\", \"<label_event_id>\"],\n    [\"k\", \"1985\"]\n  ],\n  \"content\": \"\"\n}\n```\n\n## Standard Labels\n\n### Folders\n\nEmails without a folder label are considered to be in the inbox (default state).\n\n| Label | Description |\n|-------|-------------|\n| `folder:trash` | Email is in the trash |\n| `folder:archive` | Email is archived |\n| `folder:spam` | Email is marked as spam |\n| `folder:<custom>` | Custom folder (user-defined) |\n\n### Read State\n\nEmails without a read state label are considered unread (default state).\n\n| Label | Description |\n|-------|-------------|\n| `state:read` | Email has been read |\n\n### Flags\n\nEmails without flag labels have no special flags (default state).\n\n| Label | Description |\n|-------|-------------|\n| `flag:starred` | Email is starred/favorited |\n| `flag:important` | Email is marked as important |\n\n### Custom Tags\n\nUsers can create custom tags for organization:\n\n| Label | Description |\n|-------|-------------|\n| `tag:<name>` | Custom user-defined tag |\n\n## Examples\n\n### Move Email to Trash\n\n```json\n{\n  \"kind\": 1985,\n  \"pubkey\": \"abc123...\",\n  \"created_at\": 1234567890,\n  \"tags\": [\n    [\"L\", \"mail\"],\n    [\"l\", \"folder:trash\", \"mail\"],\n    [\"e\", \"def456...\", \"\", \"labelled\"]\n  ],\n  \"content\": \"\"\n}\n```\n\n### Mark Email as Read and Starred\n\nTwo separate events:\n\n**Read event:**\n```json\n{\n  \"kind\": 1985,\n  \"tags\": [\n    [\"L\", \"mail\"],\n    [\"l\", \"state:read\", \"mail\"],\n    [\"e\", \"def456...\", \"\", \"labelled\"]\n  ],\n  \"content\": \"\"\n}\n```\n\n**Starred event:**\n```json\n{\n  \"kind\": 1985,\n  \"tags\": [\n    [\"L\", \"mail\"],\n    [\"l\", \"flag:starred\", \"mail\"],\n    [\"e\", \"def456...\", \"\", \"labelled\"]\n  ],\n  \"content\": \"\"\n}\n```\n\n### Restore Email from Trash\n\nPublish a deletion request for the `folder:trash` label event:\n\n```json\n{\n  \"kind\": 5,\n  \"tags\": [\n    [\"e\", \"<trash_label_event_id>\"],\n    [\"k\", \"1985\"]\n  ],\n  \"content\": \"\"\n}\n```\n\n## Querying Labels\n\n### Get All Labels for a User\n\n```json\n{\n  \"kinds\": [1985],\n  \"authors\": [\"<user_pubkey>\"],\n  \"#L\": [\"mail\"]\n}\n```\n\n### Get All Emails in Trash\n\n```json\n{\n  \"kinds\": [1985],\n  \"authors\": [\"<user_pubkey>\"],\n  \"#L\": [\"mail\"],\n  \"#l\": [\"folder:trash\"]\n}\n```\n\n### Get All Read Emails\n\n```json\n{\n  \"kinds\": [1985],\n  \"authors\": [\"<user_pubkey>\"],\n  \"#L\": [\"mail\"],\n  \"#l\": [\"state:read\"]\n}\n```\n\n## Default States\n\nWhen an email has no associated label events:\n\n| Property | Default State |\n|----------|---------------|\n| Folder | Inbox |\n| Read state | Unread |\n| Starred | Not starred |\n| Important | Not important |\n\n## Synchronization\n\nClients should:\n\n1. Subscribe to kind 1985 events with `#L: [\"mail\"]` for the user's pubkey\n2. Subscribe to kind 5 deletion events to track label removals\n3. Maintain a local cache of labels for performance\n4. Publish labels to the user's write relays (NIP-65 kind 10002)","sig":"3b469bcb66b1a33b292396d650b6b202d10091c9e7e12f6cf48803ec1c08688793c4111d36be6551844dba22389c9178a58d41c12f902f37426ff9b66ea597d7"}