Get Targeted List Build

print_mail.targeted_list_builds.retrieve() -> TargetedListBuildRetrieveResponse

GET/print-mail/v1/targeted_list_builds/{id}

Retrieve a specific targeted list build by its ID.

ParametersExpand Collapse

id: str

ReturnsExpand Collapse

class TargetedListBuildRetrieveResponse: …

A targeted list build represents a request to build a new mailing list by targeting US consumers or companies matching the provided filters. Once created, a quote is generated asynchronously. After reviewing the quote and preview records, you may confirm the build, which kicks off the creation of the underlying mailing list.

id: str

A unique ID prefixed with targeted_list_build_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

organization: str

The ID of the organization that owns this list build.

status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]

Status of a targeted list build.

One of the following:

"generating_quote"

"quote_ready"

"creating_list"

"completed"

"failed"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

build_progress_percent: Optional[float]

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

formatfloat

minimum0

maximum100

completed_at: Optional[datetime]

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

formatdate-time

confirmed_at: Optional[datetime]

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

formatdate-time

description: Optional[str]

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

errors: Optional[List[Error]]

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

message: str

A human-readable message describing the error.

type: Literal["not_enough_info_to_quote", "insufficient_credits", "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[int]

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

formatint32

minimum1

mailing_list: Optional[str]

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

metadata: Optional[Dict[str, object]]

See the section on Metadata.

preview_records: Optional[List[PreviewRecord]]

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

formatted_address: str

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

name: str

The masked name of the contact or business.

quote: Optional[Quote]

Details of the quote generated for a targeted list build.

count: int

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

formatint32

generated_at: datetime

The UTC time at which the quote was generated.

formatdate-time

price_per_contact_cents: float

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

formatdouble

us_companies: Optional[UsCompanies]

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

postal_codes: List[str]

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

company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]

Filter by ownership structure of the company.

One of the following:

"public"

"private"

"educational"

"government"

"nonprofit"

"public_subsidiary"

employee_count: Optional[List[int]]

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

founded_year: Optional[List[int]]

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

industries: Optional[List[str]]

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

naics_codes: Optional[List[str]]

Filter by six-digit NAICS industry codes.

tags: Optional[List[str]]

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

us_consumers: Optional[UsConsumers]

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.

age_range: Optional[List[int]]

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

city_states: Optional[List[str]]

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

education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]

Filter by highest level of education completed.

One of the following:

"high_school"

"college"

"grad_school"

"vocational_training"

gender: Optional[Literal["male", "female"]]

Gender filter for US consumer list builds.

One of the following:

"male"

"female"

home_value_range: Optional[List[int]]

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

income_range: Optional[List[int]]

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

num_children_range: Optional[List[int]]

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

occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 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"

zip_codes: Optional[List[str]]

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

zip_codes_around: Optional[UsConsumersZipCodesAround]

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

radius_in_miles: float

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

formatfloat

minimum0.1

maximum100

zip_code: str

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

Get Targeted List Build

import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
targeted_list_build = client.print_mail.targeted_list_builds.retrieve(
    "id",
)
print(targeted_list_build.id)

{
  "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

{
  "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": []
}