# Addresses and deliverability (/addresses)



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 [#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`:

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

**A single unparsed line**, as `metadata.fullAddress`:

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

<Callout>
  `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.
</Callout>

`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 [#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 [#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.

<Callout type="warn">
  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.
</Callout>

## Undeliverable recipients [#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 [#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.