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