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

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.

Query ParametersExpand Collapse

limit: optional number

formatint32

search: optional string

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 number

formatint32

ReturnsExpand Collapse

data: array of MailingListImportResponse { id, createdAt, errors, 13 more }

id: string

A unique ID prefixed with mailing_list_import_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

errors: array of object { message, type }

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

message: string

A human-readable message describing the error.

type: "no_valid_contacts_error" or "multiple_countries_error" or "invalid_contact_count_error" or "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: object { fileType, receiverAddressMapping, url, 3 more }

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

fileType: FileType

Type of file supported for mailing list imports.

receiverAddressMapping: map[string]

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: string

The signed URL your controller generates.

formaturi

receiverMergeVariableMapping: optional map[string]

Optional mapping of columns for receiver merge variables.

senderAddressMapping: optional map[string]

Optional mapping of columns for sender addresses.

senderMergeVariableMapping: optional map[string]

Optional mapping of columns for sender merge variables.

invalidRowCount: number

Number of invalid rows found in the file.

formatint32

live: boolean

true if this is a live mode resource else false.

notes: array of object { message, type }

Additional notes about the import process.

message: string

A human-readable message describing the note.

type: "truncated_test_file" or "skipped_invalid_contacts"

Type of note attached to the import process.

One of the following:

"truncated_test_file"

"skipped_invalid_contacts"

organization: string

The organization that owns this import.

receiverStatusCount: VerificationStatusCount { correctedCount, failedCount, verifiedCount }

Count of contact verification statuses.

correctedCount: number

Number of contacts that were corrected during verification.

formatint32

failedCount: number

Number of contacts that failed verification.

formatint32

verifiedCount: number

Number of contacts that were verified without changes.

formatint32

status: "validating" or "completed" or "changes_required"

Status of the mailing list import process.

One of the following:

"validating"

"completed"

"changes_required"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

validRowCount: number

Number of valid rows processed from the file.

formatint32

description: optional string

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

metadata: optional map[unknown]

See the section on Metadata.

reportURL: optional string

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

formaturi

senderStatusCount: optional VerificationStatusCount { correctedCount, failedCount, verifiedCount }

Count of contact verification statuses.

correctedCount: number

Number of contacts that were corrected during verification.

formatint32

failedCount: number

Number of contacts that failed verification.

formatint32

verifiedCount: number

Number of contacts that were verified without changes.

formatint32

limit: number

formatint32

object: "list"

skip: number

formatint32

totalCount: number

formatint32

List Mailing List Imports

HTTP

HTTP

TypeScript

Python

curl https://api.postgrid.com/print-mail/v1/mailing_list_imports \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"

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"
      }
    }
  ]
}