API Reference

Print Mail

Mailing Lists

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List Mailing Lists

GET/print-mail/v1/mailing_lists

Retrieve a list of mailing lists.

Returns a paginated list of mailing lists associated with the authenticated organization, filterable by various parameters.

Query ParametersExpand Collapse

limit: optional number

formatint32

search: optional string

You can supply any string to help narrow down the list of resources. For example, if you pass "New York" (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on StructuredSearchQuery for more details.

skip: optional number

formatint32

ReturnsExpand Collapse

data: array of MailingList { id, createdAt, live, 5 more }

id: string

A unique ID prefixed with mailing_list_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

live: boolean

true if this is a live mode resource else false.

status: "creating_contacts" or "removing_contacts" or "counting_recipient_country_codes" or "completed"

Status of the mailing list processing.

One of the following:

"creating_contacts"

"removing_contacts"

"counting_recipient_country_codes"

"completed"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

description: optional string

An optional string describing this resource. Will be visible in the API and the dashboard.

errors: optional array of object { message, type }

A list of processing errors encountered, if any.

message: string

A human-readable message describing the error.

type: "mailing_list_imports_not_found_error" or "download_file_error" or "operational_error" or "internal_service_error"

Type of error encountered during mailing list processing.

One of the following:

"mailing_list_imports_not_found_error"

"download_file_error"

"operational_error"

"internal_service_error"

metadata: optional map[unknown]

See the section on Metadata.

limit: number

formatint32

object: "list"

skip: number

formatint32

totalCount: number

formatint32

List Mailing Lists

HTTP

HTTP

TypeScript

Python

curl https://api.postgrid.com/print-mail/v1/mailing_lists \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"

200 example

{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "mailing_list_123",
      "live": false,
      "description": "Test Mailing List",
      "metadata": {
        "campaign": "launch"
      },
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z",
      "status": "completed",
      "errors": []
    }
  ]
}

Returns Examples

200 example

{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "mailing_list_123",
      "live": false,
      "description": "Test Mailing List",
      "metadata": {
        "campaign": "launch"
      },
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z",
      "status": "completed",
      "errors": []
    }
  ]
}