# ADR-006: Email Integration

## Status
Accepted

## Context
The platform needs to send email notifications for: file changes (to watchers), new comments, conflict alerts, and digest summaries. It must also receive email replies and convert them to comments. Requirement: use Postmark email gateway with plain-text only.

## Decision
**Postmark HTTP API for outgoing email, Postmark inbound webhook for incoming email.**

### Implementation

1. **Outgoing Email**:
   - Go adapter using `github.com/keighl/postmark`
   - Plain-text templates (no HTML)
   - Message-ID generated per email for threading
   - Templates: notification, digest, conflict-alert, welcome

2. **Incoming Email**:
   - Postmark inbound webhook POSTs to `/webhooks/email`
   - Webhook payload parsed for: from, subject, body, in-reply-to
   - Reply matched to comment thread via In-Reply-To header
   - Body converted to plain text comment
   - Authentication: webhook signature verification

3. **Email Format**:
   ```
   From: MD Hub Secure <notifications@example.com>
   To: user@example.com
   Subject: [docs/getting-started.md] Comment from Alice
   Message-ID: <comment-123@example.com>
   In-Reply-To: <comment-122@example.com>
   
   Alice commented on "Getting Started":
   
   > This section needs clarification...
   
   Reply to this email to add a comment.
   
   View online: https://example.com/docs/getting-started#comment-123
   ```

## Consequences

### Positive
- Postmark has excellent deliverability reputation
- Plain-text emails are accessible and lightweight
- Email threading works in all clients
- No HTML parsing/rendering security risks
- Webhook integration is simple and reliable

### Negative
- Postmark is a paid service (though inexpensive)
- Requires DNS setup (SPF, DKIM) for deliverability
- Plain-text limits formatting options (intentional trade-off)
- Rate limits on Postmark API (mitigated by queue + retry)

## Alternatives Considered

### SMTP Direct Delivery
- **Pros**: No third-party dependency, full control
- **Cons**: Complex deliverability management, IP reputation, spam folder issues
- **Rejected**: Operational burden too high for small team

### SendGrid / Mailgun
- **Pros**: Similar features to Postmark
- **Cons**: More expensive at scale, complex APIs
- **Rejected**: Postmark has better reputation for transactional email

### No Email (In-App Only)
- **Pros**: Zero email complexity
- **Cons**: Users must check app for notifications; poor for async collaboration
- **Rejected**: Email is core to collaboration workflow

## References
- Postmark API docs: https://postmarkapp.com/developer
- keighl/postmark Go library: https://github.com/keighl/postmark
- Email threading RFC: https://www.ietf.org/rfc/rfc2822.txt