[Spreadsheet integration]

Send postal mail from Google Sheets rows

Use Google Sheets for row-based mail merge, batch sends, and lightweight approval queues, then write mailbox.bot estimates, tracking, proof, forwarded docs, and mail-photo links back into the sheet.

recommended shape

approved rows read by script

template renders each letter

dry run per row before batch send

approved_by column gates live mail

status, tracking, proof back in columns

Best for

Batch letters and postcards before a full app exists.

Ops teams maintaining recipient lists or permit trackers in spreadsheets.

Generated app prototypes where Sheets is the first database and status log.

Triggers

Row status changes to approved.

New row arrives from a form or import.

Scheduled job scans rows with a due date or missing response.

[Workflow]

1

Script, Zapier, n8n, or an agent reads approved rows.

2

Template logic renders a letter or PDF.

3

mailbox.bot dry run validates addresses and estimates cost.

4

Approved rows are sent live.

5

Status, tracking, mail_id, proof fields, and any inbound artifact links are written back to the row.

Technical pattern

Apps Script with UrlFetchApp posts each approved row; an installable time-driven or onEdit trigger starts the batch.

Columns for mail_id, mail_status, tracking, proof_url and approved_by, written with setValues after each response.

Store spreadsheet_id and the row number in metadata so the event handler can find the row.

Use a batch_id per run so a failed row can be retried alone.

Metadata to preserve

source=google_sheets

spreadsheet_id

sheet_name

row_id

batch_id

approved_by

POST/api/v1/maildry_run=true

curl -X POST https://mailbox.bot/api/v1/mail \
  -H "Authorization: Bearer sk_agent_test_..." \
  -H "X-Mailbox-MD-Version: <version>" \
  -H "X-Max-Cost-Cents: 1500" \
  -F "document=@row-letter.pdf" \
  -F "recipient_name=<recipient>" \
  -F "recipient_line1=<street>" \
  -F "recipient_city=<city>" \
  -F "recipient_state=<state>" \
  -F "recipient_zip=<zip>" \
  -F "mail_class=first_class" \
  -F "dry_run=true" \
  -F 'metadata[spreadsheet_id]=<spreadsheet_id>' \
  -F 'metadata[sheet_name]=<sheet_name>' \
  -F 'metadata[row_id]=<row_id>' \
  -F 'metadata[source]=google-sheets'

Agent prompts

"Build a Google Sheets mail-merge that sends approved rows through mailbox.bot with dry-run validation first."

"Create a spreadsheet workflow that writes mailbox.bot delivery proof back into each row."