# Nostr Mail Bridges

Bridges act as gateways between Nostr and legacy email infrastructure, enabling Nostr users to send/receive emails to/from recipients who are not on Nostr.

Emails destined for non-Nostr recipients are sent with additional routing tags:

{
  "kind": 1301,
  "pubkey": "<sender_pubkey>",
  "tags": [
    ["email-id", "<unique_id>"],
    ["mail-from", "<sender_email>"],
    ["rcpt-to", "<recipient_email>"]
  ],
  "content": "<RFC 2822 email>"
}

1. Sender creates kind 1301 event with email-id, mail-from and rcpt-to tags
2. Sender gift wraps the event (NIP-59)
3. Sender sends to bridge's DMs relays
4. Bridge receives and unwraps the gift wrap
5. Bridge extracts email-id and SMTP routing information from tags
6. Bridge delivers email via SMTP
7. Bridge sends DSN (Delivery Status Notification) back to sender

{
  "kind": 1301,
  "pubkey": "alice_pubkey",
  "tags": [
    ["email-id", "550e8400-e29b-41d4-a716-446655440000"],
    ["mail-from", "npub1alice...@bridge.com"],
    ["rcpt-to", "bob@example.com"]
  ],
  "content": "From: npub1alice...@bridge.com\nTo: bob@example.com\nSubject: Hello\nDate: Sat, 28 Dec 2024 12:00:00 +0000\n\nHey Bob, how are you?"
}

Bridges send delivery status notifications to inform senders about the outcome of email delivery attempts.

The DSN event allows senders to track whether their emails were successfully delivered and, if not, understand why delivery failed.

To protect user privacy, DSNs implement forward secrecy at the bridge level:

1. No p tag: Recipient metadata is not exposed on public relays
2. Ephemeral encryption: Content is encrypted with a temporary key that the bridge immediately destroys
3. Permanent signature: Event is signed with bridge's permanent key for authenticity

This means:

• Public relays cannot see who the original sender was (no p tag)
• Bridge cannot decrypt its own archived DSN events (temporary key destroyed)
• DSN authenticity is still verifiable via bridge's permanent signature

{
  "kind": 7679,
  "pubkey": "<bridge_permanent_pubkey>",
  "tags": [
    ["r", "<email_id>"],
    ["ephemeral-pubkey", "<temp_pubkey>"]
  ],
  "content": "<nip44_encrypted_content>"
}

The content field contains JSON data encrypted with NIP-44 using a temporary ephemeral key.

{
  "status": "delivered",
  "recipient": "bob@example.com",
  "smtp_code": 250,
  "smtp_response": "2.1.5 OK",
  "attempted_at": 1735401600,
  "delivered_at": 1735401605,
  "details": "Email successfully delivered to recipient's SMTP server"
}

{
  "kind": 7679,
  "pubkey": "bridge_permanent_pubkey",
  "tags": [
    ["r", "550e8400-e29b-41d4-a716-446655440000"],
    ["ephemeral-pubkey", "a7b3c9d2..."]
  ],
  "content": "<nip44_encrypted: {\"status\":\"delivered\",\"recipient\":\"bob@example.com\",\"smtp_code\":250,\"smtp_response\":\"2.1.5 OK\",\"attempted_at\":1735401600,\"delivered_at\":1735401605,\"details\":\"Email successfully delivered\"}>"
}

{
  "kind": 7679,
  "pubkey": "bridge_permanent_pubkey",
  "tags": [
    ["r", "550e8400-e29b-41d4-a716-446655440000"],
    ["ephemeral-pubkey", "e8d4f1a6..."]
  ],
  "content": "<nip44_encrypted: {\"status\":\"failed\",\"recipient\":\"bob@example.com\",\"smtp_code\":550,\"smtp_response\":\"5.1.1 The email account that you tried to reach does not exist\",\"attempted_at\":1735401600,\"failed_at\":1735401600,\"details\":\"Recipient address rejected\"}>"
}

1. Generate ephemeral keypair: temp_privkey + temp_pubkey
2. Encrypt content with NIP-44 using (temp_privkey, sender_pubkey)
3. Create kind 7679 event with:
   • pubkey = bridge_permanent_pubkey
   • Sign with bridge_permanent_privkey
   • Tag ["r", email_id] where email_id is from the original kind 1301's email-id tag
   • Tag ["ephemeral-pubkey", temp_pubkey]
   • Encrypted content from step 2
4. Immediately destroy temp_privkey (delete from memory, never write to disk)
5. Publish event to relays

1. Listen for events matching filter:

   {
     "authors": ["<bridge_pubkey>"],
     "kinds": [7679],
     "#r": ["<email_id>"]
   }

   where <email_id> is the value from the kind 1301's email-id tag

2. Extract temp_pubkey from ephemeral-pubkey tag
3. Decrypt content with NIP-44 using (sender_privkey, temp_pubkey)
4. Parse decrypted JSON content

• 4xx errors: Retry with exponential backoff (typically 1m, 5m, 15m, 1h, 4h, 16h)
• 5xx errors: Do not retry (permanent failure, send DSN with status: "failed")

1. Success: Email delivered → DSN with status: "delivered"
2. Permanent failure: 5xx error after all retries exhausted → DSN with status: "failed"
3. Temporary delay: 4xx error or queued → DSN with status: "delayed" or status: "queued"

For long delays (e.g., greylisting), bridge MAY send intermediate DSNs with status delayed to keep sender informed before final delivery or failure.