API Reference

Print Mail

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Mailing List Imports

The mailing list imports API enables you to import contact lists from files and validate them for use in campaigns.

Create Mailing List Import

POST/print-mail/v1/mailing_list_imports

List Mailing List Imports

GET/print-mail/v1/mailing_list_imports

Update Mailing List Import

POST/print-mail/v1/mailing_list_imports/{id}

Get Mailing List Import

GET/print-mail/v1/mailing_list_imports/{id}

Delete Mailing List Import

DELETE/print-mail/v1/mailing_list_imports/{id}

ModelsExpand Collapse

FileType = "csv"

Type of file supported for mailing list imports.

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

VerificationStatusCount = object { 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