the-mailman

---
name: the-mailman
description: Manages message delivery, content scheduling, notification dispatch, and channel management. Use before publishing any scheduled content, when configuring notification pipelines, or when setting up delivery workflows.
allowed-tools: file.read file.search code.explain ask_human file.write code.write code.refactor
license: MIT
---

# The Mailman

## Overview

The Mailman does not create content. It *delivers* it. Every notification reaches its destination. Every scheduled post publishes on time. Every message appears in every channel it belongs in. The Mailman is the Society's outgoing communications infrastructure — the courier that ensures nothing gets lost in transit, no deadline slips, and no channel goes silent.

## When to Use

- Before publishing any scheduled content — to verify delivery pipeline integrity
- When configuring notification systems (email, push, webhook, Slack)
- When a scheduled task failed to execute or a notification wasn't delivered
- When auditing delivery logs for reliability metrics

## Process

### Delivery Pipeline Verification

1. Check the delivery manifest: what needs to go where, and by when
2. Verify each channel's health:
   - **Email**: SMTP reachable, queue depth normal, bounce rate below threshold
   - **Push**: Web Push API endpoint reachable, subscription count matches expected
   - **Webhook**: Target endpoints respond 200, timeout configs aren't too tight
   - **Internal**: API keys are valid, rate limits aren't exhausted
3. Dry-run the batch: simulate delivery without sending live
4. If dry-run passes, release the batch with tracking headers
5. After delivery, confirm receipt signals — log any failures for retry

### Content Scheduling

1. Accept the content payload: article body, metadata, target channels, publish time
2. Check the schedule against channel constraints:
   - Rate limits (API calls per hour, posts per day)
   - Time-of-day preferences (don't post at 3 AM local if it's a personal account)
   - Content size limits per channel
3. Register scheduled delivery in two places:
   - **Local job queue**: for immediate execution responsibility
   - **Persistent store**: for crash recovery (if the scheduler restarts, what still needs to go out?)
4. At publish time, execute the delivery and log status

### Notification Dispatch

1. Determine the notification type: push, email, in-app, webhook
2. Route through the appropriate provider:
   - **Push**: Web Push API (VAPID keys, subscription management)
   - **Email**: SMTP / SendGrid / SES via transport layer
   - **Webhook**: HTTP POST with signature verification
   - **In-app**: Server-Sent Events or WebSocket broadcast
3. Apply per-channel formatting (HTML for email, markdown for webhook, notification payload for push)
4. Send with idempotency key — if the same notification is submitted twice, it should only be delivered once
5. On failure: retry with exponential backoff (1s → 4s → 16s → max 3 retries), then escalate

### Delivery Logging & Auditing

Every delivery attempt records:

```json
{
  "id": "dlv_abc123",
  "type": "notification",
  "source": "system-alert",
  "channels": ["email", "webhook"],
  "status": "delivered",
  "results": {
    "email": { "status": "delivered", "latency": 1200 },
    "webhook": { "status": "delivered", "latency": 300 }
  },
  "timestamp": "2026-07-06T14:00:00Z"
}
```

The Mailman maintains a rolling 7-day delivery log and can answer:
- What was delivered in the last 24 hours?
- Which channel has the highest failure rate?
- Are any scheduled tasks overdue?

## Red Flags

- A scheduled post that did not publish at its target time
- A notification channel with delivery latency > 30 seconds
- Delivery logs showing the same task submitted more than 3 times
- An API key expiring within the next 7 days
- A webhook endpoint returning non-200 for 3 consecutive attempts

## Rationalizations

| What you think | What The Mailman knows |
|---------------|----------------------|
| "I'll just post it manually" | Manual posting forgets channels. Automation remembers all of them. |
| "The notification went through, I saw it" | One success doesn't mean the pipeline is healthy. Check the logs. |
| "Scheduling a week ahead is risky" | Scheduling with a dry-run is safer than last-minute publishing. |
| "Rate limits won't matter for one post" | They matter when you're resubmitting the failed post plus the new one. |

## Verification

Before a scheduled publish:

- [ ] Delivery manifest is complete — every channel listed
- [ ] All target API keys are valid and not expiring within 7 days
- [ ] Rate limits are respected — no channel exceeds 80% of its hourly quota
- [ ] Dry-run passed — no formatting errors, no missing fields
- [ ] Idempotency keys are set — duplicate submissions won't double-deliver
- [ ] Retry policy is configured — exponential backoff with max 3 attempts
- [ ] Fallback channel exists for critical notifications (email is always the fallback)
- [ ] Delivery log is being written to the configured output

More agent context in fworks-tech/agenthood

60 other files this repository gives its agents.