Lob Help Center

Campaign audience guide


The foundation of any effective marketing campaign strategy is to have a specific and defined audience of contacts. Creating a targeted audience list by utilizing important customer data, such as past purchase history, product engagement or site interaction, or loyalty or subscription data, can be an effective way to test your marketing performance. 

As you export your campaign audience list to bring it into Lob, keep the following guidelines in mind when using the Campaigns feature, either in the Dashboard or the API

Step 1: Build your audience file

All CSVs are required to contain recipient address data. If you are using HTML templates with merge variables for your creative, your CSV must also include merge variable data.

Files must have a .csv filename extension and must not exceed 5GB

You are not required to name your columns to Lob's naming convention, as you can easily map them in the Dashboard. However, any fields that use Lob's naming convention will be automatically mapped. The Lob naming convention for CSV column headers are indicated below in bold

Required columns

  • name: Recipient name must be 40 characters or less
  • address_line1: Must be 64 characters or less
  • address_city: Must be 200 characters or less
  • address_state: 2-letter US state short-name code (e.g. CA for California)
  • address_zip: Must follow the ZIP format of 12345 or ZIP+4 format of 12345-1234
  • Any merge variable data
    • When using merge variables that point to a URL, like a variable image, ensure the link is public and can be accessed by Lob

Optional columns

  • address_line2: Must be 64 characters or less
  • company: Must be 40 characters or less
  • address_country: Must be in ISO 3166-1 alpha-2 convention (e.g. US for United States of America )
  • metadata or metadata_: Metadata must not contain more than 20 key-value pairs. Keys can be at most 40 characters and valuesmust be at most 500 characters. 
    • Mailpiece metadata: is passed in the CSV and applies to each individual row, or recipient. Mailpiece metadata is great for tags that are specific to each recipient, like state:NC or first_name:John

      Mailpiece metadata can be passed in the CSV one of two ways:

      1. As key-value pairs: Put your metadata in a single column named metadata or add the metadata field in your column mapping (See Step 2). The metadata keys and values must be formatted with two double quotes on each side of the keys and values, and with a comma in between each key-value pair.

        name address_line1 address_city address_state address_zip metadata
        John Smith 200 First St #1 Charlotte NC 28209 {“”key1””:””value1””,“”key2””:””value2””}
      2. In multiple columns, prefixed with metadata_. For example, your file could have metadata_state and metadata_firstname columns, and then the values that correspond to each mailpiece in each row.

        name address_line1 address_city address_state address_zip metadata_key1 metadata_key2
        John Smith 200 First St #1 Charlotte NC 28209 value1 value2

    • Not to be confused with Campaign metadata
      • It is configured on the POST /v1/campaignsAPI call or in the dashboard, on the Campaigns Configure Settings screen at the bottom “Add Tags” section. 
        • Campaign metadata is not configured within your CSV
      • Each individual mailpiece created through the campaign will inherit Campaign metadata. This is great for tags you’d like to apply to an entire campaign and can be set in Step 1. 

Step 2: Map your data to your campaign


Upload your CSV file in Campaigns > Step 2: Add Audience. 

Campaigns API

When sending the POST or PATCH request to the /v1/uploads endpoint, you will need to pass in an array of key-value pairs in the columnMapping property. The keys will be the Lob-required field names, and the values will be the column headers in your CSV. 

Example: POST /v1/uploads

   "campaignId": "{{campaign_id}}",
   "columnMapping": {
       "name": "recipient",
       "address_line1": "primary line",
       "address_zip": "zip_code",
       "address_state": "state",
       "address_city": "city"

Step 3: Map merge variable data (if applicable)


Merge variable data (if applicable) is mapped in Campaigns > Step 3: Choose Creative 

Campaigns API

This can either be configured in Step 2 during the initial POST request or updated using a PATCH.  When sending the request, pass in an array of key-value pairs in the columnMapping property. The keys will be the merge variable names defined in your HTML template and the values will be the column headers in your CSV. 

Example: POST /v1/uploads

   "campaignId": "{{campaign_id}}",
   "columnMapping": {
       "mergeVariable1": "dog",
       "mergeVariable2": "cat",

Troubleshooting common issues 

When uploading your CSV audience file, ensure the filetype is correct. 

  • To ensure compatibility, ensure your CSV is UTF-8 encoded (Unicode)
  • Your file should have an extension that ends in .csv
  • In rare cases, your file type might appear to have a .csv extension but actually be saved in a different, unsupported format. 

Avoid opening up your audience CSV in a spreadsheet program like Excel if possible. 

  • If you do need to open the file, avoid saving the file or making updates. These programs will automatically make changes to your file when saved, which could potentially cause issues on upload. 
  • Stripped leading zeros for zip codes are the most common issue. For example, the program turns Zip Code 07751 into 7751. Zip codes that begin with “0” are in the Northeast, specifically CT, MA, ME, VT, NH, NJ, RI.

Avoid line breaks in your audience file to prevent your CSV from being rejected. 

  • If you need line breaks as part of a merge variable, consider using two merge variables at this time. 

Avoid commas in your audience file to prevent your CSV from being rejected. 

  • Check if your CSV file has commas that are separating values that belong in unique columns per the specifications above.
Was this article helpful?