Mailing list imports allow users to define recipients and senders of a mailing list by uploading a file defining sender and receiver contact information. These lists of senders and recipients are stored, validated, and used solely in Mailing Lists and will not appear as unique contacts.
To add mailing list imports to a mailing list, they must first be processed and stored with the status completed. Users can check the status of a mailing list import from the List Mailing List Imports or Get Mailing List endpoints. For more information on using mailing list imports in mailing lists, see Mailing Lists.
Mailing list imports allow the flexibility of adding unique senders for each receiver in the mailing list. To define specific senders for each receiver, include sender information in each row of the uploaded file and define sender information column headings in the senderMapping field in the Create Mailing List Imports request.
Currently, PostGrid's API only supports CSV files mailing list imports. Files can be uploaded directly to PostGrid in the request body, or the caller may also provide a URL to the file's download link. Uploaded CSVs should include the address information of each recipient, and the caller must provide the CSV's column mapping to each address field in the receiverMapping field. See Create Mailing List Imports for more information. Download a sample CSV that can be uploaded as a mailing list import here .
Mailing List Import Response
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID prefixed with mailing_list_import_ |
| object | string | always mailing_list_import |
| live | boolean | true if this is a live mode mailing list import else false |
| description | string or undefined | Optional line describing the contact |
| file | object | See File Response |
| invalidRowCount | integer | Number of invalid rows detected in uploaded file |
| validRowCount | number | Number of valid rows detected in uploaded file |
| status | completed, validating, or changes_required | Processing status of uploaded mailing list import |
| reportUrl | string | URL to file including status and errors detected for each row for uploaded mailing list |
| notes | array of objects with a type and message | Notes from processing uploaded mailing list imports file |
| errors | array of objects with a type and message | Errors encountered when processing the uploaded mailing list import file |
| receiverStatusCount | VerificationStatusCount | Status of processed receiver information. See VerifiedStatusCount |
| senderStatusCount | VerificationStatusCount or null | Status of processed sender information. See VerifiedStatusCount |
File Response Object
| Name | Type | Description |
|---|---|---|
| fileType | csv | Type of file uploaded. Currently only csv is supported |
| receiverMapping | object | Mapping of file headers to respective address fields for receiver |
| senderMapping | object or undefined | Mapping of file headers to respective address fields for sender |
| url | string | URL to uploaded mailing list file |
VerifiedStatusCount
| Name | Type | Description |
|---|---|---|
| correctedCount | number | Number of contacts that have been corrected |
| failedCount | number | Number of contacts that have failed verification |
| verifiedCount | number | Number of contacts that have verified |
Processing Errors
Errors that may be encountered when processing mailing list imports are detailed below. Error information and processing status can be retrieved for mailing lists using the Get Mailing List Import and List Mailing List Imports endpoints.
| Type | Description |
|---|---|
invalid_contact_count_error | An odd number of receiving and sending contacts were detected. A receiver contact must be defined for each sender contact |
multiple_countries_error | Multiple countries were detected for contacts. All contacts must share the same country code |
no_valid_contacts_error | No valid contacts were found in the uploaded file |
internal_service_error | Something went wrong on PostGrid's side |