# Mailing Lists ## Create Mailing List `print_mail.mailing_lists.create(MailingListCreateParams**kwargs) -> MailingList` **post** `/print-mail/v1/mailing_lists` Create a new mailing list. ### Parameters - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. - `idempotency_key: Optional[str]` ### Returns - `class MailingList: …` Represents a mailing list. - `id: str` A unique ID prefixed with mailing_list_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: Optional[List[Error]]` A list of processing errors encountered, if any. - `message: str` A human-readable message describing the error. - `type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "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[Dict[str, object]]` See the section on Metadata. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) mailing_list = client.print_mail.mailing_lists.create( description="Test Mailing List", metadata={ "campaign": "launch" }, ) print(mailing_list.id) ``` #### 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 `print_mail.mailing_lists.list(MailingListListParams**kwargs) -> SyncSkipLimit[MailingList]` **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. ### Parameters - `limit: Optional[int]` - `search: Optional[str]` 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[int]` ### Returns - `class MailingList: …` Represents a mailing list. - `id: str` A unique ID prefixed with mailing_list_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: Optional[List[Error]]` A list of processing errors encountered, if any. - `message: str` A human-readable message describing the error. - `type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "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[Dict[str, object]]` See the section on Metadata. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) page = client.print_mail.mailing_lists.list() page = page.data[0] print(page.id) ``` #### 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 `print_mail.mailing_lists.retrieve(strid) -> MailingList` **get** `/print-mail/v1/mailing_lists/{id}` Retrieve a specific mailing list by its ID. ### Parameters - `id: str` ### Returns - `class MailingList: …` Represents a mailing list. - `id: str` A unique ID prefixed with mailing_list_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: Optional[List[Error]]` A list of processing errors encountered, if any. - `message: str` A human-readable message describing the error. - `type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "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[Dict[str, object]]` See the section on Metadata. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) mailing_list = client.print_mail.mailing_lists.retrieve( "id", ) print(mailing_list.id) ``` #### 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 `print_mail.mailing_lists.update(strid, MailingListUpdateParams**kwargs) -> MailingListUpdate` **post** `/print-mail/v1/mailing_lists/{id}` Update an existing mailing list. ### Parameters - `id: str` - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Returns - `class MailingListUpdate: …` Parameters for updating an existing mailing list. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) mailing_list_update = client.print_mail.mailing_lists.update( id="id", description="Updated Mailing List Description", ) print(mailing_list_update.description) ``` #### Response ```json { "description": "Test Mailing List", "metadata": { "campaign": "launch" } } ``` ## Delete Mailing List `print_mail.mailing_lists.delete(strid) -> MailingListDeleteResponse` **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. ### Parameters - `id: str` ### Returns - `class MailingListDeleteResponse: …` - `id: str` A unique ID prefixed with mailing_list_ - `deleted: Literal[true]` - `true` ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) mailing_list = client.print_mail.mailing_lists.delete( "id", ) print(mailing_list.id) ``` #### Response ```json { "id": "mailing_list_sqF12lZ1VlBb", "deleted": true } ``` ## Submit a Mailing List Job `print_mail.mailing_lists.jobs(strid, MailingListJobsParams**kwargs) -> MailingList` **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. ### Parameters - `id: str` - `add_contacts: Optional[SequenceNotStr[str]]` List of contact IDs to add to the mailing list. Cannot be used with other operations. - `add_mailing_list_imports: Optional[SequenceNotStr[str]]` List of mailing list import IDs to add to the mailing list. Cannot be used with other operations. - `remove_contacts: Optional[SequenceNotStr[str]]` List of contact IDs to remove from the mailing list. Cannot be used with other operations. - `remove_mailing_list_imports: Optional[SequenceNotStr[str]]` List of mailing list import IDs to remove from the mailing list. Cannot be used with other operations. ### Returns - `class MailingList: …` Represents a mailing list. - `id: str` A unique ID prefixed with mailing_list_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: Optional[List[Error]]` A list of processing errors encountered, if any. - `message: str` A human-readable message describing the error. - `type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "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[Dict[str, object]]` See the section on Metadata. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) mailing_list = client.print_mail.mailing_lists.jobs( id="id", remove_mailing_list_imports=["mailing_list_import_123", "mailing_list_import_456"], ) print(mailing_list.id) ``` #### 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 - `class MailingList: …` Represents a mailing list. - `id: str` A unique ID prefixed with mailing_list_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `status: Literal["creating_contacts", "removing_contacts", "counting_recipient_country_codes", "completed"]` Status of the mailing list processing. - `"creating_contacts"` - `"removing_contacts"` - `"counting_recipient_country_codes"` - `"completed"` - `updated_at: datetime` The UTC time at which this resource was last updated. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: Optional[List[Error]]` A list of processing errors encountered, if any. - `message: str` A human-readable message describing the error. - `type: Literal["mailing_list_imports_not_found_error", "download_file_error", "operational_error", "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[Dict[str, object]]` See the section on Metadata. ### Mailing List Update - `class MailingListUpdate: …` Parameters for updating an existing mailing list. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata.