Skip to main content

Create

POST /v1/campaigns

Creates a campaign.

The thumbnails and proof will not be populated immediately since they are renedered in the background, you should check periodically for them until they are available.

Form Data Parameters

postage_class
string
Required

The postage class of the mail piece, either first_class or standard

size
string
Required

The size of the postcard (height x width), one of:

  • self_mailer_6x18 - self mailer with the size of 6in x 18in
  • self_mailer_12x9 - self mailer with the size of 12in x 9in
  • postcard_6x11 - postcard with the size of 6in x 11in
  • postcard_6x9 - postcard with the size of 6in x 9in
  • postcard_4x6 - postcard with the size of 4in x 6in
  • letter - letter with the size of 8.5in x 11in
designs
array
Required

The designs of the postcard / letter, each can be either a file or an url in any of the following formats:

  • HTML file containing the contents of the mailpiece.
  • Image file matching the size of the mailpiece at 300dpi plus the bleed.
  • PDF file matching the size of the mailpiece plus the bleed.
csv
file
Optional

The CSV file containing the addresses to send to with the following columns (in order): Name,Address,City,State,Zip.

If the Name column is empty the name will default to Current Resident

recipients[][name]
string
Optional

The name of one of the recipients.

recipients[][address]
string
Optional

The address of one of the recipients.

recipients[][city]
string
Optional

The city of one of the recipients.

recipients[][state]
string
Optional

The state of one of the recipients.

recipients[][zip]
string
Optional

The zip of one of the recipients.

sender[name]
file
Required

The sender's name for the return address.

sender[company]
file
Optional

The sender's company name for the return address.

sender[address_line1]
file
Required

The sender's street address.

sender[address_city]
file
Required

The sender's city.

sender[address_state]
file
Required

The sender's state.

sender[address_zip]
file
Required

The sender's zip code in either ZIP5 or ZIP5+ZIP4 format.

send_copy_to_sender
boolean
Optional
Defaults to false

Controls whether or not to send a copy of the mail piece to the sender's address. If true the total number of mailpieces will be increased by 1.

property_filter
string
Optional

The JSON representation of the property filters.

meta_data[][key]
string
Optional

The key of any additional information (metadata) to store with the campaign. For examples check the Making Requests page.

meta_data[][value]
string
Optional

The value of the additional information (metadata) to store with the campaign. For examples check the Making Requests page.

Example Request
curl -X POST https://api.realmailers.com/v1/campaigns \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F "postage_class"="first_class" \
  -F "size"="postcard_4x6" \
  -F "designs[]"="https://www.example.com/front.jpg" \
  -F "designs[]"="https://www.example.com/back.jpg" \
  -F "sender[name]"="JOHN SMITH" \
  -F "sender[address_line1]"="20 W 34TH ST" \
  -F "sender[address_city]"="NEW YORK" \
  -F "sender[address_state]"="NY" \
  -F "sender[address_zip]"="10001"
Response Schema
{
  scheduled_at: Timestamp(ISO8601)
  created_at: Timestamp(ISO8601)
  updated_at: Timestamp(ISO8601)
  sent_at: Timestamp(ISO8601)

  expected_delivery_date: String
  send_copy_to_sender: Boolean
  recipient_count: Number
  property_filter: JSON
  postage_class: String
  template_id: Number
  status: String
  price: String
  proof: URL
  size: Size
  id: Number

  thumbnails: Array(URL)
  designs: Array(URL)

  exposed_addresses: Array({
    address_country: String
    address_line1: String
    address_state: String
    address_city: String
    address_zip: String
    variables: JSON
    company: String
    name:String
  })

  sender: {
    address_country: String
    address_line1: String
    address_state: String
    address_city: String
    address_zip: String
    variables: JSON
    company: String
    name:String
  }

  meta_data: {
    key: String
  }
}