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.
All CSVs, or comma-separated values, 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. Also note, though this is typically already the default, UTF-8 encoding is required for CSV files.
CSV output will always start with the first row returning the column field names. Then the data itself will follow as CSV records.
Whitespace characters (spaces, pilcrows, and carriage returns) will be trimmed at the start and end of each value to ensure we can process the CSV. For example, " John Doe " will be trimmed to "John Doe". Any whitespace characters inside the value will not be trimmed.
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.
name
: Recipient name must be 40 characters or less- Note the name as it appears in this column will appear in to field in the address block on your mail piece
address_line1
: Must be 64 characters or lessaddress_city
: Must be 200 characters or lessaddress_zip
: Must follow the ZIP format of 12345 or ZIP+4 format of 12345-1234- Lookout! MS Excel and Google Sheets may attempt to drop leading zero.
- Any merge variable data
- When using merge variables that point to a URL, like images or custom fonts, ensure the link is public and can be accessed by Lob
address_line2
: Must be 64 characters or lesscompany
: Must be 40 characters or less
Tagging your mailpieces with metadata can help identify and group your mail sent in any given campaign for easier reporting and attribution. While optional, if you choose to add metadata tags, you cannot add more than 20 Key-Value pairs. Keys can be at most 40 characters and values must be at most 500 characters.
- Recipient metadata: is passed in the CSV and applies to each individual row, or recipient. Recipient metadata is great for tags that are specific to each recipient of mail, like
state:NC
orfirst_name:John
.Recipient metadata can be passed in the CSV one of two ways:- 1.As regular column data: You can use any number of the CSV columns as metadata for your mailpieces such as “name”, “address_line1”, etc. The values for this column for each row should be regular text and not JSON formatted. See our API documentation on how to use more than one column from your CSV file as metadata. Example: If you have a column header in your CSV file called “
recipient
” and the value of the cell for this column in the first row is “john_smith
”, then the metadata that gets attached to your mailpiece for this row will be “recipient: john_smith
” - 2.In multiple columns, prefixed with
metadata_
. For example, your file could havemetadata_key1
andmetadata_key2
columns, and then the values that correspond to each mailpiece in each row.
- This is different than Campaign Metadata
- It is configured on the
POST /v1/campaigns
API call or in the Lob dashboard, on the Campaigns Configure Settings screen in Step 1 at the bottom in the “Add campaign-level metadata tags” section.- Note: Campaign metadata is not configurable within your CSV
- Each individual mailpiece created through the campaign will inherit Campaign metadata. This is ideal for tags you’d like to apply to an entire campaign and can be set in Step 1.
Only 1 of the above methods can be used at once. If you have a column name prefixed with
metadata_
in your CSV file but you’ve also selected a regular column to be used as metadata for your mailpiece, then the the values from the metadata_
prefixed column will NOT be used. We prioritize the manually selected columns to be attached as metadata. If you have not manually selected any column from your CSV file to be used as metadata and the CSV file contains a
metadata_
prefixed column, then the data from the metadata_
prefixed columns will be used as metadata for each mailpiece automatically. Column names prefixed with
metadata_
DO NOT need to be manually selected as metadata. They are automatically applied. If you would like to manually select this column, then simply remove the metadata_
prefix from the column name.
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 requiredAddressColumnMapping
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}}",
"requiredAddressColumnMapping": {
"name": "recipient",
"address_line1": "primary line",
"address_zip": "zip_code",
"address_state": "state",
"address_city": "city"
}
}

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 mergeVariableColumnMapping
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}}",
"mergeVariableColumnMapping": {
"mergeVariable1": "dog",
"mergeVariable2": "cat",
}
}
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.
Last modified 1mo ago