Guides

Neighborhood Mail over the API

Send the addresses to mail around, and get the homes found and mailed for each one.

How it works

On a Neighborhood Mail campaign, each address you send is a center, not a recipient: the center itself is never mailed. Inside the request, we find the homes within the campaign's radius around each center, apply the campaign's filters, fit them to its budget, and mail them.

Send centers to POST /api/v1/recipients with your Full access key, exactly as you would send recipients. See the Dynamic Audience API reference.
The custom fields you send with a center apply to every home around it.
Each center's result reports homesFound (the homes within the radius) and homesMailed (the homes mailed).
A center with no homes within the radius comes back not_mailed with no_homes_found.
When the budget or the request's home limit stops part of a center's homes, the center is still mailed, and its detail says how many of the homes found were mailed and why the rest were not. When neither leaves room for any of its homes, it comes back not_mailed with budget_exceeded or request_capacity_reached.

curl https://www.postaged.com/api/v1/recipients \
  -H "Authorization: Bearer $POSTAGED_SEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "PA-4H2K9C",
    "recipients": [
      {
        "reference": "listing-118",
        "address_1": "118 Maple Ave",
        "city": "West Hartford",
        "state": "CT",
        "zip": "06107"
      },
      {
        "reference": "listing-204",
        "address_1": "204 Ridge Rd",
        "city": "Avon",
        "state": "CT",
        "zip": "06001"
      }
    ]
  }'

const response = await fetch("https://www.postaged.com/api/v1/recipients", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POSTAGED_SEND_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "PA-4H2K9C",
    recipients: [
      {
        reference: "listing-118",
        address_1: "118 Maple Ave",
        city: "West Hartford",
        state: "CT",
        zip: "06107",
      },
      {
        reference: "listing-204",
        address_1: "204 Ridge Rd",
        city: "Avon",
        state: "CT",
        zip: "06001",
      },
    ],
  }),
});
const result = await response.json();
console.log(result);

import os

import requests

response = requests.post(
    "https://www.postaged.com/api/v1/recipients",
    headers={"Authorization": f"Bearer {os.environ['POSTAGED_SEND_KEY']}"},
    json={
        "campaign_id": "PA-4H2K9C",
        "recipients": [
            {
                "reference": "listing-118",
                "address_1": "118 Maple Ave",
                "city": "West Hartford",
                "state": "CT",
                "zip": "06107",
            },
            {
                "reference": "listing-204",
                "address_1": "204 Ridge Rd",
                "city": "Avon",
                "state": "CT",
                "zip": "06001",
            },
        ],
    },
    timeout=300,
)
print(response.json())

Response200 OK

{
  "summary": { "received": 2, "mailed": 1, "notMailed": 1 },
  "results": [
    {
      "reference": "listing-118",
      "address": "118 Maple Ave, West Hartford, CT 06107-2614",
      "status": "mailed",
      "homesFound": 42,
      "homesMailed": 42,
      "detail": "42 homes around this address."
    },
    {
      "reference": "listing-204",
      "address": "204 Ridge Rd, Avon, CT 06001-3901",
      "status": "not_mailed",
      "reason": "no_homes_found",
      "detail": "No homes inside the radius around this address."
    }
  ]
}

Limits

250 centers per request.
10,000 homes mailed per request. Homes past that limit are not mailed in this request: send their centers again in another request.
Every other Dynamic Audience API limit applies, including 4.25 MB per request body and 60 requests per minute per API key. See Rate limits.

Check before you send

Which homes are found depends on the address data for the area you mail. Run a payload through Send test request in the campaign's API / Webhook setup first: a test reports the homes found around each center, and never mails or charges. See Testing.