## 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": []
}
```