Direct Mail

This document defines the schema and bucket structure for direct mail integrations with SearchLight. For S3 setup, file format, and access steps see the overview.

Bucket Key Structure

standard-direct-mail/{account-id}/{YYYY-MM-DD}/{filename}.json.gz

Example: standard-direct-mail/pk7f3q9x2m/2026-02-19/direct_mail_bort.json.gz

{account-id} is your internal identifier for the location: the id your own system uses (e.g. pk7f3q9x2m or 48211). Use it as-is and keep it stable for the life of the integration.

The date in the path reflects the updated_at date of the record. If a record is created on 2026-03-10 but updated on 2026-03-15, it should appear in the 2026-03-15 folder. The original record in the 2026-03-10 folder can either be removed or left in place, either is acceptable.

---

Schema

Field	Type	Required	Description	Example
id	string	required	Unique identifier for the job record	"12345"
account_name	string	required	Name of the account	"Example Account"
location_name	string	required	Name of the business location the job was for	"Jim's HVAC"
campaign_name	string	required	Name of the campaign	"Example Campaign Name"
campaign_phone_numbers	string[]	required	Array of tracking numbers associated with the job's campaign	["000-000-0000"]
drop_dates	string[] (ISO 8601)	required	Array of dates the mail pieces were dropped for a given job	["2024-12-09"]
order_quantity_mailed	number	required	Total number of mail pieces sent	8000
order_total_cost	number	required	Total cost of the job in dollars	3200
updated_at	string (ISO 8601)	required	Date the record was uploaded or last updated	"2025-01-01"
order_total_cost_per_piece	number	optional	Cost per mail piece in dollars	0.4

---

Example Record

{
  "id": "12345",
  "account_name": "Example Account",
  "location_name": "Jim's HVAC",
  "campaign_name": "Example Campaign Name",
  "campaign_phone_numbers": ["000-000-0000"],
  "updated_at": "2025-01-01",
  "drop_dates": ["2024-12-09"],
  "order_quantity_mailed": 8000,
  "order_total_cost": 3200,
  "order_total_cost_per_piece": 0.4
}