Add outbound calendar invites, RSVP replies, and Postmark webhook logging

- Send METHOD:REQUEST .ics invite emails via Postmark when events are
  created/updated with attendees (fire-and-forget, graceful degradation)
- Send METHOD:REPLY .ics emails when agents respond to inbound invites
- Track invite_sent, reply_sent, ical_sequence on events to prevent dupes
- Add Postmark webhook endpoint for deliverability debugging (bounces, etc.)
- Set trust proxy for correct rate limiting behind Fly's reverse proxy
- Improved [outbound] logging with Postmark message IDs and error codes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: plc

.env.example

@@ -14,3 +14,7 @@ DATABASE_URL=postgres://plc:postgres@host.docker.internal:5432/caldave
 
 # Database name
 DB_NAME=caldave
+
+# Postmark server API token for outbound calendar invite/reply emails
+# Optional — if not set, outbound emails are silently skipped
+POSTMARK_SERVER_TOKEN=

CALDAVE_SPEC.md

@@ -505,7 +505,7 @@ Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-R
 3. **Webhook logs** — Failed deliveries are queryable via `GET /calendars/:id/webhook-logs`.
 4. **Domain** — `caldave.ai` for v1. Email addresses: `cal-abc123@caldave.ai`.
 5. **Event size limits** — 64KB for description, 16KB for metadata JSON.
-6. **Outbound email** — Not in v1. Agents can accept/decline internally but organisers are not notified. Stubbed for v2.
+6. **Outbound email** — Implemented. Creating/updating events with attendees sends METHOD:REQUEST invite emails via Postmark. Responding to inbound invites sends METHOD:REPLY emails to the organiser. Requires `POSTMARK_SERVER_TOKEN` env var; gracefully skipped if not set.
 7. **Calendar sharing** — Not in v1. Could add via a `calendar_shares` table later.
 
 ---
@@ -517,5 +517,3 @@ Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-R
 - Attachments on events
 - Free/busy lookups
 - CalDAV protocol compliance
-- Outbound calendar invites (agent inviting humans)
-- Outbound email responses (notifying organisers of accept/decline)

CHANGELOG.md

@@ -7,9 +7,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 
 ### Added
+- **Outbound calendar invites** — when an event is created or updated with attendees, CalDave sends METHOD:REQUEST iCal invite emails via Postmark. Invites include `.ics` attachments that work with Google Calendar, Outlook, and Apple Calendar. From address is the calendar's email so replies route back through the inbound webhook.
+- **Outbound RSVP replies** — when an agent responds to an inbound invite via `POST /respond`, CalDave sends a METHOD:REPLY iCal email back to the organiser with the agent's acceptance, decline, or tentative status.
+- **Graceful degradation** — if `POSTMARK_SERVER_TOKEN` is not set, outbound emails are silently skipped. All API endpoints continue to work normally.
+- **Outbound email tracking** — new `invite_sent`, `reply_sent`, and `ical_sequence` columns on events prevent duplicate sends and support proper iCal update semantics.
+- **`email_sent` in respond response** — `POST /respond` now includes an `email_sent` boolean indicating whether a reply email was triggered.
 - **All-day events** — events can now be created with `all_day: true` and date-only `start`/`end` in `YYYY-MM-DD` format. End date is inclusive (e.g. `start: "2025-03-15", end: "2025-03-15"` = one-day event). Supported across the full stack: API CRUD, recurring events, inbound email detection (VALUE=DATE), iCal feeds (DTSTART;VALUE=DATE), plain text view, MCP tools, and documentation.
 - **`caldave-mcp` npm package** — standalone MCP server published as `caldave-mcp` on npm. Run with `npx caldave-mcp` with `CALDAVE_API_KEY` set.
 
+- **Postmark webhook event logging** — new endpoint ingests Postmark delivery, bounce, spam, open, and click events into a `postmark_webhooks` table for email deliverability debugging. GET the same URL to view recent events.
+
+### Fixed
+- **`trust proxy` for Fly.io** — set `app.set('trust proxy', 1)` so `express-rate-limit` correctly identifies clients behind Fly's reverse proxy. Fixes `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` validation errors on every cold start.
+- **Improved outbound email logging** — all outbound email operations now log with `[outbound]` prefix including Postmark message IDs on success and status codes on failure.
+
 ### Changed
 - **`rrule` accepted as alias for `recurrence`** — POST/PATCH event endpoints now accept either `rrule` or `recurrence` for the recurrence rule field. `rrule` is the RFC 5545 term and more intuitive for most users.
 - **Timezone in event list responses** — `GET /events` and `GET /upcoming` now include a `timezone` field in the response envelope when the calendar has a timezone set, making it easier for agents to convert UTC times.

GOTCHAS.md

@@ -34,4 +34,28 @@ This file documents confusing issues, mistakes, and lessons learned. When Claude
 
 **Prevention**: When implementing DST-aware recurrence, expand RRULEs in the calendar's local timezone, then convert each occurrence to UTC for storage.
 
+### Postmark sender signature requirement
+
+**Date**: 2026-02-14
+
+**Problem**: Outbound calendar invite emails fail to send because Postmark rejects the From address.
+
+**Cause**: Postmark requires all sender addresses to be verified via a Sender Signature or domain-level verification. Calendar email addresses (`cal-xxx@invite.caldave.ai`) are auto-generated and not individually registered as sender signatures.
+
+**Solution**: Verify the entire `invite.caldave.ai` domain in the Postmark account settings (not individual email addresses). This allows any `*@invite.caldave.ai` address to send.
+
+**Prevention**: When setting up a new Postmark account or changing the `CALDAVE_EMAIL_DOMAIN`, always verify the domain in Postmark first.
+
+### ical-generator requires organizer.name
+
+**Date**: 2026-02-14
+
+**Problem**: `ical-generator` v10 throws `'organizer.name' is empty!` when creating a VEVENT with an organizer that has no name.
+
+**Cause**: The library validates that `organizer.name` is a non-empty string. Setting just `{ email: 'foo@bar.com' }` fails.
+
+**Solution**: Always provide both `name` and `email` when setting the organizer. For REPLY .ics (where we may not know the organiser's name), use the email address as the name.
+
+**Prevention**: Always pass `{ name: ..., email: ... }` to `ical-generator`'s organizer option.
+
 <!-- Add new post-mortems above this line -->

SPEC.md

@@ -43,6 +43,8 @@ fly deploy
 | `POST /calendars/:id/events/:eid/respond` | Yes | Accept/decline invite |
 | `GET /feeds/:id.ics?token=TOKEN` | Feed token | iCal feed (subscribable) |
 | `POST /inbound/:token` | Token in URL | Inbound email webhook (per-calendar) |
+| `POST /hooks/pm-Mj7aXcGE23gCfnql` | No (obscure URL) | Postmark outbound event webhook (delivery, bounce, spam, etc.) |
+| `GET /hooks/pm-Mj7aXcGE23gCfnql` | No (obscure URL) | View recent Postmark webhook events (?limit=N&type=Bounce) |
 
 Auth = `Authorization: Bearer <api_key>` (except feeds, which use `?token=` query param)
 
@@ -56,6 +58,7 @@ src/
 ├── lib/
 │   ├── ids.js            — nanoid-based ID generation (agt_, cal_, evt_, inb_)
 │   ├── keys.js           — SHA-256 API key hashing
+│   ├── outbound.js       — Outbound email (iCal invite/reply generation, Postmark sending)
 │   └── recurrence.js     — RRULE parsing, materialization, horizon management
 ├── middleware/
 │   ├── auth.js           — Bearer token auth
@@ -66,15 +69,16 @@ src/
     ├── calendars.js      — Calendar CRUD
     ├── events.js         — Event CRUD + upcoming + respond
     ├── feeds.js          — iCal feed generation
-    └── inbound.js        — Inbound email webhook (per-calendar token URL)
+    ├── inbound.js        — Inbound email webhook (per-calendar token URL)
+    └── postmark-webhooks.js — Postmark outbound event logging (deliverability debugging)
 scripts/
 ├── init-db.sh            — Creates DB if not exists (Docker)
 └── get-port.sh           — Deterministic port from project name
 ```
 
 ## Database Schema
 
-Three tables: `agents`, `calendars`, `events`. Schema auto-created on startup.
+Five tables: `agents`, `calendars`, `events`, `postmark_webhooks`, `error_log`. Schema auto-created on startup.
 
 See `CALDAVE_SPEC.md` for full column definitions.
 
@@ -109,6 +113,7 @@ Events can be created with `all_day: true`. When set:
 | `DATABASE_URL` | — | Postgres connection string |
 | `DB_NAME` | `caldave` | Database name for init script |
 | `CALDAVE_DOMAIN` | `caldave.ai` | Domain for calendar email addresses |
+| `POSTMARK_SERVER_TOKEN` | — | Postmark API token for outbound emails (optional; if unset, outbound emails are silently skipped) |
 
 ## Auth Model
 

docker-compose.yml

@@ -35,6 +35,7 @@ services:
       - DATABASE_URL=postgres://plc:postgres@host.docker.internal:5432/${DB_NAME:-caldave}
       - PORT=${PORT:-3000}
       - INBOUND_WEBHOOK_SECRET=${INBOUND_WEBHOOK_SECRET:-}
+      - POSTMARK_SERVER_TOKEN=${POSTMARK_SERVER_TOKEN:-}
     extra_hosts:
       - "host.docker.internal:host-gateway"
     depends_on:

package.json

@@ -27,6 +27,7 @@
     "nanoid": "^5.1.6",
     "node-ical": "^0.25.1",
     "pg": "^8.11.3",
+    "postmark": "^4.0.5",
     "rrule": "^2.8.1",
     "zod": "^4.3.6"
   },

src/db.js

@@ -104,6 +104,27 @@ async function initSchema() {
     -- Per-calendar AgentMail API key for fetching attachments
     ALTER TABLE calendars ADD COLUMN IF NOT EXISTS agentmail_api_key text;
 
+    -- Outbound email tracking
+    ALTER TABLE events ADD COLUMN IF NOT EXISTS invite_sent boolean NOT NULL DEFAULT false;
+    ALTER TABLE events ADD COLUMN IF NOT EXISTS reply_sent text;
+    ALTER TABLE events ADD COLUMN IF NOT EXISTS ical_sequence integer NOT NULL DEFAULT 0;
+
+    -- Postmark webhook events for email deliverability debugging
+    CREATE TABLE IF NOT EXISTS postmark_webhooks (
+      id            serial PRIMARY KEY,
+      record_type   text NOT NULL,
+      message_id    text,
+      recipient     text,
+      tag           text,
+      error_code    text,
+      error_message text,
+      payload       jsonb,
+      created_at    timestamptz NOT NULL DEFAULT now()
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_postmark_webhooks_created
+      ON postmark_webhooks (created_at DESC);
+
     -- Error log for tracking API errors
     CREATE TABLE IF NOT EXISTS error_log (
       id            serial PRIMARY KEY,

src/index.js

@@ -30,9 +30,11 @@ const docsRouter = require('./routes/docs');
 const quickstartRouter = require('./routes/quickstart');
 const manRouter = require('./routes/man');
 const viewRouter = require('./routes/view');
+const postmarkWebhooksRouter = require('./routes/postmark-webhooks');
 const { extendAllHorizons, EXTEND_INTERVAL_MS } = require('./lib/recurrence');
 
 const app = express();
+app.set('trust proxy', 1);
 const port = process.env.PORT || 3000;
 
 // ---------------------------------------------------------------------------
@@ -169,6 +171,9 @@ app.use('/feeds', feedsRouter);
 // Inbound email webhook (no Bearer auth — token in URL authenticates)
 app.use('/inbound', inboundLimiter, inboundRouter);
 
+// Postmark outbound event webhooks (no auth — obscure URL is the secret)
+app.use('/hooks/pm-Mj7aXcGE23gCfnql', postmarkWebhooksRouter);
+
 // ---------------------------------------------------------------------------
 // Authenticated routes
 // ---------------------------------------------------------------------------