crm-snail-mail-postgrid

# CRM Snail Mail via PostGrid

Use this skill to run targeted direct-mail outreach from CRM contacts.

## Workflow

1. Pick source: `ghl`, `fub`, or pre-exported contact JSON.
2. Pull and normalize contacts into a common schema.
3. Filter to records with mailable addresses.
4. Build personalized message content.
5. Submit jobs to PostGrid (`letters` or `postcards`) with dry-run available.
6. Return send summary with success/failure per contact.

## Script

- `scripts/crm_postgrid_mailer.py`
Purpose: Pull contacts from GHL/FUB (or load from JSON), normalize fields, render templates, and send to PostGrid.
- `scripts/postgrid_api.py`
Purpose: Full PostGrid API utility with broad endpoint catalog and `call-raw` fallback for any documented endpoint.

## Environment Variables

- `GHL_API_KEY`: GHL API key/token.
- `GHL_BASE_URL` (optional): defaults to `https://services.leadconnectorhq.com`.
- `FUB_API_KEY`: Follow Up Boss API key.
- `FUB_BASE_URL` (optional): defaults to `https://api.followupboss.com/v1`.
- `POSTGRID_API_KEY`: PostGrid API key.
- `POSTGRID_BASE_URL` (optional): defaults to `https://api.postgrid.com/print-mail/v1`.

## Typical Commands

List full PostGrid endpoint catalog included in this skill:

```bash
python3 scripts/postgrid_api.py list-endpoints
```

Call a cataloged PostGrid endpoint:

```bash
python3 scripts/postgrid_api.py call contacts.list
```

Call any PostGrid endpoint directly (full docs coverage fallback):

```bash
python3 scripts/postgrid_api.py call-raw GET /letters \
  --base-url https://api.postgrid.com/print-mail/v1
```

Normalize contacts from FUB to JSON:

```bash
python3 scripts/crm_postgrid_mailer.py fetch \
  --provider fub \
  --limit 200 \
  --output /tmp/fub_contacts_normalized.json
```

Normalize contacts from GHL to JSON:

```bash
python3 scripts/crm_postgrid_mailer.py fetch \
  --provider ghl \
  --location-id "$GHL_LOCATION_ID" \
  --limit 200 \
  --output /tmp/ghl_contacts_normalized.json
```

Dry-run PostGrid payload gener...