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}/{YYYY-MM-DD}/{filename}.json.gz

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

The date in the path reflects the updatedAt 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
accountId	number	required	Unique identifier for the account	12345
accountName	string	required	Name of the account	"Example Account"
campaignId	string	required	Unique identifier for the campaign (or work order)	"1111111"
campaignName	string	required	Name of the campaign	"Example Campaign Name"
campaignPhoneNumbers	string[]	required	Array of tracking numbers associated with the campaign	["000-000-0000"]
dropDates	string[] (ISO 8601)	required	Array of dates the mail pieces were dropped for a given campaign	["2024-12-09"]
orderQuantityMailed	number	required	Total number of mail pieces sent	8000
orderTotalCost	number	required	Total cost of the campaign in dollars	3200
updatedAt	string (ISO 8601)	required	Date the record was uploaded or last updated	"2025-01-01"
orderTotalCostPerPiece	number	optional	Cost per mail piece in dollars	0.4

---

Example Record

{
  "accountId": 12345,
  "accountName": "Example Account",
  "campaignId": "1111111",
  "campaignName": "Example Campaign Name",
  "campaignPhoneNumbers": ["000-000-0000"],
  "updatedAt": "2025-01-01",
  "dropDates": ["2024-12-09"],
  "orderQuantityMailed": 8000,
  "orderTotalCost": 3200,
  "orderTotalCostPerPiece": 0.4
}