Send Campaign

POST/print-mail/v1/campaigns/{id}/send

Send a campaign for processing.

This action transitions a campaign from the draft status to creating_orders. You can optionally specify a future sendDate. Once sent, the campaign cannot be updated.

Path ParametersExpand Collapse

id: string

Body ParametersJSONExpand Collapse

sendDate: optional string or string

The date and time the campaign should be sent. Must be in the future. If omitted, defaults to the earliest possible processing date.

One of the following:

string

ReturnsExpand Collapse

Campaign object { id, createdAt, createdCount, 16 more }

Represents a bulk mail campaign.

id: string

A unique ID prefixed with campaign_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

createdCount: number

The number of orders successfully created for this campaign.

formatint32

live: boolean

true if this is a live mode resource else false.

mailingList: string

The ID of the mailing list associated with this campaign.

status: "drafting" or "changes_required" or "creating_orders" or 4 more

Status of the campaign lifecycle.

One of the following:

"drafting"

"changes_required"

"creating_orders"

"draft"

"ready"

"printing"

"processed_for_delivery"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

cheque: optional object { bankAccount, currencyCode, description, 12 more }

Inline cheque configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

bankAccount: optional string

ID of the bank account to use for the cheque.

currencyCode: optional "CAD" or "USD"

Enum representing the supported currency codes.

One of the following:

"CAD"

"USD"

description: optional string

An optional description.

envelope: optional string

The custom envelope ID or "standard".

letterSettings: optional object { color }

Settings for the attached letter (e.g., color printing).

color: optional boolean

Whether to print the attached letter in color.

letterTemplate: optional string

ID of a template for an optional attached letter. Cannot be used with letterPDF.

letterUploadedPDF: optional string

A signed URL to the attached letter PDF, if any.

formaturi

logo: optional string

A publicly accessible URL for the logo to print on the cheque.

formaturi

mailingClass: optional "first_class" or "standard_class" or "express" or 23 more

Mailing class for the cheque.

One of the following:

"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"

memo: optional string

Memo line text for the cheque.

mergeVariables: optional map[unknown]

Default merge variables for the cheque.

message: optional string

Message included on the cheque stub.

metadata: optional map[string]

Optional key-value metadata.

returnEnvelope: optional string

ID of a return envelope to include.

size: optional ChequeSize

Enum representing the supported cheque sizes.

One of the following:

"us_letter"

"us_legal"

defaultSenderContact: optional string

The ID of the default sender contact to use for orders if not specified per recipient.

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. Present when status is ‘changes_required’.

message: string

A human-readable message describing the error.

type: "processing_error" or "internal_error"

Type of error encountered during campaign processing.

One of the following:

"processing_error"

"internal_error"

letter: optional object { addressPlacement, attachedPDF, color, 13 more }

Inline letter configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

addressPlacement: optional AddressPlacement

Enum representing the placement of the address on the letter.

One of the following:

"top_first_page"

"insert_blank_page"

attachedPDF: optional AttachedPdf { file, placement }

Model representing an attached PDF.

file: string

The file (multipart form upload) or URL pointing to a PDF for the attached PDF.

formaturi

placement: "before_template" or "after_template"

Enum representing the placement of the attached PDF.

One of the following:

"before_template"

"after_template"

color: optional boolean

Whether to print in color.

description: optional string

An optional description.

doubleSided: optional boolean

Whether to print on both sides of the paper.

envelope: optional string

The custom envelope ID or "standard".

envelopeType: optional "standard_double_window" or "flat"

The type of envelope used for the letter.

One of the following:

"standard_double_window"

"flat"

mailingClass: optional "first_class" or "standard_class" or "express" or 23 more

Mailing class for the letter.

One of the following:

"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"

mergeVariables: optional map[unknown]

Default merge variables for the letter.

metadata: optional map[string]

Optional key-value metadata.

paper: optional "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb" or string

Premium paper selection (“standard” or a premium paper ID). If omitted, org default is used when configured; otherwise “standard”.

One of the following:

LetterBuiltInPremiumPaperID = "standard" or "premium_paper_letter_standard_white_70lb" or "premium_paper_letter_standard_white_80lb"

Built-in paper IDs for letter products. Actual availability depends on your organization settings.

One of the following:

"standard"

"premium_paper_letter_standard_white_70lb"

"premium_paper_letter_standard_white_80lb"

PremiumPaperID = string

Premium paper identifier.

standard is always accepted. Organizations may also have additional custom premium_paper_* IDs beyond the built-in values documented here.

perforatedPage: optional 1

Which page number should be perforated (if any).

returnEnvelope: optional string

ID of a return envelope to include.

size: optional LetterSize

Enum representing the supported letter sizes.

One of the following:

"us_letter"

"a4"

template: optional string

ID of a template for the letter content. Cannot be used with pdf.

uploadedPDF: optional string

A signed URL to the uploaded PDF, if any.

formaturi

metadata: optional map[unknown]

See the section on Metadata.

orderPreviewURL: optional string

A temporary URL to preview the first rendered order, available once the campaign status is ‘draft’ or later.

formaturi

postcard: optional object { backTemplate, description, frontTemplate, 6 more }

Inline postcard configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

backTemplate: optional string

ID of the template for the back side. Cannot be used with pdf.

description: optional string

An optional description.

frontTemplate: optional string

ID of the template for the front side. Cannot be used with pdf.

mailingClass: optional "first_class" or "standard_class" or "express" or 23 more

Mailing class for the postcard.

One of the following:

"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"

mergeVariables: optional map[unknown]

Default merge variables for the postcard.

metadata: optional map[string]

Optional key-value metadata.

paper: optional "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more or string

Premium paper selection (“standard” or a premium paper ID). If omitted, org default is used when configured; otherwise “standard”.

One of the following:

PostcardBuiltInPremiumPaperID = "standard" or "premium_paper_heavy_1_glossy" or "premium_paper_postcard_uv_glossy_ss" or 2 more

Built-in paper IDs for postcard products. Actual availability depends on your organization settings.

One of the following:

"standard"

"premium_paper_heavy_1_glossy"

"premium_paper_postcard_uv_glossy_ss"

"premium_paper_postcard_uv_glossy_ss_120lb"

"premium_paper_postcard_satin_ds"

PremiumPaperID = string

Premium paper identifier.

standard is always accepted. Organizations may also have additional custom premium_paper_* IDs beyond the built-in values documented here.

size: optional "6x4" or "9x6" or "11x6"

Enum representing the supported postcard sizes.

One of the following:

"6x4"

"9x6"

"11x6"

uploadedPDF: optional string

A signed URL to the uploaded PDF, if any.

formaturi

reportURL: optional string

A temporary URL to download the processing report, available once the campaign is in the ready status.

formaturi

selfMailer: optional object { description, insideTemplate, mailingClass, 5 more }

Inline self-mailer configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

description: optional string

An optional description.

insideTemplate: optional string

ID of the template for the inside. Cannot be used with pdf.

mailingClass: optional "first_class" or "standard_class" or "express" or 23 more

Mailing class for the self-mailer.

One of the following:

"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"

mergeVariables: optional map[unknown]

Default merge variables for the self-mailer.

metadata: optional map[string]

Optional key-value metadata.

outsideTemplate: optional string

ID of the template for the outside. Cannot be used with pdf.

size: optional "8.5x11_bifold" or "8.5x11_trifold" or "9.5x16_trifold"

Enum representing the supported self-mailer sizes.

One of the following:

"8.5x11_bifold"

"8.5x11_trifold"

"9.5x16_trifold"

uploadedPDF: optional string

A signed URL to the uploaded PDF, if any.

formaturi

sendDate: optional string

The scheduled date and time for the campaign to be sent.

formatdate-time

snapPack: optional object { description, insideTemplate, mailingClass, 5 more }

Inline snap pack configuration for a campaign. All fields are optional since campaigns may be in a partial state during drafting.

description: optional string

An optional description.

insideTemplate: optional string

ID of the template for the inside. Cannot be used with pdf.

mailingClass: optional "first_class" or "standard_class" or "express" or 23 more

Mailing class for the snap pack.

One of the following:

"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"

mergeVariables: optional map[unknown]

Default merge variables for the snap pack.

metadata: optional map[string]

Optional key-value metadata.

outsideTemplate: optional string

ID of the template for the outside. Cannot be used with pdf.

size: optional "8.5x11_bifold_v"

Enum representing the supported snap pack sizes.

uploadedPDF: optional string

A signed URL to the uploaded PDF, if any.

formaturi

Send Campaign

curl https://api.postgrid.com/print-mail/v1/campaigns/$ID/send \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
    -d '{}'

{
  "id": "campaign_sqF12lZ1VlBb",
  "createdAt": "2019-12-27T18:11:19.117Z",
  "createdCount": 0,
  "live": true,
  "mailingList": "mailingList",
  "status": "drafting",
  "updatedAt": "2019-12-27T18:11:19.117Z",
  "cheque": {
    "bankAccount": "bankAccount",
    "currencyCode": "CAD",
    "description": "description",
    "envelope": "envelope",
    "letterSettings": {
      "color": true
    },
    "letterTemplate": "letterTemplate",
    "letterUploadedPDF": "https://example.com",
    "logo": "https://example.com",
    "mailingClass": "first_class",
    "memo": "memo",
    "mergeVariables": {
      "foo": "bar"
    },
    "message": "message",
    "metadata": {
      "foo": "string"
    },
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter"
  },
  "defaultSenderContact": "defaultSenderContact",
  "description": "description",
  "errors": [
    {
      "message": "message",
      "type": "processing_error"
    }
  ],
  "letter": {
    "addressPlacement": "top_first_page",
    "attachedPDF": {
      "file": "https://example.com",
      "placement": "before_template"
    },
    "color": true,
    "description": "description",
    "doubleSided": true,
    "envelope": "envelope",
    "envelopeType": "standard_double_window",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "perforatedPage": 1,
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter",
    "template": "template",
    "uploadedPDF": "https://example.com"
  },
  "metadata": {
    "foo": "bar"
  },
  "orderPreviewURL": "https://example.com",
  "postcard": {
    "backTemplate": "backTemplate",
    "description": "description",
    "frontTemplate": "frontTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "size": "6x4",
    "uploadedPDF": "https://example.com"
  },
  "reportURL": "https://example.com",
  "selfMailer": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold",
    "uploadedPDF": "https://example.com"
  },
  "sendDate": "2019-12-27T18:11:19.117Z",
  "snapPack": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold_v",
    "uploadedPDF": "https://example.com"
  }
}

Returns Examples

{
  "id": "campaign_sqF12lZ1VlBb",
  "createdAt": "2019-12-27T18:11:19.117Z",
  "createdCount": 0,
  "live": true,
  "mailingList": "mailingList",
  "status": "drafting",
  "updatedAt": "2019-12-27T18:11:19.117Z",
  "cheque": {
    "bankAccount": "bankAccount",
    "currencyCode": "CAD",
    "description": "description",
    "envelope": "envelope",
    "letterSettings": {
      "color": true
    },
    "letterTemplate": "letterTemplate",
    "letterUploadedPDF": "https://example.com",
    "logo": "https://example.com",
    "mailingClass": "first_class",
    "memo": "memo",
    "mergeVariables": {
      "foo": "bar"
    },
    "message": "message",
    "metadata": {
      "foo": "string"
    },
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter"
  },
  "defaultSenderContact": "defaultSenderContact",
  "description": "description",
  "errors": [
    {
      "message": "message",
      "type": "processing_error"
    }
  ],
  "letter": {
    "addressPlacement": "top_first_page",
    "attachedPDF": {
      "file": "https://example.com",
      "placement": "before_template"
    },
    "color": true,
    "description": "description",
    "doubleSided": true,
    "envelope": "envelope",
    "envelopeType": "standard_double_window",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "perforatedPage": 1,
    "returnEnvelope": "returnEnvelope",
    "size": "us_letter",
    "template": "template",
    "uploadedPDF": "https://example.com"
  },
  "metadata": {
    "foo": "bar"
  },
  "orderPreviewURL": "https://example.com",
  "postcard": {
    "backTemplate": "backTemplate",
    "description": "description",
    "frontTemplate": "frontTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "paper": "standard",
    "size": "6x4",
    "uploadedPDF": "https://example.com"
  },
  "reportURL": "https://example.com",
  "selfMailer": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold",
    "uploadedPDF": "https://example.com"
  },
  "sendDate": "2019-12-27T18:11:19.117Z",
  "snapPack": {
    "description": "description",
    "insideTemplate": "insideTemplate",
    "mailingClass": "first_class",
    "mergeVariables": {
      "foo": "bar"
    },
    "metadata": {
      "foo": "string"
    },
    "outsideTemplate": "outsideTemplate",
    "size": "8.5x11_bifold_v",
    "uploadedPDF": "https://example.com"
  }
}