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

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).

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 "artworks[][file]"="https://www.example.com/front.jpg" \
  -F "artworks[][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"

{
  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
  template_id: Number
  status: String
  price: Number
  name: String
  id: Number

  thumbnails: Array(URL)
  artworks: Array(URL)
  proof: URL

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

  company: {
    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
  }
}