--- name: neighbor-mail-coordinator description: "When and how to run neighbor postcard blasts, record jobs for matchback, honor opt-outs, and read ROI with the neighbor-mail plugin." metadata: version: 0.1.0 openclaw: category: find-customers requires: bins: - neighbor-mail triggers: - blast - postcards - neighbors - mail the street - matchback - opt out - take me off --- # Neighbor Mail — how to run it The `neighbor-mail` plugin talks to the company's Neighbor Mail account. Every command prints JSON. Money moves only on `blasts send` and `blasts approve`. ## The loop 0. **Pick the audience**: `neighbor-mail audiences list` → names and ids. `neighbor-mail audiences get ` → the fields and the `sentence`; read the sentence back, never your own paraphrase. No `--audience` means the template's default `audience_id`, else the tenant default. Draft one from a description ("60+, homeowners, 10+ years in the home"): `neighbor-mail audiences create --name "Long-time owners" --preset owner_occupied --tenure-years-min 10 --radius-miles 2` after saying, in one sentence, that age is not a filter and asking to save. Edit with `audiences update …`; `audiences delete ` needs approval. The fields are the ones `audiences get` returns and nothing else; the API refuses the rest and names what it has. Age and income are not filters. Flag spellings: `skill(action: "browse", name: "neighbor-mail-audiences", path: "reference/actions.md")`. Reading one back: `audiences get aud_12` → its `sentence` → say that sentence, word for word; never your own paraphrase. 1. **Preview**: `neighbor-mail blasts preview --origin-address "123 Oak St, Austin, TX 78704" --rep "Jordan" --job-ref "new windows" --idempotency-key JOB-123 --audience aud_12` Read `funnel`: `pulled → residential → matched_preset → deliverable → suppressed → selected`, and `funnel.price_cents`. 2. **Send** what was previewed: `neighbor-mail blasts approve ` — or, for a trusted trigger, do both at once with `neighbor-mail blasts send …` (same flags as preview). 3. **Record the job**: `neighbor-mail matchback add --address "…" --external-id JOB-123 --completed-at 2026-09-15 --revenue-cents 1250000 --source jobber` This attributes the job to any postcard mailed to that address in the last 90 days and suppresses it as a customer. ## Plays Three cards come already written for an audience; `neighbor-mail templates list` shows them by name with their `audience_id`. Never a fourth. | Play | Template id | Audience | When it fits | |------|-------------|----------|--------------| | The job next door | `neighbor_job` | Owner-occupied neighbors | The day a job finishes. The default. | | Seventh house this year | `seventh_house` | Long-time owners | `report get` shows two or more jobs on the same street this year. | | Seasonal | `seasonal` | Owner-occupied neighbors | A slow stretch; the owner fills in `{{deadline}}` first. | - A play is sent by its template: `blasts preview … --template-id seventh_house`; the audience it is written for comes with it unless `--audience` says otherwise. - *Seventh house* prints `{{jobs_on_street_this_year}}`, the count of distinct homes on the recipient's street with a job recorded this calendar year. Under two it is blank and the card's plain words print instead. It only counts what `matchback add` recorded, so for this play record the job before the blast. - "What should I send?": `report get` + `templates list`, then one play and one reason. No history yet: list the three, *The job next door* first. - Designing and writing: `neighbor-mail templates update --size 6x11 --split 1/3 --photo --bg "#0f4c81" --headline "…" --body "…" --message "…"` (the reference: `skill(action: "browse", name: "neighbor-mail-templates", path: "reference/actions.md")`). A designed card is proofed on save; an error names what did not fit, and a warning names a `{{field}}` still waiting to be filled — the card previews with the placeholder printed as words, and `blasts send` refuses it by name until it is replaced. The photo: `neighbor-mail assets upload --file ` → `{"id": …}`. The proof: `neighbor-mail templates proof --output /neighbor-mail-.png`, shown as `![Proof](/api/v1/files/neighbor-mail-.png)`. The craft is in the `neighbor-mail-craft` skill. ## Reading a result - `selected < n` is normal: the rest were mailed inside the window, are customers, or opted out. Say the number; don't retry bigger. - `duplicate: true` means this idempotency key already ran — nothing new was mailed. - `error` mentioning balance: quote the amount short and point the owner to Billing. Don't retry. - The call itself did not land — `dns error`, connection refused, a timeout, `NeboAI session expired`: say Neighbor Mail could not be reached, quote the error in one short clause, and stop. Answer nothing that call was going to carry: no price, no balance, no count, no audience. A number you did not read in this conversation is a number you invented, and the owner will repeat it to a customer. This is the same rule as quoting prices from `billing get` and never from memory — a failed call is a missing answer, not a remembered one. ## Suppression - Homeowner says stop: `neighbor-mail suppression add --address "…" --reason opt_out` — immediately, permanent. - Rep already knocked: `--reason knocked --days 60`. - Search: `neighbor-mail suppression list --q "Oak"`. ## Reporting `neighbor-mail report get` → `totals.revenue_cents ÷ totals.price_cents` is the ROI. The report also carries totals by audience; when more than one audience mailed, lead with ROI per audience, best first, then the total. `blasts list` for recent activity, `blasts get ` for one blast's pieces, proofs and audience. `billing get` for the balance. ## Summaries One line, numbers first, audience named: "Sent 50 to Long-time owners around Oak St (412 pulled → 188 owner-occupied → 61 ten-plus years → 50 not recently mailed). $49.50."

neighbor-mail-coordinator

About this skill