---
title: "Create Campaign"
method: POST
path: "/print-mail/v1/campaigns"
tags: ["Campaigns"]
---

# Create Campaign

`POST /print-mail/v1/campaigns`

Create a new campaign.

A campaign links a mailing list with a specific mail piece configuration (letter, postcard, cheque, self-mailer, or snap pack)
to send bulk mail. Only one collateral type can be set per campaign.

Upon creation, the campaign enters the `drafting` status while assets are validated.

## Headers

- `idempotency-key` string

## Request body

- CampaignCreate — Parameters for creating a new campaign.
  - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard.
  - `metadata` object — See the section on Metadata.
  - `defaultSenderContact` string — The ID of the default sender contact to use for orders if not specified per recipient.
  - `mailingList` string, required — The ID of the mailing list associated with this campaign.
  - `letter` CampaignLetterFieldsCreate — Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
    - `size` 'us_letter' | 'a4' — Enum representing the supported letter sizes.
    - `color` boolean — Whether to print in color.
    - `doubleSided` boolean — Whether to print on both sides of the paper.
    - `envelope` string — The custom envelope ID or `"standard"`.
    - `envelopeType` 'standard_double_window' | 'flat' — The type of envelope used for the letter.
    - `perforatedPage` 1 — Which page number should be perforated (if any).
    - `addressPlacement` 'top_first_page' | 'insert_blank_page' — Enum representing the placement of the address on the letter.
    - `returnEnvelope` string — ID of a return envelope to include.
    - `attachedPDF` AttachedPDF — Model representing an attached PDF.
      - `file` union, required — The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
        - string, uri
        - string, binary — Represents a raw file upload. Sending the actual file requires a `multipart/form-data` request; in `application/json` request bodies, supply a URL instead.
      - `placement` 'before_template' | 'after_template', required — Enum representing the placement of the attached PDF.
    - `template` string — ID of a template for the letter content. Cannot be used with `pdf`.
    - `pdf` union — A PDF file or URL for the letter content. Cannot be used with `template`.
      - string, uri
      - string, binary — Represents a raw file upload. Sending the actual file requires a `multipart/form-data` request; in `application/json` request bodies, supply a URL instead.
    - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
    - `description` string — An optional description.
    - `metadata` object — Optional key-value metadata.
    - `mergeVariables` object — Default merge variables for the letter.
    - `paper` union
      - 'standard' | 'premium_paper_letter_standard_white_70lb' | 'premium_paper_letter_standard_white_80lb' — Built-in paper IDs for letter products. Actual availability depends on your organization settings.
      - string — Premium paper identifier. `standard` is always accepted. Organizations may also have additional custom `premium_paper_*` IDs beyond the built-in values documented here.
  - `postcard` CampaignPostcardFieldsCreate — Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
    - `size` '6x4' | '9x6' | '11x6' — Enum representing the supported postcard sizes.
    - `frontTemplate` string — ID of the template for the front side. Cannot be used with `pdf`.
    - `backTemplate` string — ID of the template for the back side. Cannot be used with `pdf`.
    - `pdf` union — A 2-page PDF file for the postcard content (front and back). Cannot be used with `frontTemplate`/`backTemplate`.
      - string, uri
      - string, binary — Represents a raw file upload. Sending the actual file requires a `multipart/form-data` request; in `application/json` request bodies, supply a URL instead.
    - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
    - `paper` union
      - 'standard' | 'premium_paper_heavy_1_glossy' | 'premium_paper_postcard_uv_glossy_ss' | 'premium_paper_postcard_uv_glossy_ss_120lb' | 'premium_paper_postcard_satin_ds' — Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
      - string — Premium paper identifier. `standard` is always accepted. Organizations may also have additional custom `premium_paper_*` IDs beyond the built-in values documented here.
    - `description` string — An optional description.
    - `metadata` object — Optional key-value metadata.
    - `mergeVariables` object — Default merge variables for the postcard.
  - `cheque` CampaignChequeFieldsCreate — Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
    - `size` 'us_letter' | 'us_legal' — Enum representing the supported cheque sizes.
    - `bankAccount` string — ID of the bank account to use for the cheque.
    - `currencyCode` 'CAD' | 'USD' — Enum representing the supported currency codes.
    - `memo` string — Memo line text for the cheque.
    - `message` string — Message included on the cheque stub.
    - `logo` string, uri — A publicly accessible URL for the logo to print on the cheque.
    - `letterTemplate` string — ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
    - `letterPDF` union — PDF file for an optional attached letter. Cannot be used with `letterTemplate`.
      - string, uri
      - string, binary — Represents a raw file upload. Sending the actual file requires a `multipart/form-data` request; in `application/json` request bodies, supply a URL instead.
    - `envelope` string — The custom envelope ID or `"standard"`.
    - `returnEnvelope` string — ID of a return envelope to include.
    - `letterSettings` object — Settings for the attached letter (e.g., color printing).
      - `color` boolean — Whether to print the attached letter in color.
    - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
    - `description` string — An optional description.
    - `metadata` object — Optional key-value metadata.
    - `mergeVariables` object — Default merge variables for the cheque.
  - `selfMailer` CampaignSelfMailerFieldsCreate — Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
    - `size` '8.5x11_bifold' | '8.5x11_trifold' | '9.5x16_trifold' — Enum representing the supported self-mailer sizes.
    - `insideTemplate` string — ID of the template for the inside. Cannot be used with `pdf`.
    - `outsideTemplate` string — ID of the template for the outside. Cannot be used with `pdf`.
    - `pdf` union — A 2-page PDF file for the self-mailer content. Cannot be used with `insideTemplate`/`outsideTemplate`.
      - string, uri
      - string, binary — Represents a raw file upload. Sending the actual file requires a `multipart/form-data` request; in `application/json` request bodies, supply a URL instead.
    - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
    - `description` string — An optional description.
    - `metadata` object — Optional key-value metadata.
    - `mergeVariables` object — Default merge variables for the self-mailer.
  - `snapPack` CampaignSnapPackFieldsCreate — Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
    - `size` '8.5x11_bifold_v' — Enum representing the supported snap pack sizes.
    - `insideTemplate` string — ID of the template for the inside. Cannot be used with `pdf`.
    - `outsideTemplate` string — ID of the template for the outside. Cannot be used with `pdf`.
    - `pdf` union — A 2-page PDF file for the snap pack content. Cannot be used with `insideTemplate`/`outsideTemplate`.
      - string, uri
      - string, binary — Represents a raw file upload. Sending the actual file requires a `multipart/form-data` request; in `application/json` request bodies, supply a URL instead.
    - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
    - `description` string — An optional description.
    - `metadata` object — Optional key-value metadata.
    - `mergeVariables` object — Default merge variables for the snap pack.
  - `sendDate` string, date-time — The scheduled date and time for the campaign to be sent.

## Response `201`

The newly created campaign in `drafting` status.

- Campaign — Represents a bulk mail campaign.
  - `id` string, required — A unique ID prefixed with campaign_
  - `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` 'drafting' | 'changes_required' | 'creating_orders' | 'draft' | 'ready' | 'printing' | 'processed_for_delivery', required — Status of the campaign lifecycle.
  - `defaultSenderContact` string — The ID of the default sender contact to use for orders if not specified per recipient.
  - `mailingList` string, required — The ID of the mailing list associated with this campaign.
  - `createdCount` integer, required — The number of orders successfully created for this campaign.
  - `letter` CampaignLetterFields — Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
    - `size` 'us_letter' | 'a4' — Enum representing the supported letter sizes.
    - `color` boolean — Whether to print in color.
    - `doubleSided` boolean — Whether to print on both sides of the paper.
    - `envelope` string — The custom envelope ID or `"standard"`.
    - `envelopeType` 'standard_double_window' | 'flat' — The type of envelope used for the letter.
    - `perforatedPage` 1 — Which page number should be perforated (if any).
    - `addressPlacement` 'top_first_page' | 'insert_blank_page' — Enum representing the placement of the address on the letter.
    - `returnEnvelope` string — ID of a return envelope to include.
    - `attachedPDF` AttachedPDF — Model representing an attached PDF.
      - `file` union, required — The file (multipart form upload) or URL pointing to a PDF for the attached PDF.
        - string, uri
        - string, binary — Represents a raw file upload. Sending the actual file requires a `multipart/form-data` request; in `application/json` request bodies, supply a URL instead.
      - `placement` 'before_template' | 'after_template', required — Enum representing the placement of the attached PDF.
    - `template` string — ID of a template for the letter content. Cannot be used with `pdf`.
    - `uploadedPDF` string, uri — A signed URL to the uploaded PDF, if any.
    - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
    - `description` string — An optional description.
    - `metadata` object — Optional key-value metadata.
    - `mergeVariables` object — Default merge variables for the letter.
    - `paper` union
      - 'standard' | 'premium_paper_letter_standard_white_70lb' | 'premium_paper_letter_standard_white_80lb' — Built-in paper IDs for letter products. Actual availability depends on your organization settings.
      - string — Premium paper identifier. `standard` is always accepted. Organizations may also have additional custom `premium_paper_*` IDs beyond the built-in values documented here.
  - `postcard` CampaignPostcardFields — Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
    - `size` '6x4' | '9x6' | '11x6' — Enum representing the supported postcard sizes.
    - `frontTemplate` string — ID of the template for the front side. Cannot be used with `pdf`.
    - `backTemplate` string — ID of the template for the back side. Cannot be used with `pdf`.
    - `uploadedPDF` string, uri — A signed URL to the uploaded PDF, if any.
    - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
    - `paper` union
      - 'standard' | 'premium_paper_heavy_1_glossy' | 'premium_paper_postcard_uv_glossy_ss' | 'premium_paper_postcard_uv_glossy_ss_120lb' | 'premium_paper_postcard_satin_ds' — Built-in paper IDs for postcard products. Actual availability depends on your organization settings.
      - string — Premium paper identifier. `standard` is always accepted. Organizations may also have additional custom `premium_paper_*` IDs beyond the built-in values documented here.
    - `description` string — An optional description.
    - `metadata` object — Optional key-value metadata.
    - `mergeVariables` object — Default merge variables for the postcard.
  - `cheque` CampaignChequeFields — Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
    - `size` 'us_letter' | 'us_legal' — Enum representing the supported cheque sizes.
    - `bankAccount` string — ID of the bank account to use for the cheque.
    - `currencyCode` 'CAD' | 'USD' — Enum representing the supported currency codes.
    - `memo` string — Memo line text for the cheque.
    - `message` string — Message included on the cheque stub.
    - `logo` string, uri — A publicly accessible URL for the logo to print on the cheque.
    - `letterTemplate` string — ID of a template for an optional attached letter. Cannot be used with `letterPDF`.
    - `letterUploadedPDF` string, uri — A signed URL to the attached letter PDF, if any.
    - `envelope` string — The custom envelope ID or `"standard"`.
    - `returnEnvelope` string — ID of a return envelope to include.
    - `letterSettings` object — Settings for the attached letter (e.g., color printing).
      - `color` boolean — Whether to print the attached letter in color.
    - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
    - `description` string — An optional description.
    - `metadata` object — Optional key-value metadata.
    - `mergeVariables` object — Default merge variables for the cheque.
  - `selfMailer` CampaignSelfMailerFields — Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
    - `size` '8.5x11_bifold' | '8.5x11_trifold' | '9.5x16_trifold' — Enum representing the supported self-mailer sizes.
    - `insideTemplate` string — ID of the template for the inside. Cannot be used with `pdf`.
    - `outsideTemplate` string — ID of the template for the outside. Cannot be used with `pdf`.
    - `uploadedPDF` string, uri — A signed URL to the uploaded PDF, if any.
    - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
    - `description` string — An optional description.
    - `metadata` object — Optional key-value metadata.
    - `mergeVariables` object — Default merge variables for the self-mailer.
  - `snapPack` CampaignSnapPackFields — Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.
    - `size` '8.5x11_bifold_v' — Enum representing the supported snap pack sizes.
    - `insideTemplate` string — ID of the template for the inside. Cannot be used with `pdf`.
    - `outsideTemplate` string — ID of the template for the outside. Cannot be used with `pdf`.
    - `uploadedPDF` string, uri — A signed URL to the uploaded PDF, if any.
    - `mailingClass` 'first_class' | 'standard_class' | 'express' | 'certified' | 'certified_return_receipt' | 'registered' | 'usps_first_class' | 'usps_standard_class' | 'usps_eddm' | 'usps_express_2_day' | 'usps_express_3_day' | 'usps_first_class_certified' | 'usps_first_class_certified_return_receipt' | 'usps_first_class_registered' | 'usps_express_3_day_signature_confirmation' | 'usps_express_3_day_certified' | 'usps_express_3_day_certified_return_receipt' | 'ca_post_lettermail' | 'ca_post_personalized' | 'ca_post_neighbourhood_mail' | 'ups_express_overnight' | 'ups_express_2_day' | 'ups_express_3_day' | 'royal_mail_first_class' | 'royal_mail_second_class' | 'au_post_second_class'
    - `description` string — An optional description.
    - `metadata` object — Optional key-value metadata.
    - `mergeVariables` object — Default merge variables for the snap pack.
  - `orderPreviewURL` string, uri — A temporary URL to preview the first rendered order, available once the campaign status is 'draft' or later.
  - `sendDate` string, date-time — The scheduled date and time for the campaign to be sent.
  - `errors` CampaignError[] — A list of processing errors encountered, if any. Present when status is 'changes_required'.
    - `type` 'processing_error' | 'internal_error', required — Type of error encountered during campaign processing.
    - `message` string, required — A human-readable message describing the error.
  - `reportURL` string, uri — A temporary URL to download the processing report, available once the campaign is in the `ready` status.

## Other responses

- `400` — The newly created campaign in `drafting` status.
- `401` — The newly created campaign in `drafting` status.
- `404` — The newly created campaign in `drafting` status.
- `422` — The newly created campaign in `drafting` status.
- `429` — The newly created campaign in `drafting` status.
- `500` — The newly created campaign in `drafting` status.

---

[API](https://skmtc.net/postgrid/apis/postgrid-address-verification-api.md) · [All operations](https://skmtc.net/postgrid/apis/postgrid-address-verification-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/postgrid/postgrid-address-verification-api/versions/537d2bbc624a/schema)