API Reference

Print Mail

Targeted List Builds

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create Targeted List Build

POST/print-mail/v1/targeted_list_builds

Create a new targeted list build. A quote will be generated asynchronously based on the provided filters.

Header ParametersExpand Collapse

"idempotency-key": optional string

Body ParametersJSONExpand Collapse

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

limit: optional number

Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included.

formatint32

minimum1

metadata: optional map[unknown]

See the section on Metadata.

usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }

Filters used to target US companies (B2B) when building a list.

postalCodes: array of string

Required list of five-digit US ZIP codes to target.

companyTypes: optional array of "public" or "private" or "educational" or 3 more

Filter by ownership structure of the company.

One of the following:

"public"

"private"

"educational"

"government"

"nonprofit"

"public_subsidiary"

employeeCount: optional array of number

Inclusive [min, max] range for the number of employees at the company. Values must be between 1 and 1,000,000.

foundedYear: optional array of number

Inclusive [min, max] range for the year the company was founded. Values must be between 1600 and 2100.

industries: optional array of string

Filter by free-form industry names (see the autocomplete endpoint).

naicsCodes: optional array of string

Filter by six-digit NAICS industry codes.

tags: optional array of string

Filter by free-form company tags (e.g., "saas", "b2b").

usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }

Filters used to target US consumers (B2C) when building a list.

The geographic filters (zipCodesAround, cityStates, zipCodes) are mutually exclusive — you may supply at most one of them.

ageRange: optional array of number

Inclusive [min, max] age range. Values must be between 18 and 80.

cityStates: optional array of string

A list of "City, ST" strings (e.g. "New York, NY") to target.

educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"

Filter by highest level of education completed.

One of the following:

"high_school"

"college"

"grad_school"

"vocational_training"

gender: optional "male" or "female"

Gender filter for US consumer list builds.

One of the following:

"male"

"female"

homeValueRange: optional array of number

Inclusive [min, max] home value range, in US dollars. Values must be between 0 and 1,000,000.

incomeRange: optional array of number

Inclusive [min, max] annual household income range, in US dollars. Values must be between 0 and 200,000.

numChildrenRange: optional array of number

Inclusive [min, max] number of children in the household. Values must be between 0 and 8.

occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 23 more

Filter by occupation classification.

One of the following:

"professional_technical"

"administration_management"

"sales_service"

"clerical_white_collar"

"craftsmen_blue_collar"

"student"

"homemaker"

"retired"

"farmer"

"military"

"religious"

"self_employed"

"self_employed_professional_technical"

"self_employed_administration_management"

"self_employed_sales_service"

"self_employed_clerical_white_collar"

"self_employed_craftsmen_blue_collar"

"self_employed_student"

"self_employed_homemaker"

"self_employed_retired"

"self_employed_other"

"educator"

"financial_professional"

"legal_professional"

"medical_professional"

"other"

zipCodes: optional array of string

A list of five-digit US ZIP codes to target.

zipCodesAround: optional object { radiusInMiles, zipCode }

A geographic filter that selects all ZIP codes within a given radius of a center ZIP code.

radiusInMiles: number

The radius in miles around zipCode to include. Between 0.1 and 100.

formatfloat

minimum0.1

maximum100

zipCode: string

The five-digit ZIP code at the center of the search circle.

ReturnsExpand Collapse

id: string

A unique ID prefixed with targeted_list_build_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

organization: string

The ID of the organization that owns this list build.

status: "generating_quote" or "quote_ready" or "creating_list" or 2 more

Status of a targeted list build.

One of the following:

"generating_quote"

"quote_ready"

"creating_list"

"completed"

"failed"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

buildProgressPercent: optional number

A percentage from 0 to 100 representing how much of the build has completed. Only populated while status is creating_list.

formatfloat

minimum0

maximum100

completedAt: optional string

The UTC time at which the build finished successfully. Only present once status is completed.

formatdate-time

confirmedAt: optional string

The UTC time at which the build was confirmed, if any.

formatdate-time

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

errors: optional array of object { message, type }

Any errors encountered while generating a quote or building the list.

message: string

A human-readable message describing the error.

type: "not_enough_info_to_quote" or "insufficient_credits" or "internal_service_error"

Type of error encountered while generating a quote or building the list.

One of the following:

"not_enough_info_to_quote"

"insufficient_credits"

"internal_service_error"

limit: optional number

Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included.

formatint32

minimum1

mailingList: optional string

The ID of the mailing list that was built. Present once status is completed.

metadata: optional map[unknown]

See the section on Metadata.

previewRecords: optional array of object { formattedAddress, name }

A small number of masked sample records for the configured filters, populated alongside quote.

formattedAddress: string

The masked, comma-joined formatted address of the contact.

name: string

The masked name of the contact or business.

quote: optional object { count, generatedAt, pricePerContactCents }

Details of the quote generated for a targeted list build.

count: number

The number of contacts that will be included in the built mailing list. This accounts for any limit that was provided.

formatint32

generatedAt: string

The UTC time at which the quote was generated.

formatdate-time

pricePerContactCents: number

The price per contact, in cents. Multiply by count to get the total cost of building the list.

formatdouble

usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }

Filters used to target US companies (B2B) when building a list.

postalCodes: array of string

Required list of five-digit US ZIP codes to target.

companyTypes: optional array of "public" or "private" or "educational" or 3 more

Filter by ownership structure of the company.

One of the following:

"public"

"private"

"educational"

"government"

"nonprofit"

"public_subsidiary"

employeeCount: optional array of number

Inclusive [min, max] range for the number of employees at the company. Values must be between 1 and 1,000,000.

foundedYear: optional array of number

Inclusive [min, max] range for the year the company was founded. Values must be between 1600 and 2100.

industries: optional array of string

Filter by free-form industry names (see the autocomplete endpoint).

naicsCodes: optional array of string

Filter by six-digit NAICS industry codes.

tags: optional array of string

Filter by free-form company tags (e.g., "saas", "b2b").

usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }

Filters used to target US consumers (B2C) when building a list.

The geographic filters (zipCodesAround, cityStates, zipCodes) are mutually exclusive — you may supply at most one of them.

ageRange: optional array of number

Inclusive [min, max] age range. Values must be between 18 and 80.

cityStates: optional array of string

A list of "City, ST" strings (e.g. "New York, NY") to target.

educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"

Filter by highest level of education completed.

One of the following:

"high_school"

"college"

"grad_school"

"vocational_training"

gender: optional "male" or "female"

Gender filter for US consumer list builds.

One of the following:

"male"

"female"

homeValueRange: optional array of number

Inclusive [min, max] home value range, in US dollars. Values must be between 0 and 1,000,000.

incomeRange: optional array of number

Inclusive [min, max] annual household income range, in US dollars. Values must be between 0 and 200,000.

numChildrenRange: optional array of number

Inclusive [min, max] number of children in the household. Values must be between 0 and 8.

occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 23 more

Filter by occupation classification.

One of the following:

"professional_technical"

"administration_management"

"sales_service"

"clerical_white_collar"

"craftsmen_blue_collar"

"student"

"homemaker"

"retired"

"farmer"

"military"

"religious"

"self_employed"

"self_employed_professional_technical"

"self_employed_administration_management"

"self_employed_sales_service"

"self_employed_clerical_white_collar"

"self_employed_craftsmen_blue_collar"

"self_employed_student"

"self_employed_homemaker"

"self_employed_retired"

"self_employed_other"

"educator"

"financial_professional"

"legal_professional"

"medical_professional"

"other"

zipCodes: optional array of string

A list of five-digit US ZIP codes to target.

zipCodesAround: optional object { radiusInMiles, zipCode }

A geographic filter that selects all ZIP codes within a given radius of a center ZIP code.

radiusInMiles: number

The radius in miles around zipCode to include. Between 0.1 and 100.

formatfloat

minimum0.1

maximum100

zipCode: string

The five-digit ZIP code at the center of the search circle.

Create Targeted List Build

HTTP

HTTP

TypeScript

Python

curl https://api.postgrid.com/print-mail/v1/targeted_list_builds \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
    -d '{}'

201 example

{
  "id": "targeted_list_build_123",
  "live": false,
  "description": "Q1 prospecting list",
  "metadata": {
    "campaign": "q1_prospecting"
  },
  "createdAt": "2026-01-05T10:00:00Z",
  "updatedAt": "2026-01-05T10:01:30Z",
  "organization": "organization_123",
  "status": "quote_ready",
  "usCompanies": {
    "postalCodes": [
      "10001",
      "10002"
    ],
    "industries": [
      "software"
    ],
    "employeeCount": [
      10,
      500
    ]
  },
  "limit": 1000,
  "quote": {
    "generatedAt": "2026-01-05T10:01:30Z",
    "count": 1000,
    "pricePerContactCents": 11.98
  },
  "previewRecords": [
    {
      "name": "Acm***",
      "formattedAddress": "12** Main St, New York, NY, 100**"
    }
  ],
  "errors": []
}

Returns Examples

201 example

{
  "id": "targeted_list_build_123",
  "live": false,
  "description": "Q1 prospecting list",
  "metadata": {
    "campaign": "q1_prospecting"
  },
  "createdAt": "2026-01-05T10:00:00Z",
  "updatedAt": "2026-01-05T10:01:30Z",
  "organization": "organization_123",
  "status": "quote_ready",
  "usCompanies": {
    "postalCodes": [
      "10001",
      "10002"
    ],
    "industries": [
      "software"
    ],
    "employeeCount": [
      10,
      500
    ]
  },
  "limit": 1000,
  "quote": {
    "generatedAt": "2026-01-05T10:01:30Z",
    "count": 1000,
    "pricePerContactCents": 11.98
  },
  "previewRecords": [
    {
      "name": "Acm***",
      "formattedAddress": "12** Main St, New York, NY, 100**"
    }
  ],
  "errors": []
}