# Mailing Lists ## Create Mailing List **post** `/print-mail/v1/mailing_lists` Create a new mailing list. ### Header Parameters - `"idempotency-key": optional string` ### Body Parameters - `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. ### Returns - `MailingList = object { id, createdAt, live, 5 more }` Represents a mailing list. - `id: string` A unique ID prefixed with mailing_list_ - `createdAt: string` The UTC time at which this resource was created. - `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. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `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. - `"mailing_list_imports_not_found_error"` - `"download_file_error"` - `"operational_error"` - `"internal_service_error"` - `metadata: optional map[unknown]` See the section on Metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### Response ```json { "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": [] } ``` ## 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 Parameters - `limit: optional number` - `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` ### Returns - `data: array of MailingList` - `id: string` A unique ID prefixed with mailing_list_ - `createdAt: string` The UTC time at which this resource was created. - `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. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `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. - `"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` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "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": [] } ] } ``` ## Get Mailing List **get** `/print-mail/v1/mailing_lists/{id}` Retrieve a specific mailing list by its ID. ### Path Parameters - `id: string` ### Returns - `MailingList = object { id, createdAt, live, 5 more }` Represents a mailing list. - `id: string` A unique ID prefixed with mailing_list_ - `createdAt: string` The UTC time at which this resource was created. - `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. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `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. - `"mailing_list_imports_not_found_error"` - `"download_file_error"` - `"operational_error"` - `"internal_service_error"` - `metadata: optional map[unknown]` See the section on Metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "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": [] } ``` ## Update Mailing List **post** `/print-mail/v1/mailing_lists/{id}` Update an existing mailing list. ### Path Parameters - `id: string` ### Body Parameters - `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. ### Returns - `MailingListUpdate = object { description, metadata }` Parameters for updating an existing mailing list. - `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. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### Response ```json { "description": "Test Mailing List", "metadata": { "campaign": "launch" } } ``` ## Delete Mailing List **delete** `/print-mail/v1/mailing_lists/{id}` Delete a mailing list. This permanently deletes the mailing list and its associations. This operation cannot be undone. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with mailing_list_ - `deleted: true` - `true` ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "mailing_list_sqF12lZ1VlBb", "deleted": true } ``` ## Submit a Mailing List Job **post** `/print-mail/v1/mailing_lists/{id}/jobs` Runs a mailing list job. Mailing list jobs allow you to add or remove contacts to your mailing list from mailing list imports or directly with contact IDs. Only one job can be ran at a time and jobs are only able to be ran while the mailing list has a `status` of "completed". Once a job as successfully been kicked off, the mailing list will have a `status` of either `creating_contacts` or `removing_contacts` depending on which job was ran. After the job has finished, the mailing list will go back into the `completed` state where more jobs can be ran. If there are any errors while running a job, the `errors` field on the mailing list will contain a list of error objects which describe the errors. ### Path Parameters - `id: string` ### Body Parameters - `addContacts: optional array of string` List of contact IDs to add to the mailing list. Cannot be used with other operations. - `addMailingListImports: optional array of string` List of mailing list import IDs to add to the mailing list. Cannot be used with other operations. - `removeContacts: optional array of string` List of contact IDs to remove from the mailing list. Cannot be used with other operations. - `removeMailingListImports: optional array of string` List of mailing list import IDs to remove from the mailing list. Cannot be used with other operations. ### Returns - `MailingList = object { id, createdAt, live, 5 more }` Represents a mailing list. - `id: string` A unique ID prefixed with mailing_list_ - `createdAt: string` The UTC time at which this resource was created. - `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. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `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. - `"mailing_list_imports_not_found_error"` - `"download_file_error"` - `"operational_error"` - `"internal_service_error"` - `metadata: optional map[unknown]` See the section on Metadata. ### Example ```http curl https://api.postgrid.com/print-mail/v1/mailing_lists/$ID/jobs \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### Response ```json { "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": [] } ``` ## Domain Types ### Mailing List - `MailingList = object { id, createdAt, live, 5 more }` Represents a mailing list. - `id: string` A unique ID prefixed with mailing_list_ - `createdAt: string` The UTC time at which this resource was created. - `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. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `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. - `"mailing_list_imports_not_found_error"` - `"download_file_error"` - `"operational_error"` - `"internal_service_error"` - `metadata: optional map[unknown]` See the section on Metadata. ### Mailing List Update - `MailingListUpdate = object { description, metadata }` Parameters for updating an existing mailing list. - `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.