API Reference

Print Mail

Mailing List Imports

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List Mailing List Imports

print_mail.mailing_list_imports.list(MailingListImportListParams**kwargs) -> SyncSkipLimit[MailingListImportResponse]

GET/print-mail/v1/mailing_list_imports

Retrieve a list of mailing list imports.

Returns a paginated list of imports associated with the authenticated organization, filterable by various parameters.

ParametersExpand Collapse

limit: Optional[int]

formatint32

search: Optional[str]

You can supply any string to help narrow down the list of resources. For example, if you pass "New York" (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on StructuredSearchQuery for more details.

skip: Optional[int]

formatint32

ReturnsExpand Collapse

class MailingListImportResponse: …

Read-only view of a MailingListImport

id: str

A unique ID prefixed with mailing_list_import_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

errors: List[Error]

A list of processing errors encountered, if any. Present when status is 'changes_required'.

message: str

A human-readable message describing the error.

type: Literal["no_valid_contacts_error", "multiple_countries_error", "invalid_contact_count_error", "internal_service_error"]

Type of error encountered during import processing.

One of the following:

"no_valid_contacts_error"

"multiple_countries_error"

"invalid_contact_count_error"

"internal_service_error"

file: File

The file object your controller returns: all the mappings plus a signed URL.

file_type: FileType

Type of file supported for mailing list imports.

receiver_address_mapping: Dict[str, str]

Mapping of columns for receiver addresses. Contact fields to file columns. Possible Contact fields:

• description
• firstName
• lastName
• email
• phoneNumber
• companyName
• addressLine1
• addressLine2
• jobTitle
• city
• postalOrZip
• provinceOrState
• countryCode

url: str

The signed URL your controller generates.

formaturi

receiver_merge_variable_mapping: Optional[Dict[str, str]]

Optional mapping of columns for receiver merge variables.

sender_address_mapping: Optional[Dict[str, str]]

Optional mapping of columns for sender addresses.

sender_merge_variable_mapping: Optional[Dict[str, str]]

Optional mapping of columns for sender merge variables.

invalid_row_count: int

Number of invalid rows found in the file.

formatint32

live: bool

true if this is a live mode resource else false.

notes: List[Note]

Additional notes about the import process.

message: str

A human-readable message describing the note.

type: Literal["truncated_test_file", "skipped_invalid_contacts"]

Type of note attached to the import process.

One of the following:

"truncated_test_file"

"skipped_invalid_contacts"

organization: str

The organization that owns this import.

receiver_status_count: VerificationStatusCount

Count of contact verification statuses.

corrected_count: int

Number of contacts that were corrected during verification.

formatint32

failed_count: int

Number of contacts that failed verification.

formatint32

verified_count: int

Number of contacts that were verified without changes.

formatint32

status: Literal["validating", "completed", "changes_required"]

Status of the mailing list import process.

One of the following:

"validating"

"completed"

"changes_required"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

valid_row_count: int

Number of valid rows processed from the file.

formatint32

description: Optional[str]

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

metadata: Optional[Dict[str, object]]

See the section on Metadata.

report_url: Optional[str]

A temporary URL to download the processing report, available once the import is completed.

formaturi

sender_status_count: Optional[VerificationStatusCount]

Count of contact verification statuses.

corrected_count: int

Number of contacts that were corrected during verification.

formatint32

failed_count: int

Number of contacts that failed verification.

formatint32

verified_count: int

Number of contacts that were verified without changes.

formatint32

List Mailing List Imports

Python

HTTP

TypeScript

Python

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
)
page = client.print_mail.mailing_list_imports.list()
page = page.data[0]
print(page.id)

200 example

{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "mailing_list_import_123",
      "live": false,
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:05:00Z",
      "status": "completed",
      "reportURL": "https://signed-report-url.csv",
      "errors": [],
      "notes": [],
      "validRowCount": 100,
      "invalidRowCount": 0,
      "receiverStatusCount": {
        "verifiedCount": 100,
        "correctedCount": 0,
        "failedCount": 0
      },
      "senderStatusCount": {
        "verifiedCount": 100,
        "correctedCount": 0,
        "failedCount": 0
      },
      "organization": "org_123",
      "file": {
        "fileType": "csv",
        "receiverAddressMapping": {
          "description": "Description",
          "firstName": "First Name",
          "lastName": "Last Name",
          "email": "Email",
          "addressLine1": "Address",
          "addressLine2": "Address Line 2",
          "city": "City",
          "postalOrZip": "Postal Code",
          "provinceOrState": "Province",
          "countryCode": "Country"
        },
        "url": "https://signed.url/import_123.csv"
      }
    }
  ]
}

Returns Examples

200 example

{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "mailing_list_import_123",
      "live": false,
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:05:00Z",
      "status": "completed",
      "reportURL": "https://signed-report-url.csv",
      "errors": [],
      "notes": [],
      "validRowCount": 100,
      "invalidRowCount": 0,
      "receiverStatusCount": {
        "verifiedCount": 100,
        "correctedCount": 0,
        "failedCount": 0
      },
      "senderStatusCount": {
        "verifiedCount": 100,
        "correctedCount": 0,
        "failedCount": 0
      },
      "organization": "org_123",
      "file": {
        "fileType": "csv",
        "receiverAddressMapping": {
          "description": "Description",
          "firstName": "First Name",
          "lastName": "Last Name",
          "email": "Email",
          "addressLine1": "Address",
          "addressLine2": "Address Line 2",
          "city": "City",
          "postalOrZip": "Postal Code",
          "provinceOrState": "Province",
          "countryCode": "Country"
        },
        "url": "https://signed.url/import_123.csv"
      }
    }
  ]
}