API Reference

Print Mail

Mailing List Imports

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create Mailing List Import

print_mail.mailing_list_imports.create(MailingListImportCreateParams**kwargs) -> MailingListImportResponse

POST/print-mail/v1/mailing_list_imports

Create a new mailing list import.

Initiates the import process for a contact list file. The import enters the validating status while contacts are processed and verified.

ParametersExpand Collapse

file: str

The CSV file for this import.

formaturi

file_type: FileType

Type of file supported for mailing list imports.

receiver_address_mapping: Dict[str, str]

Mapping of columns for receiver addresses.

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.

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. If this is present, then all receivers should have a corresponding sender.

sender_merge_variable_mapping: Optional[Dict[str, str]]

Optional mapping of columns for sender merge variables.

idempotency_key: Optional[str]

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

Create Mailing List Import

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
)
mailing_list_import_response = client.print_mail.mailing_list_imports.create(
    file="https://signed-upload-url.csv",
    file_type="csv",
    receiver_address_mapping={
        "description": "Description",
        "firstName": "First Name",
        "lastName": "Last Name",
        "email": "Email",
        "addressLine1": "Address",
        "city": "City",
        "postalOrZip": "Postal Code",
        "provinceOrState": "State",
        "countryCode": "Country",
    },
)
print(mailing_list_import_response.id)

201 example

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

201 example

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