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

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.

Header ParametersExpand Collapse

"idempotency-key": optional string

Body ParametersJSONExpand Collapse

file: string

The CSV file for this import.

formaturi

fileType: FileType

Type of file supported for mailing list imports.

receiverAddressMapping: map[string]

Mapping of columns for receiver addresses.

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.

receiverMergeVariableMapping: optional map[string]

Optional mapping of columns for receiver merge variables.

senderAddressMapping: optional map[string]

Optional mapping of columns for sender addresses. If this is present, then all receivers should have a corresponding sender.

senderMergeVariableMapping: optional map[string]

Optional mapping of columns for sender merge variables.

ReturnsExpand Collapse

MailingListImportResponse = object { id, createdAt, errors, 13 more }

Read-only view of a MailingListImport

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

Create Mailing List Import

HTTP

HTTP

TypeScript

Python

curl https://api.postgrid.com/print-mail/v1/mailing_list_imports \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
    -d '{
          "file": "https://signed-upload-url.csv",
          "fileType": "csv",
          "receiverAddressMapping": {
            "description": "Description",
            "firstName": "First Name",
            "lastName": "Last Name",
            "email": "Email",
            "addressLine1": "Address",
            "city": "City",
            "postalOrZip": "Postal Code",
            "provinceOrState": "State",
            "countryCode": "Country"
          }
        }'

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