Address user feedback: GET /man, email_sent, SMTP test, webhook on create

Feedback-driven improvements:
- Convert POST /man to GET /man (cacheable, browser-friendly)
- Add email_sent to event create/update responses (synchronous invites)
- Add POST /agents/smtp/test endpoint to verify SMTP config
- Add secure field to SMTP config for explicit SSL/TLS control
- Accept webhook_url/secret/offsets on POST /calendars
- Quote all curl URLs in double quotes for shell safety
- Include name/description in /man guide agent creation curl
- Improve welcome_event docs visibility

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

Author: plc

CALDAVE_SPEC.md

@@ -143,6 +143,44 @@ Update the authenticated agent's metadata. Does not change the API key.
 }
 ```
 
+#### `PUT /agents/smtp`
+Configure SMTP for outbound emails. When set, all invite and RSVP emails are sent via your SMTP server.
+
+**Request:**
+```json
+{
+  "host": "smtp.agentmail.to",
+  "port": 465,
+  "username": "inbox@agentmail.to",
+  "password": "YOUR_SMTP_PASSWORD",
+  "from": "inbox@agentmail.to",
+  "secure": true
+}
+```
+
+All fields except `secure` are required. `secure` defaults to `true` for port 465, `false` otherwise. Use `true` for implicit TLS, `false` for STARTTLS.
+
+**Response:** Returns the config without the password.
+
+#### `GET /agents/smtp`
+View SMTP configuration (password excluded). Returns `null` if not configured.
+
+#### `DELETE /agents/smtp`
+Remove SMTP configuration. Outbound emails revert to CalDave's built-in delivery.
+
+#### `POST /agents/smtp/test`
+Send a test email to verify SMTP configuration works. Sends to the configured `from` address.
+
+**Response:**
+```json
+{
+  "success": true,
+  "message_id": "<abc123@smtp.agentmail.to>",
+  "from": "inbox@agentmail.to",
+  "message": "Test email sent successfully to inbox@agentmail.to."
+}
+```
+
 ---
 
 ### API Changelog
@@ -210,7 +248,7 @@ The `recommendations` array is only present when authenticated and when there ar
 
 ### API Manual
 
-#### `POST /man`
+#### `GET /man`
 Machine-readable API manual. Returns a JSON document describing all CalDave endpoints with curl examples, parameter definitions, and example responses.
 
 Auth is optional. If a valid Bearer token is provided, the response includes the agent's real calendar IDs and event counts, with personalized curl examples and a recommended next step.
@@ -246,10 +284,15 @@ Create a new calendar for the authenticated agent.
 {
   "name": "Work Schedule",
   "timezone": "America/Denver",
-  "agentmail_api_key": "am_xxx..."
+  "webhook_url": "https://example.com/webhook",
+  "webhook_secret": "my_secret",
+  "webhook_offsets": [300, 900],
+  "welcome_event": false
 }
 ```
 
+Optional fields: `timezone` (default UTC), `webhook_url`, `webhook_secret`, `webhook_offsets`, `agentmail_api_key`, `welcome_event` (default true — set to false to skip the auto-created welcome event).
+
 **Response:**
 ```json
 {
@@ -331,7 +374,7 @@ Plain text table of upcoming events. Useful for quick inspection via curl.
 
 **Example:**
 ```
-curl -s http://127.0.0.1:3720/calendars/cal_xxx/view \
+curl -s "http://127.0.0.1:3720/calendars/cal_xxx/view" \
   -H "Authorization: Bearer sk_live_xxx"
 
 Work (cal_xxx)  tz: America/Denver

CHANGELOG.md

@@ -7,14 +7,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 
 ### Added
+- **SMTP test endpoint** — `POST /agents/smtp/test` sends a test email to verify your SMTP configuration works. Sends to the configured `from` address and reports success/failure with the SMTP error message if any.
+- **SMTP `secure` field** — `PUT /agents/smtp` now accepts an optional `secure` boolean to explicitly control TLS mode. Use `true` for implicit TLS (port 465) or `false` for STARTTLS (port 587). Auto-detected from port when omitted.
+- **Webhook config at calendar creation** — `POST /calendars` now accepts `webhook_url`, `webhook_secret`, and `webhook_offsets` at creation time, saving a separate `PATCH` call.
+- **`email_sent` in event responses** — `POST` and `PATCH` event endpoints now return `email_sent: true/false` when the event has attendees, confirming whether the invite was dispatched. Invites are now sent synchronously before the response is returned.
 - **SMTP integration for outbound emails** — configure your own SMTP server via `PUT /agents/smtp` so calendar invites and RSVP replies are sent from your email address instead of CalDave's built-in delivery. New `GET /agents/smtp` (view config, password excluded) and `DELETE /agents/smtp` (revert to built-in). `GET /agents/me` now includes `smtp_configured` boolean. Supports any SMTP provider (AgentMail, SendGrid, Gmail, etc.).
 - **Webhook test endpoint** — `POST /calendars/:id/webhook/test` sends a test payload to the calendar's configured webhook URL and returns the HTTP status code. Supports HMAC-SHA256 signing via `X-CalDave-Signature` when `webhook_secret` is set.
 - **Welcome event opt-out** — `POST /calendars` now accepts `welcome_event: false` to skip the auto-created welcome event. Default remains true.
-- **Rate limit documentation** — rate limits documented in `/docs` and included in `POST /man` responses. All responses include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers (RFC draft-7).
-- **Agent name/description prominence** — `POST /agents` docs and quickstart now recommend including `name` and `description` at creation time. `POST /man` recommends naming your agent as the first step for unnamed agents. New `recommended` badge on params.
+- **Rate limit documentation** — rate limits documented in `/docs` and included in `GET /man` responses. All responses include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers (RFC draft-7).
+- **Agent name/description prominence** — `POST /agents` docs and quickstart now recommend including `name` and `description` at creation time. `GET /man` recommends naming your agent as the first step for unnamed agents. New `recommended` badge on params.
 - **Personalized recommendations in changelog** — `GET /changelog` with auth now includes a `recommendations` array with actionable suggestions based on agent state (e.g. name your agent, create your first calendar, add a description).
 - **API changelog endpoint** — `GET /changelog` returns a structured list of API changes with dates and docs links. With optional Bearer auth, highlights changes introduced since the agent was created. Designed for agents to poll ~weekly.
-- **Agent metadata** — `POST /agents` now accepts optional `name` and `description` fields to identify agents. New `GET /agents/me` returns the agent's profile. New `PATCH /agents` updates metadata without changing the API key. Agent name and description are surfaced in `POST /man` context.
+- **Agent metadata** — `POST /agents` now accepts optional `name` and `description` fields to identify agents. New `GET /agents/me` returns the agent's profile. New `PATCH /agents` updates metadata without changing the API key. Agent name and description are surfaced in `GET /man` context.
 - **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.
 - **Agent name in outbound emails** — when an agent has a name set (via `PATCH /agents`), outbound invite and RSVP reply emails use `"Agent Name" <calendar-email>` as the From address, so recipients see a friendly display name instead of just the calendar email.
 - **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.
@@ -28,12 +32,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **Welcome event on new calendars** — new calendars automatically get a "Send Peter feedback" event at 9am the next day (in the calendar's timezone), with an invite sent to peter.clark@gmail.com.
 - **Terms of Service and Privacy Policy** — new `/terms` and `/privacy` pages with footer links on landing, docs, and quickstart pages.
 
+### Changed
+- **`GET /man` (was `POST /man`)** — the machine-readable API manual is now a GET endpoint. GET is cacheable, browser-friendly, and conventional for read-only endpoints. The `?guide` query param still works. All docs, tests, and examples updated.
+
 ### Fixed
-- **Docs placeholder standardization** — all curl examples in `/docs` now use consistent `UPPER_SNAKE_CASE` placeholders (`YOUR_API_KEY`, `CAL_ID`, `EVT_ID`, `FEED_TOKEN`) with gold highlighting. Added placeholder legend, error endpoints (`GET /errors`, `GET /errors/:id`), and fixed agent description max length (1024, not 1000). Fixed `POST /man` respond example (`email_sent` field, not `response_sent`).
-- **API docs updated** — `/docs` page now documents `GET /agents/me`, `PATCH /agents`, agent `name`/`description` fields on `POST /agents`, `GET /changelog`, and `POST /man`. Table of contents updated with Agents and Discovery sections.
-- **JSON 404 catch-all** — unmatched routes now return `{"error": "Not found. Try POST /man for the API reference."}` instead of Express's default HTML page.
-- **Guide mode discoverability** — `POST /man?guide` now includes a `discover_more` object pointing to the full API reference, changelog, and agent update endpoint so agents don't have to guess at available endpoints.
-- **Welcome event in /man recommendation** — `POST /man` recommendation logic now accounts for the auto-created welcome event (same fix as changelog recommendations).
+- **Curl URL quoting** — all curl examples across docs, homepage, quickstart, `/man`, README, and spec files now wrap URLs in double quotes for shell safety (especially URLs with `?` query parameters).
+- **`/man` guide mode agent creation** — the recommended next step for unauthenticated agents now includes `name` and `description` params in the example curl body, so agents set their identity from the start.
+- **Docs placeholder standardization** — all curl examples in `/docs` now use consistent `UPPER_SNAKE_CASE` placeholders (`YOUR_API_KEY`, `CAL_ID`, `EVT_ID`, `FEED_TOKEN`) with gold highlighting. Added placeholder legend, error endpoints (`GET /errors`, `GET /errors/:id`), and fixed agent description max length (1024, not 1000). Fixed `GET /man` respond example (`email_sent` field, not `response_sent`).
+- **API docs updated** — `/docs` page now documents `GET /agents/me`, `PATCH /agents`, agent `name`/`description` fields on `POST /agents`, `GET /changelog`, and `GET /man`. Table of contents updated with Agents and Discovery sections.
+- **JSON 404 catch-all** — unmatched routes now return `{"error": "Not found. Try GET /man for the API reference."}` instead of Express's default HTML page.
+- **Guide mode discoverability** — `GET /man?guide` now includes a `discover_more` object pointing to the full API reference, changelog, and agent update endpoint so agents don't have to guess at available endpoints.
+- **Welcome event in /man recommendation** — `GET /man` recommendation logic now accounts for the auto-created welcome event (same fix as changelog recommendations).
 - **Agent creation rate limiter scope** — the strict agent creation rate limiter (POST /agents) no longer applies to GET /agents/me and PATCH /agents, which now use the general API rate limiter instead.
 - **`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.
@@ -48,7 +57,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **Inbound REQUEST after CANCEL** — when an organiser moves or re-sends an invite that was previously cancelled, the event is now un-cancelled (recurring events reset to `recurring` with rematerialized instances; non-recurring events reset to `tentative`)
 - **Calendar email domain** — calendar emails now correctly use `@invite.caldave.ai` (Postmark inbound domain) instead of `@caldave.ai`
 - **MCP server instructions** — the MCP server now sends a detailed `instructions` string during initialization, giving AI agents full context about CalDave's workflow, inbound email, recurring events, metadata, and tool usage guidance
-- **Machine-readable API manual** (`POST /man`) — JSON endpoint describing all CalDave API endpoints, with optional Bearer auth for personalized context. Returns real calendar IDs, event counts, and recommended next steps for authenticated agents. Designed for AI agent consumption.
+- **Machine-readable API manual** (`GET /man`) — JSON endpoint describing all CalDave API endpoints, with optional Bearer auth for personalized context. Returns real calendar IDs, event counts, and recommended next steps for authenticated agents. Designed for AI agent consumption.
 - **CalDave v1 core API** — calendar-as-a-service for AI agents
 - Agent provisioning (`POST /agents`) with API key generation (nanoid + SHA-256 hash)
 - Bearer token authentication middleware

README.md

@@ -46,22 +46,22 @@ The database and schema are created automatically.
 
 ```bash
 # Create an agent (returns API key — save it!)
-curl -s -X POST http://127.0.0.1:3720/agents | jq
+curl -s -X POST "http://127.0.0.1:3720/agents" | jq
 
 # Create a calendar
-curl -s -X POST http://127.0.0.1:3720/calendars \
+curl -s -X POST "http://127.0.0.1:3720/calendars" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer YOUR_API_KEY" \
   -d '{"name": "Work Schedule", "timezone": "America/Denver"}' | jq
 
 # Create an event
-curl -s -X POST http://127.0.0.1:3720/calendars/CAL_ID/events \
+curl -s -X POST "http://127.0.0.1:3720/calendars/CAL_ID/events" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer YOUR_API_KEY" \
   -d '{"title": "Daily standup", "start": "2025-03-01T09:00:00-07:00", "end": "2025-03-01T09:15:00-07:00"}' | jq
 
 # Check upcoming events
-curl -s http://127.0.0.1:3720/calendars/CAL_ID/upcoming \
+curl -s "http://127.0.0.1:3720/calendars/CAL_ID/upcoming" \
   -H "Authorization: Bearer YOUR_API_KEY" | jq
 ```
 

SPEC.md

@@ -11,10 +11,10 @@ docker compose up --build
 DATABASE_URL=postgres://plc:postgres@localhost:5432/caldave PORT=3720 npm run dev
 
 # Test health
-curl http://127.0.0.1:3720/health
+curl "http://127.0.0.1:3720/health"
 
 # Create an agent
-curl -X POST http://127.0.0.1:3720/agents
+curl -X POST "http://127.0.0.1:3720/agents"
 
 # Deploy
 fly deploy
@@ -28,7 +28,7 @@ fly deploy
 | `GET /health` | No | Server health check |
 | `GET /health/db` | No | Database health check |
 | `POST /agents` | No | Create agent (returns API key) |
-| `POST /man` | Optional | Machine-readable API manual (JSON), personalized if authenticated |
+| `GET /man` | Optional | Machine-readable API manual (JSON), personalized if authenticated |
 | `POST /calendars` | Yes | Create calendar |
 | `GET /calendars` | Yes | List agent's calendars |
 | `GET /calendars/:id` | Yes | Get calendar details |
@@ -65,7 +65,7 @@ src/
 │   └── rateLimitStub.js  — Stub rate limit headers
 └── routes/
     ├── agents.js         — POST /agents
-    ├── man.js            — POST /man (machine-readable API manual)
+    ├── man.js            — GET /man (machine-readable API manual)
     ├── calendars.js      — Calendar CRUD
     ├── events.js         — Event CRUD + upcoming + respond
     ├── feeds.js          — iCal feed generation

src/db.js

@@ -152,6 +152,7 @@ async function initSchema() {
     ALTER TABLE agents ADD COLUMN IF NOT EXISTS smtp_user text;
     ALTER TABLE agents ADD COLUMN IF NOT EXISTS smtp_pass text;
     ALTER TABLE agents ADD COLUMN IF NOT EXISTS smtp_from text;
+    ALTER TABLE agents ADD COLUMN IF NOT EXISTS smtp_secure boolean;
   `);
 
   // Backfill inbound_token for existing calendars that don't have one

src/index.js

@@ -145,9 +145,9 @@ app.get('/', (req, res) => {
     </ul>
 
     <pre><code><span class="dim"># Get started in seconds</span>
-curl -s -X POST https://${DOMAIN}/man?guide</code></pre>
+curl -s "https://${DOMAIN}/man?guide"</code></pre>
 
-    <p style="color:#fbbf24; font-size:0.8125rem; margin-bottom:1.5rem;"><strong>AI agents:</strong> Use curl or HTTP requests, not a browser. Run the command above or call <code style="background:#334155; padding:0.125rem 0.375rem; border-radius:4px; font-size:0.8125rem;">POST /man</code> for a machine-readable guide.</p>
+    <p style="color:#fbbf24; font-size:0.8125rem; margin-bottom:1.5rem;"><strong>AI agents:</strong> Use curl or HTTP requests, not a browser. Run the command above or call <code style="background:#334155; padding:0.125rem 0.375rem; border-radius:4px; font-size:0.8125rem;">GET /man</code> for a machine-readable guide.</p>
 
     <div class="links">
       <a href="/docs" class="primary">API Docs</a>
@@ -255,7 +255,7 @@ app.get('/errors/:id', auth, async (req, res) => {
 // ---------------------------------------------------------------------------
 
 app.use((req, res) => {
-  res.status(404).json({ error: 'Not found. Try POST /man for the API reference.' });
+  res.status(404).json({ error: 'Not found. Try GET /man for the API reference.' });
 });
 
 // ---------------------------------------------------------------------------

src/lib/outbound.js

@@ -42,12 +42,12 @@ function getPostmarkClient() {
 async function getAgentSmtpConfig(agentId) {
   if (!agentId) return null;
   const { rows } = await pool.query(
-    'SELECT smtp_host, smtp_port, smtp_user, smtp_pass, smtp_from FROM agents WHERE id = $1',
+    'SELECT smtp_host, smtp_port, smtp_user, smtp_pass, smtp_from, smtp_secure FROM agents WHERE id = $1',
     [agentId]
   );
   if (rows.length === 0 || !rows[0].smtp_host) return null;
   const r = rows[0];
-  return { host: r.smtp_host, port: r.smtp_port, user: r.smtp_user, pass: r.smtp_pass, from: r.smtp_from };
+  return { host: r.smtp_host, port: r.smtp_port, user: r.smtp_user, pass: r.smtp_pass, from: r.smtp_from, secure: r.smtp_secure };
 }
 
 /**
@@ -62,7 +62,7 @@ async function sendViaSmtp(smtpConfig, params) {
   const transporter = nodemailer.createTransport({
     host: smtpConfig.host,
     port: smtpConfig.port,
-    secure: smtpConfig.port === 465,
+    secure: smtpConfig.secure !== null && smtpConfig.secure !== undefined ? smtpConfig.secure : (smtpConfig.port === 465),
     auth: { user: smtpConfig.user, pass: smtpConfig.pass },
   });