File Layouts for Direct Mail exports – Avid

A file layout sets the columns in your Direct Mail file, their names, and their order. Create layouts on Direct Mail > File Layouts. Then pick one on the Review step before you click Generate File.

A column can show your data, an appeal or package setting, fixed text, or several columns merged together.

Use this article when

You need to build or change the columns in a Direct Mail file for your mail vendor.
You want to merge fields, such as first and last name, into one column.
You need to multiply or round a number, such as an ask amount.
You need the columns in a set order.
Generate File shows an invalid source error.

Applies to and prerequisites

Where	Direct Mail in the left nav, then the File Layouts tab.
Plan	The Direct Mail add-on.
Permission	Direct Mail Edit to create, change, copy, or delete a layout. View to open one. Export to generate a file with one.
Data	A constituent data blend. Without one, the column list shows only Direct Mail Settings columns.
Time	About 10 minutes.

Create a file layout

Click Direct Mail in the left nav, then click the File Layouts tab.

You see your layouts, or the message No file layouts have been created yet.
Click Add New File Layout.

The File Layout Editor opens with 10 starter columns. They are Appeal Code, Appeal Name, Account ID, First Name, and Last Name. They also include Address Line 1, Address Line 2, City, State, and Zip Code.
Enter a File Layout Name.

This name appears in the Export File Layout list on the Review step.
Keep, change, or remove the starter columns, and add your own. See Add or edit a column.

The Export Columns heading shows how many columns you have.
Click Save.

You see File Layout Saved Successfully! Click OK. The File Layouts tab opens with your layout in the list.

If you click Cancel with unsaved changes, Avid asks You have unsaved changes. Do you want to save before leaving? Choose Save, Discard, or Stay.

Add or edit a column

In the File Layout Editor, click Add Column. To change a column, open its Actions menu and click Edit Column.

The Add Export Column or Edit Export Column window opens.
Under Source of Data, choose Column Value, Static Value, or Token Merge. Then fill in the field beside it. See Choose a column type.
Enter an Export Column Name. This is the heading in your file.

If you pick a data column and leave the name blank, Avid fills in the column's own name.
Optional: enter a Default Value. Avid writes it when the column is blank.

Numeric data columns show Modifications instead. See Change numbers with modifications.
Click Apply.

The window closes and the column shows in the table. Avid does not save the layout until you click Save.

The Actions menu on a row has two more options:

Copy Column adds a copy under the original, named like Zip Code (Copy). Avid opens it so you can change it.
Delete Column removes the column from the table at once. Avid saves the removal when you click Save.

Choose a column type

Type	Use it to	What you enter	What the file shows
Column Value	Pull a value from your data, or from the appeal and package.	Choose a column from the Select a column list.	The value for each person. A blank value stays blank unless you set a Default Value.
Static Value	Repeat the same text on every row, such as a source code your vendor needs.	Type the text in Enter static value.	That text on every row. A static value has no Default Value.
Token Merge	Join several columns and text in one column, such as `{First Name} {Last Name}`.	Type your text. Add columns from the Columns list. Each column shows in braces.	The pieces joined in order. A blank piece adds nothing. If every piece is blank, the cell is blank.

A Token Merge needs at least one column. Add columns from the Columns list. A name in braces that does not match a column can make the export fail or print as plain text.

Direct Mail Settings columns

These columns come from your appeal and package, not from donor data. They appear under Direct Mail Settings in the Select a column list.

Column	What the file shows
Appeal Code	The package's appeal code. If the package has none, the appeal's Default Appeal Code.
Appeal Name	The appeal's Name.
Carrier Postage	The package's Carrier Postage.
Carrier Size	The package's Carrier Size.
Double Sided	The package's Double Sided setting.
Drop Date	The appeal's Drop Date.
Experiment Version	`Control` or `Treatment` for a package with Split for A/B Test. Blank for other packages.
Finder Number	A running number, one for each row. It starts at the Starting Finder Number from step 1. A blank Starting Finder Number starts at 0.
Letter Version	The package's Letter Version.
Package Code	The package's Pkg Code.
Package Description	The package's Description.
Reply Card Version	The package's Reply Card Version.
Reply Postage	The package's Reply Postage.
Segment Code	A number Avid gives each cell on the Selection grid. Use it to tell cells apart.

People in the Treatment group of an A/B test get the treatment details you entered on the package. This covers every Direct Mail Settings column except Appeal Name, Drop Date, Experiment Version, Finder Number, and Segment Code. A blank treatment detail falls back to the original. A blank treatment description becomes the package description plus (Treatment).

Carrier Postage, Carrier Size, and Reply Postage write the stored code, not the name in the package window. Non-Profit writes non_profit. #10 writes 10. 6 x 9.5 writes 6_9.5.

Double Sided writes the stored yes/no value, not the Yes or No label in the package window.

Data columns

The Select a column list also holds columns from your constituent data blend:

Contact details such as names, addresses, email, phone, and contact custom fields. For each person, the file uses one address, one email, and one phone number. Avid picks the primary one first.
Account ID and account type. Account ID is Avid's ID for the constituent record.
Custom calculations from your blend, listed by name.
Giving fields, such as last gift amount and last gift date. Giving dates are written like Mar 5, 2026.

Change numbers with modifications

A numeric data column, such as a gift amount, shows a Modifications table. It changes the number in your file. Modifications do not apply to Direct Mail Settings columns, Static Value, or Token Merge.

From (Inclusive) and To (Inclusive) set a range. The first range starts at 0. Leave To blank for no upper limit.
Type a number in To to add the next range. Avid starts it just above your number. The trash icon removes a range after the first.
Action is No Changes to Number, Multiply the Number, or Override the Number. Multiply and Override ask for a value.
Multiply and Override also show Format output and Round to nearest. The round choices are $1, $5, $10, $25, $50, and $100.

Avid writes the changed number as text:

Multiply or Override writes two decimal places, such as 63.00.
Round to nearest rounds up to the next multiple of the amount you pick, then writes a whole number. For example, 62 rounded to $5 becomes 65, not 60.
Format output adds a dollar sign and commas, such as $1,250. Without rounding, it applies to Multiply only.
With more than one range, every range writes its result as text. This includes a range set to No Changes to Number, which writes two decimals. A blank number counts as 0 when Avid picks the range.

Example: set one range from 0 with no upper limit. Choose Multiply the Number, enter 1.5, tick Round to nearest, choose $5, and tick Format output. A last gift of $42 becomes $65.

Set the column order

Your file lists columns in the order shown in the Export Columns table.

Clear the Search box. At the bottom of the table, set the page size to ALL so every column shows.
Drag the handle at the left of a row to a new position.

The row moves to its new place in the table.
Click Save.

Sorting by a column heading changes only what you see. If you drag a row after you sort, the sorted order becomes the file order.

Edit, copy, or delete a layout

Edit Layout: on the File Layouts tab, click a layout's name, or open its Actions menu and click Edit Layout.
Copy Layout: Avid saves a copy named like Mail Vendor File (Copy) with all columns, and opens it.
Delete Layout: Avid asks Are you sure you want to delete this file layout? Click Yes, delete. You see Deleted! The layout is no longer available for file exports.

A layout belongs to your organization, and every appeal can use it. When you change a layout, the next file for each appeal that uses it changes. Files you already generated stay the same. Copy a layout before you change one that other appeals use.

If you delete a layout an appeal still uses, choose another layout on Review before you click Generate File.

Choose a layout on the Review step

Open your appeal and go to step 5, Review. The heading reads Step 5: Verify Your Selections.
Under Export File Layout, open the list and choose a layout. The first entry reads Choose a layout...

The list shows your layout's name.
Click Generate File. It stays gray until you choose a layout, and it needs Direct Mail Export.

Avid saves the appeal with your layout choice, builds the file, and shows Success! Your file has been generated. You will also be emailed a link to your file. For security reasons, this link will only work for the next hour. Click Download Your File.

An appeal uses one layout at a time. To use another, choose it and click Generate File again.

Fix a layout error

What you see	Cause	Fix
`Please enter a file layout name.`	The layout has no name.	Enter a File Layout Name, then click Save.
`Please add at least one column.`	The layout has no columns.	Click Add Column.
`Please enter a column name to use in the export.`	The Export Column Name is blank.	Enter a name, then click Apply.
`This column name is already in use. Please choose a different name.`	Another column in the layout has the same name. Avid ignores capital letters when it compares names.	Give each column a different Export Column Name.
`Please select a source column.`, `Please enter a static value.`, `Please enter a token merge pattern.`, or `Please insert at least one column from Variables.`	The source for the type you chose is empty. A Token Merge needs at least one column.	Choose a column, type the text, or add a column from the Columns list.
`Please enter values for all modifications.`	A range uses Multiply the Number or Override the Number but has no value.	Enter the value, or choose No Changes to Number.
`Modification ranges cannot overlap.`	Two ranges share some of the same numbers.	Change the To values so that each range starts above the one before it.
A red notification says `Error saving file layout. Please try again.`	Avid could not save the layout.	Click Save again. If the message returns, contact LockStep Support.
An Error! dialog says `File layout column "COLUMN NAME" has an invalid source. Choose a valid data column and try the export again.`	One column points to a source Avid cannot read. `COLUMN NAME` is that column's Export Column Name. It reads `unknown` if the column has no name.	Open the layout and click Edit Column on that column. Under Source of Data, choose Column Value and pick the column from the list again. Click Apply, click Save, then click Generate File again. If the column is not in the list, delete it or choose a different one.
An Error! dialog says `An error occurred while processing the file. Please submit a support ticket for further assistance.`	Avid could not build the file. A layout column is one possible cause, such as a token that does not match a column.	Check the columns you changed most recently. If the message returns, contact LockStep Support.

Notes and limits

The first row of the file holds your Export Column Name values exactly as you typed them.
The file is a CSV that Excel opens correctly.
Give each column a clearly different name. Names that differ only in spacing or punctuation can collide when Avid builds the file.
Avid keeps the last file you generated for each appeal. Use Download on the Actions menu of Direct Mail > Appeals to get it again.

When to contact LockStep Support

Contact LockStep Support if a fix above does not work, or if the file still fails. Include:

The file layout name and the appeal name.
The exact message. Copy it from the Error! dialog.
The Export Column Name of any column the message names.
What you changed in the layout most recently.
The date, time, and time zone.

Next steps

For agency partners

Token Merge keys. Avid stores a token merge as a pattern of column keys, such as {contacts.first_name}. The table shows column names instead. Typing a column name in braces works when it matches a column name exactly.
Appeal code placeholders. In an appeal code, Avid replaces [C] with the Account ID and [S] with the segment code. In the Default Appeal Code, Avid replaces [P] with the package code. This applies to packages with no appeal code of their own.
Internal column names. Avid builds each column under an internal name. The name is the Export Column Name in lowercase, with underscores for spaces and no other punctuation. The header row in the file keeps your names as typed.
Contact custom fields. Avid saves a column whose key starts with contacts.custom with its source set to contact.