Create campaign

POST /v2/campaigns

Creates a campaign. No parameters are strictly required – if none are provided, an empty campaign draft is created.

Some fields become required depending on your choices:

designs are required if the template is an own_design template.
map_targeting is required if the targeting_method is map.
recipients or recipients_csv is required if the targeting_method is recipients.

thumbnails and proof are rendered in the background. Poll the campaign resource until they appear.

Form Data Parameters

Validation and basics

Validation level:

template → require template
content → require template + content
targeting → require template + content + targeting

Campaign name.

The ID or UID of the template to use. See here.

own_list or map.

first_class or standard.

Where to send campaign notifications (e.g. payment receipt and postal induction confirmation email).

The discount code.

Default false. If true, one extra mailpiece is sent to the sender.

Targeting (map)

How many postcards to send in a radius around the targeting center.

Center address to target around.

Coordinates for the center; takes precedence over address.

Filter addresses by type: all or single_family, multi_family.

Filter addresses by bathroom count.

Filter addresses by bedroom count.

Filter addresses by lot size.

Filter addresses by square footage.

Filter addresses by year built.

Filter addresses by last sold price (in dollars).

Filter addresses by last sold year.

Targeting (own list)

You can either provide a properly structured CSV (publicly accessible URL or multipart) or an array of recipients JSON.

CSV with columns in order: Name,Address,City,State,Zip.

If Name is empty it defaults to Current Resident

Recipient name.

Recipient street address.

Recipient city.

Recipient state.

Recipient ZIP.

Template data

Landing page URL (rendered as text or QR depending on the template).

square_feet or acres.

Listing description (commonly on back).

Back title.

Listing address (commonly on front).

Listing label, e.g., JUST LISTED or JUST SOLD.

Square footage.

Annual maintenance cost (USD).

Lot size.

Price (USD).

Annual taxes (USD).

Number of bathrooms (integer or half, e.g., 1, 1.5).

Number of bedrooms (integer or half, e.g., 1, 1.5).

Extra variable key for rendering.

Extra variable value for rendering.

Template photos

Photo file or URL; count must match the template’s photo slots. Images are cropped to the template’s aspect ratio if no crop is provided.

Crop data ( height, width, x, y).

Own design templates

Artwork file or URL. Accepts images or a PDF sized to the mailpiece including bleed.

Crop data ( height, width, x, y).

QR codes

QR code overlays are grouped by side ( front, back). Each side holds an array of QR codes. Positions and sizes are in inches. A template_id is required when sending QR codes, and letter templates may only use the front side.

The URL encoded into the QR code. Scans are tracked through a redirect. A URL without a scheme is assumed to be https.

Position in inches from the top-left corner of the page.

Side length of the QR code in inches.

The URL encoded into the QR code. Scans are tracked through a redirect. A URL without a scheme is assumed to be https.

Position in inches from the top-left corner of the page.

Side length of the QR code in inches.

Metadata

Custom metadata key.

Custom metadata value.

Agent

License number.

Cell phone.

First name.

Last name.

Landline.

Email.

Photo file or URL.

Crop data ( height, width, x, y).

Sender

Street address.

Suite or unit.

State.

Name (usually the company name).

City.

ZIP code.

Logo file or URL.

Crop data ( height, width, x, y).

curl -X POST https://www.realmailers.com/v2/campaigns \
  -H 'Authorization: Bearer YOUR_API_KEY USER_EMAIL' \
  -H 'X-Create-User: true' \
  -F "postage_class"="first_class" \
  -F "template_id"="1" \
  -F "designs[][file]"="https://www.example.com/front.jpg" \
  -F "designs[][file]"="https://www.example.com/back.jpg" \
  -F "company[name]"="JOHN SMITH" \
  -F "company[street_address]"="20 W 34TH ST" \
  -F "company[city]"="NEW YORK" \
  -F "company[state]"="NY" \
  -F "company[zip]"="10001"

{
  template_uid: String
  template_id: Number

  expected_delivery_date: Timestamp(ISO8601)
  scheduled_at: Timestamp(ISO8601)
  created_at: Timestamp(ISO8601)
  updated_at: Timestamp(ISO8601)
  sent_at: Timestamp(ISO8601)

  send_copy_to_sender: Boolean
  notification_email: String
  targeting_method: String
  recipient_count: Number
  discount_code: String
  postage_class: String
  price: Number
  name: String
  id: Number

  thumbnails: Array(URL)
  proof: URL

  status: Enum(
    draft
    in_queue
    mailed
    in_production
    in_transit
    in_local_area
    processed_for_delivery)

  designs: Array({
    thumbnail: URL
    height: Number
    width: Number
    file: URL
    crop: {
      height: Number
      width: Number
      y: Number
      x: Number
    }
  })

  qr_codes: {
    front: Array({
      url: String
      size: Number
      y: Number
      x: Number
    })
    back: Array({
      url: String
      size: Number
      y: Number
      x: Number
    })
  }

  targeting_center: {
    coordinates: Array(Number)
    postcard_count: Number
    address: String
  }

  template_data: {
    landing_page_url: String
    square_footage: Number
    lot_size_type: String
    description: String
    maintenance: Number
    back_title: String
    photos: Array(URL)
    bathrooms: Number
    bedrooms: Number
    lot_size: Number
    address: String
    label: String
    price: Number
    taxes: Number

    variables: {
      key: String
    }
  }

  sender: {
    street_address: String
    state: String
    name: String
    city: String
    zip: String
    logo: URL
  }

  agent: {
    license_number: String
    cell_phone: String
    first_name: String
    last_name: String
    landline: String
    email: String
    photo: URL
  }

  meta_data: {
    key: String
  }
}