---
title: "Submit a Mailing List Job"
method: POST
path: "/print-mail/v1/mailing_lists/{id}/jobs"
tags: ["Mailing Lists"]
---

# Submit a Mailing List Job

`POST /print-mail/v1/mailing_lists/{id}/jobs`

## Request

- Base URL: `https://api.postgrid.com`
- URL: `https://api.postgrid.com/print-mail/v1/mailing_lists/{id}/jobs`
- Auth: API key in header `X-API-Key`

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, required

## Request body

- MailingListJobsRequest: Parameters for bulk operations on mailing list contacts.
  - `addContacts` string[]: List of contact IDs to add to the mailing list. Cannot be used with other operations.
  - `removeContacts` string[]: List of contact IDs to remove from the mailing list. Cannot be used with other operations.
  - `addMailingListImports` string[]: List of mailing list import IDs to add to the mailing list. Cannot be used with other operations.
  - `removeMailingListImports` string[]: List of mailing list import IDs to remove from the mailing list. Cannot be used with other operations.

## Response `200`

The request has succeeded.

- MailingList: Represents a mailing list.
  - `id` string, required: A unique ID prefixed with mailing_list_
  - `description` string: An optional string describing this resource. Will be visible in the API and the dashboard.
  - `metadata` object: See the section on Metadata.
  - `live` boolean, required: `true` if this is a live mode resource else `false`.
  - `createdAt` string, date-time, required: The UTC time at which this resource was created.
  - `updatedAt` string, date-time, required: The UTC time at which this resource was last updated.
  - `status` 'creating_contacts' | 'removing_contacts' | 'counting_recipient_country_codes' | 'completed', required: Status of the mailing list processing.
  - `errors` ProcessError[]: A list of processing errors encountered, if any.
    - `type` 'mailing_list_imports_not_found_error' | 'download_file_error' | 'operational_error' | 'internal_service_error', required: Type of error encountered during mailing list processing.
    - `message` string, required: A human-readable message describing the error.

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `404`: The server cannot find the requested resource.
- `422`: Client error
- `429`: Client error
- `500`: Server error

## Changes

- **2026-05-01** `c8fedcbd705e`: 2 warning, 6 info
  - added the new `internal_server_error` enum value to the `error/type` response property for the response status `500`
  - added the new `rate_limit_exceeded_error` enum value to the `error/type` response property for the response status `429`
  - added `subschema #1, subschema #2` to the response body `anyOf` list for the response status `400`
  - added `subschema #1, subschema #2` to the response body `anyOf` list for the response status `401`
  - …4 more

[Operation history](https://skmtc.dev/postgrid/apis/postgrid-address-verification-api/changes/print-mail/v1/mailing_lists/:id/jobs/post.md)

---

[API](https://skmtc.dev/postgrid/apis/postgrid-address-verification-api.md) - [All operations](https://skmtc.dev/postgrid/apis/postgrid-address-verification-api/llms.txt) - [OpenAPI document](https://skmtc.dev/postgrid/apis/postgrid-address-verification-api/revisions/537d2bbc624a?raw)