Addresses and deliverability

How to supply an address, what validation changes, and how to read the deliverability fields.

Every recipient address is validated and standardized before the mailpiece is produced. Understanding what validation does to your data — and which fields it writes back — avoids the two most common surprises: recipients silently marked undeliverable, and fields you set being overwritten.

Two ways to supply an address

Either works. The address requirement is satisfied by either the component fields or a single line.

Component fields (preferred), under address:

{
  "address": {
    "address1": "1600 Pennsylvania Ave NW",
    "address2": "Suite 300",
    "city": "Washington",
    "state": "DC",
    "zipCode": "20500"
  }
}

A single unparsed line, as metadata.fullAddress:

{ "metadata": { "fullAddress": "1600 Pennsylvania Ave NW, Washington, DC 20500" } }

fullAddress is a genuine fallback, not a convenience alias: when the component fields are incomplete, supplying fullAddress is what stops the recipient being rejected for a missing address. If you have structured data, send the component fields — parsing is more reliable when you have already done it.

metadata.fullAddress and metadata.text, metadata.text2 are declared non-nullable. Send an empty string rather than null for any you are not using.

What you send versus what validation writes

Field	Who sets it
`address1`, `address2`, `city`, `state`, `zipCode`	You. Validation may standardize the values.
`zip4`	Validation. Sending it has no effect on delivery.
`zip2`	Validation. The delivery-point code; sending it has no effect.
`country`	You. US spellings and US territory names are canonicalized; anything else passes through unchanged. Omit for US addresses.
`metadata.dpvConfirmationCode`	Validation. Read-only; ignored on input.
`metadata.deliveryStatus`	Carrier tracking. Read-only; ignored on input.

state accepts either the two-letter abbreviation or the full state name — a full name is converted for you.

Reading the deliverability result

dpvConfirmationCode is the USPS Delivery Point Validation result, passed through as the postal standard defines it:

Code	Meaning
`Y`	Confirmed — a valid delivery point.
`N`	Not confirmed — could not be validated.
`S`	Confirmed after dropping the unit or suite information.
`D`	Confirmed to the building only; unit information is missing.
empty	Not yet validated.

S and D are deliverable but imprecise: mail reaches the building, and a unit number you supplied may have been dropped or was never matched. If unit-level accuracy matters to your campaign, treat them as warnings.

Do not confuse this with DPV footnotes, a longer code set in which the same letters carry different meanings. This field is the confirmation code only.

Undeliverable recipients

Recipients that fail validation are not silently dropped: the add-recipients response separates them out, so read its payload rather than assuming everything you sent was accepted. Compare the count you sent against the count accepted on every call, and log the undeliverable set — that is your data-quality signal, and it is cheaper to fix at the source than to discover in a delivery report.

Recipients are also checked against your suppression lists and de-duplicated within the batch during the same step, so the accepted count can legitimately be lower than what you sent for reasons other than a bad address.

Delivery status after mailing

Once a piece mails, deliveryStatus tracks it through: Waiting on USPS Info, Mailed, In Transit, At Local Facility, Delivered, or Undeliverable.

Before the first tracking update arrives you will see No Tracking Available. That is the normal pending state, not an error and not a delivery failure — do not alert on it.