What does a direct mail API do?
A direct mail API lets software request a physical postcard or letter from structured data. The API receives the event, recipient, address, creative, and release context, then returns operational status that the source system can store and review.
The API is not just a shortcut around a dashboard. In an event-to-mail workflow, it becomes the record boundary between software behavior and physical production. That boundary should explain why a piece was considered, held, approved, released, tracked, or reviewed later.
What should the API record before it creates mail?
Before mail is created, the API should record enough context to identify the source event, review the address, render the creative safely, prevent duplicate sends, join tracking fields, and explain the release decision.
| Record layer | Fields to keep visible | Why it matters |
|---|---|---|
| Source event | Event ID, source system, source record ID, timestamp, trigger reason. | Explains why the API request exists and supports later audit review. |
| Recipient and address | Recipient key, name, company, address lines, city, state, ZIP Code, secondary-unit state, original and reviewed address. | Connects API data to USPS addressing and address-quality review. |
| Creative and merge data | Template ID, artwork version, merge fields, fallback values, proof version. | Keeps variable content and final proof review traceable. |
| Release control | Send rule result, suppression result, approval state, owner, exception reason. | Shows why a record moved forward, paused, or stopped. |
| Retry safety | Idempotency key, payload fingerprint, first request state, retry history. | Reduces the chance that one software retry creates more than one mail record. |
| Join keys | Campaign ID, batch ID, mailpiece ID, barcode or status-event keys when available. | Connects the API request to production, mailstream visibility, and later measurement. |
How should event payloads and send rules work together?
The event payload supplies the source data. The send rule decides whether that data is eligible to mail. A direct mail API should preserve both pieces so operators can explain the decision instead of guessing from a final send file.
For the source data contract, see the direct mail event payload guide. For the release logic, see the direct mail send-rule guide. The API should make the relationship between those records easy to inspect.
Operator rule: save the source event before modifying the mailing record. Corrections can happen later, but the original trigger should remain explainable.
How should a direct mail API handle retries and duplicate sends?
A direct mail API should use a stable idempotency key for each intended create-mail request. If the client retries the same request, the API should return the original accepted, held, rejected, or released state instead of silently creating another piece.
Idempotency is not the same thing as duplicate-send prevention. Idempotency handles retry safety for one intended request. A duplicate-send prevention rule checks whether a similar person, household, address, campaign, or review window has already mailed. For the retry-safety layer, see the direct mail idempotency key guide.
How should tracking joins work after release?
After release, the API record should connect the original event and recipient to campaign IDs, batch IDs, mailpiece IDs, and status events. USPS Intelligent Mail barcode and Informed Visibility resources describe postal visibility systems; the API record keeps workflow context attached.
Keep the boundary clear. A tracking join can help operators review the mailstream, but it does not prove that a recipient saw the mail, responded, or generated lift. For adjacent records, see the USPS tracking guide, campaign ID guide, mailpiece ID guide, and measurement-window guide.
What should teams verify before connecting an endpoint?
Before relying on a direct mail API, verify the endpoint can preserve source events, structured addresses, proof approval, send-rule decisions, idempotency behavior, exception states, tracking joins, and measurement boundaries.
| Readiness check | Question to answer before release |
|---|---|
| Address readiness | Does the workflow separate original address fields from the reviewed mailing address? |
| Proof readiness | Can reviewers see the final artwork, variable fields, fallback copy, and approval state? |
| Release readiness | Does the send rule show why the record was approved, held, suppressed, or rejected? |
| Retry readiness | Can a retry return the original request state without creating a second mail record? |
| Exception readiness | Can invalid addresses, changed payloads, missing proofs, and suppressed records pause for review? |
| Tracking readiness | Can batch, mailpiece, barcode, and status-event fields join back to the source event? |
| Measurement readiness | Is the response window declared before results are reviewed? |
How does Sendvo fit this API workflow?
Sendvo is in beta as a self-service direct-mail platform. Current public materials describe audience building, browser-based postcard design, USPS tracking, triggered sends, integrations, and an API surface at api.sendvo.io.
For API-connected direct mail, the practical evaluation question is whether the workflow keeps event payloads, address checks, proof versions, idempotency keys, campaign IDs, batch records, tracking joins, and audit trails visible before results are reviewed. For the broader automation pattern, see the triggered postcards guide and the direct mail audit-trail guide.
Direct mail API FAQ
What is a direct mail API?
A direct mail API is a software interface that lets an application request physical mail from structured data. A safe workflow records the source event, recipient and address, creative version, approval state, idempotency key, batch or mailpiece IDs, status events, and later measurement context.
What fields should a direct mail API record before sending mail?
Before sending mail, the API record should preserve the event payload, recipient key, original and reviewed address, template or artwork version, merge fields, proof approval, send rule result, idempotency key, campaign ID, batch context, and status-event destination.
Does USPS tracking prove a direct mail campaign worked?
No. USPS mailstream tracking can help operators review where a piece was in the mailing process, but it does not prove recipient exposure, response, revenue, or lift. Teams need separate response sources and declared measurement windows.
Sources
- RFC 9110: HTTP Semantics, Idempotent Methods
- Stripe API documentation: Idempotent requests
- USPS Postal Explorer: Publication 28 Postal Addressing Standards
- USPS Domestic Mail Manual: Section 602 Addressing
- USPS Domestic Mail Manual: Section 201 Commercial Letters, Flats, and Parcels Design Standards
- USPS Domestic Mail Manual: Section 204 Barcode Standards
- USPS PostalPro: Intelligent Mail Barcode
- USPS PostalPro: Informed Visibility
Evaluate API-ready direct mail workflows.
Sendvo is a beta direct-mail platform for teams connecting audience data, postcard design, triggered sends, USPS tracking, and reviewable mail records. Keep event payloads, idempotency keys, proofs, batches, tracking joins, and measurement windows visible before release.