Nostr mail labels

Nostr Mail Labels

This document defines the protocol for managing email metadata (folders, read state, stars, custom tags) in Nostr Mail using NIP-32 labels.

Overview

Email metadata is managed through NIP-32 label events (kind 1985). Each label is a separate event, allowing granular control and easy synchronization across clients.

Namespace

All Nostr Mail labels use the namespace: mail

Label Format

Adding a Label

To add a label to an email, publish a kind 1985 event:

{
  "kind": 1985,
  "pubkey": "<user_pubkey>",
  "tags": [
    ["L", "mail"],
    ["l", "<label>", "mail"],
    ["e", "<gift_wrap_event_id>", "", "labelled"]
  ],
  "content": ""
}

Removing a Label

To remove a label, publish a NIP-09 deletion request (kind 5) targeting the label event:

{
  "kind": 5,
  "pubkey": "<user_pubkey>",
  "tags": [
    ["e", "<label_event_id>"],
    ["k", "1985"]
  ],
  "content": ""
}

Standard Labels

Folders

Emails without a folder label are considered to be in the inbox (default state).

Read State

Emails without a read state label are considered unread (default state).

Flags

Emails without flag labels have no special flags (default state).

Custom Tags

Users can create custom tags for organization:

Examples

Move Email to Trash

{
  "kind": 1985,
  "pubkey": "abc123...",
  "created_at": 1234567890,
  "tags": [
    ["L", "mail"],
    ["l", "folder:trash", "mail"],
    ["e", "def456...", "", "labelled"]
  ],
  "content": ""
}

Mark Email as Read and Starred

Two separate events:

Read event:

{
  "kind": 1985,
  "tags": [
    ["L", "mail"],
    ["l", "state:read", "mail"],
    ["e", "def456...", "", "labelled"]
  ],
  "content": ""
}

Starred event:

{
  "kind": 1985,
  "tags": [
    ["L", "mail"],
    ["l", "flag:starred", "mail"],
    ["e", "def456...", "", "labelled"]
  ],
  "content": ""
}

Restore Email from Trash

Publish a deletion request for the folder:trash label event:

{
  "kind": 5,
  "tags": [
    ["e", "<trash_label_event_id>"],
    ["k", "1985"]
  ],
  "content": ""
}

Querying Labels

Get All Labels for a User

{
  "kinds": [1985],
  "authors": ["<user_pubkey>"],
  "#L": ["mail"]
}

Get All Emails in Trash

{
  "kinds": [1985],
  "authors": ["<user_pubkey>"],
  "#L": ["mail"],
  "#l": ["folder:trash"]
}

Get All Read Emails

{
  "kinds": [1985],
  "authors": ["<user_pubkey>"],
  "#L": ["mail"],
  "#l": ["state:read"]
}

Default States

When an email has no associated label events:

Synchronization

Clients should:

1. Subscribe to kind 1985 events with #L: ["mail"] for the user's pubkey
2. Subscribe to kind 5 deletion events to track label removals
3. Maintain a local cache of labels for performance
4. Publish labels to the user's write relays (NIP-65 kind 10002)