Skip to main content

Direct Mail Select tool: how it works, limits and troubleshooting

Updated

The select tool is the Appeals wizard on the Direct Mail page. It selects people from your constituent data blend, sorts them into a grid, and builds a mailing file. Many teams call the mailing list it builds a select.

Counts change when your blend refreshes and when you change a setting. Use this article to learn what the tool selects and what each setting does. It also lists what to check when a select looks wrong.

Use this article when

  • You want to know what the select tool selects from, and why a count changed.
  • You need to know what a Selection Limitation does, such as Select only one record per household.
  • A count on the Review step, or the number of rows in your file, looks wrong.
  • You want to confirm that a drop (one mailing) reached Matchback.
  • The Direct Mail item is missing from the left nav, or Generate File is gray.

Applies to and prerequisites

Where Direct Mail in the left nav. The page has three tabs: Appeals, File Layouts, and Audiences. The select tool is the Appeals tab.
Plan The Direct Mail add-on, or an active Direct Mail trial. Without it, Avid hides Direct Mail in the left nav. A Direct Mail address opens an upgrade page.
Permission Direct Mail View opens appeals and layouts. Edit creates and changes appeals, packages, and file layouts. Export turns on Generate File. An admin sets these under Settings > Team. See How Do I Manage User Permissions and Access Levels in Avid?
Data A constituent data blend. The select tool reads only this blend.

How the select tool works

This section explains what the tool selects from and when its numbers change. For the click-by-click steps, see Create a matchback-ready appeal in Direct Mail.

What the tool selects from

The select tool selects only people who are in your constituent data blend. The blend is the donor-level data that Avid builds from your connected systems and uploaded files. For a field list, see the Constituent Data Blend Glossary.

A person who is not in the blend cannot be in a select. When the blend refreshes, people can move between grid cells, and counts change.

To see when your blend last refreshed, open Settings > Data Blends and check Last Refreshed. You need Connections access to see the Data Blends tab.

Direct Mail Select is also the name of a data category for uploaded files that list who received a mailing. The select tool works without it. See How to Load Direct Mail Data into Avid for that category.

When Avid counts people

The wizard counts people at three points. The numbers do not always match.

  • Audience step (step 2). When you click Next Step, Avid recounts the grid. The grid counts the people your audiences match in each cell. It does not apply your Selection Limitations.
  • Selection step (step 4). The grid shows the counts saved on the Audience step. They stay the same until you save the Audience step again or change an axis.
  • Review step (step 5). Avid recounts each time you open the step, and it applies your Selection Limitations. Use the Audience Size column to plan quantities. The page title reads Verify Your Selections.

The Review step can show fewer people than the grid. With de-duplicate on, an info icon beside Total Selected (All Audiences) on the Selection step reminds you of this.

Avid builds the file from your data at the moment you click Generate File.

What happens to grid cells when your data changes

A cell is one combination of an X, a Y, and a Z value. You color a cell with a package to include its people.

  • Avid adds a cell for each new value in your data. It does this when you open an appeal or save the Audience step. A new cell has no package.
  • Avid removes a cell when one of its values no longer exists in your data. The cell loses its package.
  • People in a cell with no package color are not in the file.

After a refresh, open the Selection step and look for cells with no color.

What each Selection Limitation does

You set these on step 1 (Information), under Selection Limitations. They apply on the Review step and in your file. They do not apply to the grid counts.

Select only one record per household

Off by default. Avid treats one constituent record, shown as one Account ID in your file, as one household. It keeps one person from each record.

  • Avid keeps the person your data marks as the primary contact. If none is marked, it keeps the person with the highest contact ID.
  • It does not merge separate constituent records. If your CRM stores spouses as two records, both stay.
  • To catch pairs that share a last name and address, also turn on De-duplicate records based upon address.

Select primary addresses only

Off by default. Avid reads one address for each person.

  • With this off, Avid prefers the primary address. If a person has none, it uses another address that has a street line.
  • With this on, Avid reads only addresses that your data marks as primary. An address with no primary flag counts as primary.

With this on, a person who has no primary address stays in the file. The address columns for that person are blank.

Exclude deceased

On by default. Avid leaves out people your data marks as deceased. People with no deceased flag stay in. Turn it off to include everyone.

De-duplicate records based upon address

Off by default. When you turn it on, De-dupe Priority appears. It starts on Prioritize based upon Largest Giving Amount.

  • Avid builds an address key for each person. The key joins these parts in lowercase:
    • Last name
    • Street line (Address Line 1)
    • City
    • State
    • The first five digits of the ZIP code
  • People with the same key count as one. Avid keeps one of them.
  • Matching is exact. Ave does not match Avenue. When the street, city, and state are present, people with different last names never match.
  • Avid keeps the person with the higher priority. Prioritize based upon Largest Giving Amount favors the person with the largest single gift. Prioritize based upon Last Giving Date favors the person who gave most recently.
  • If priority ties, Avid keeps the primary contact, then the lowest Account ID.

If the street, city, or state is missing, Avid can group those people as one address. That can include people with different last names.

Axes and custom calculations

An axis is a way to group people, such as Lifetime Gifts or Months Since Last Gift. You pick three on step 1: X Axis, Y Axis, and Z Axis. Together they make the grid on the Selection step.

  • A new appeal starts with these axes: Lifetime Gifts (X), Last Gift Amount (Y), and Months Since Last Gift (Z).
  • You must pick all three, and each axis can be used once.
  • Avid offers 11 built-in axes. It also lists each custom calculation from your constituent data blend, by name.
  • Avid leaves out any person who has no value for one of the three axes. Those people cannot appear in the Review counts or the file.

Avid groups some custom calculations into ranges for you. Whole numbers become gift-count ranges. Dates become months-since ranges. Some decimal numbers become revenue ranges. Avid uses text calculations exactly as written, with one cell per value.

To control your own groups, change the calculation so that it returns text, such as High, Mid, and Low. Then choose it again on step 1.

Changing an axis clears your package selections. Avid removes every package selection for the appeal when an axis changes. Choose your axes before you assign packages.

The A/B split is fixed at 50/50

Tick Split for A/B Test on a package to run a test. Avid puts each person in a Control group or a Treatment group. Each group gets about half of the people. You cannot change the percentages.

  • Avid picks the group from the person's Account ID and the appeal. The same person stays in the same group each time you generate the file for that appeal.
  • The Treatment group gets the treatment details from the package. A blank treatment detail falls back to the package's original detail.
  • Avid does not offer other splits today. Tell LockStep Support what you need so they can log the request. You can also split the downloaded file yourself.

Confirm a drop registered for Matchback

Matchback compares gifts to the people you mailed. On the Review step, tick Include the exported data in Direct Mail and Matchback reporting. Avid then saves who you mailed and registers it for Matchback.

The box starts unticked every time you open the appeal. Tick Include the exported data in Direct Mail and Matchback reporting again each time you generate a file you want in Matchback.

That registration can fail without a message. You still see the Success! banner and you still get your file. To check that the drop registered:

  1. Open Settings > Files and search for your appeal's name. You need Connections access to see the Files tab.

    You see a file named like Spring Appeal (ID #123) with (Upload) beside it. The number after ID # is the number at the end of the appeal's web address.

  2. Check the Status column.

    It shows Ready.

  3. Check the Data Set column in the same row.

    It shows a data set named for your appeal.

  4. Run the Matchback report. See Run a Matchback report.

    Your appeal appears in the report.

If the file or the data set is missing:

  • Generate the file again with the box ticked. Avid asks Your previous reporting export will be overwritten. Do you want to continue? if an earlier reporting file exists. Click Yes, continue.
  • If it is still missing, contact LockStep Support. A missing file upload connection can stop the registration.

Fix problems with a select

What you see Likely cause What to do
Direct Mail is missing from the left nav, or a Direct Mail address opens an upgrade page. Your plan does not include the Direct Mail add-on, or your user lacks Direct Mail View. Ask an admin to check your Direct Mail permissions. If they are on, contact LockStep Support to confirm the add-on is active.
A button is hidden or gray. A tooltip says You do not have privileges to complete this action. Your user lacks Direct Mail Edit or Export. Ask an admin to turn on the permission you need. Edit covers appeals, packages, and layouts. Export covers Generate File.
Next Step is gray, or a red message appears under a field, such as Please select an X axis. A required item is missing. Step 1 needs a name, a drop date, and all three axes. The Audience step needs one audience under Inclusions. The Packages step needs one package. Complete the missing item.
On Review, Audience Size shows N/A for every package. The Selection grid still shows counts. Avid could not calculate the Review counts. The page does not show the error. Do not rebuild the appeal. Your appeal settings, packages, and saved selections stay as they are. Contact LockStep Support.
An Error! dialog says An error occurred while processing the file. Please submit a support ticket for further assistance. Avid could not build the list or the file. A column in your file layout is one possible cause. Open Direct Mail > File Layouts, check the column, and generate the file again. If the message returns, contact LockStep Support.
An Error! dialog says File layout column "NAME" has an invalid source. Choose a valid data column and try the export again. One column in the file layout points to a source Avid cannot read. NAME is the column's Export Column Name. Open Direct Mail > File Layouts, edit that column, choose its source again, and save the layout. Then generate the file again.
The emailed link stopped working, or the email did not arrive. Each link works for one hour. The email subject is Direct Mail File Ready for followed by your organization's name. Open Direct Mail > Appeals, open the Actions menu on the appeal, and click Download. You need Edit and Export to see it. Avid keeps the last file you generated for each appeal.
People you expected are missing from the file.
  • Their cell has no package color.
  • They have no value for one of the three axes.
  • They match an Exclusions audience.
  • A Selection Limitation removed them.
  • They are not in the constituent data blend.
 Look for cells with no color on the Selection step. Check each Selection Limitation on step 1. Then contact LockStep Support with the Account ID of one missing person.
Counts changed since the last time you worked on the appeal. Your blend refreshed, or you are comparing the grid with Review. See When Avid counts people. Open Review for current counts. To update the grid, go back to the Audience step and click Next Step. Then look for cells with no color.
Two pieces go to the same household. Select only one record per household works within one constituent record. Address de-duplication needs an exact match. See What each Selection Limitation does. Turn on De-duplicate records based upon address. Fix names and addresses that do not match in your CRM.
Cells lost their package colors. You changed an axis after you assigned packages, or your data gained new values. See What happens to grid cells when your data changes. Assign packages again on the Selection step. Avoid changing axes after you assign packages.
The groups for a custom calculation are not what you expected. Avid groups some number and date calculations into ranges. See Axes and custom calculations. Change the calculation so that it returns text. Then choose it again as an axis on step 1.
You need a split other than 50/50. The split for Split for A/B Test is fixed. See The A/B split is fixed at 50/50.
The appeal does not appear in Matchback. The reporting box was not ticked, or the registration did not finish. Follow Confirm a drop registered for Matchback.
People you deleted or merged in your CRM still appear in a select. Some file-based feeds add new and changed records but never remove old ones. Avid cannot see deletions or merges in those feeds. Add those people to an Exclusions audience. Ask LockStep Support whether your data set can be rebuilt from your latest file.

LockStep insight: Open the Review step again just before you click Generate File. Compare Audience Size with the number you expect. Only one person should edit an appeal at a time.

When to contact LockStep Support

Contact LockStep Support if the table above does not explain the problem. Also contact them if a message asks you to submit a support ticket. Include:

  • The appeal name and the number at the end of its web address.
  • The step where it happens and the exact message. Copy it from the Error! dialog.
  • The date, time, and time zone.
  • Your X, Y, and Z axes, and which Selection Limitations are on.
  • The file layout name.
  • The count you expected, the count you see, and the step where you read it.
  • The Account ID of one person who is missing or repeated.
  • Whether you ticked Include the exported data in Direct Mail and Matchback reporting.
  • When your constituent data blend last refreshed.

Next steps

For agency partners
  • Generate File saves first. Avid sends the appeal form from your screen, then builds the file. If a teammate changed the appeal in another tab, your save can overwrite their changes. If your screen shows different axes than Avid has saved, Avid clears the package selections.
  • Reporting file. With the reporting box ticked, Avid saves a CSV. The CSV has these columns: appeal_name, drop_date, package_code, appeal_code, account_id, mailing_id, source, and cost_per_piece. Avid names the file appeal name (ID #id). It saves the file through your file upload connection and maps it as a data set. Generating again replaces the file and reuses the data set.
  • Built-in axes. Avid wraps most built-in axes in a range function for gift counts, revenue, or months since. Fiscal Year Lifecycle and Trailing 12 Mo. Lifecycle use their stored values as written.
  • Custom calculation ranges. Avid checks the field path and the data type. An integer always uses gift-count ranges. A decimal uses gift-count ranges when the field path includes gifts or num. It uses revenue ranges when the field path includes revenue, amount, amt, or average. Any other decimal is used as written. A date uses months-since ranges.
  • A/B assignment. Avid hashes the appeal ID and the Account ID into ten buckets. Five buckets are Control and five are Treatment.
  • One address, email, and phone per person. The file reads the primary one first. For email and phone, it then prefers a valid one. For address, it then prefers one with a street line.

Related articles