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

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
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

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

2.7 KiB Raw Blame History