80 lines
2.7 KiB
Markdown
80 lines
2.7 KiB
Markdown
# 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
|