CSV Format for Contact Imports

Basic File Structure​

Example:

"user.Email","user.FirstName","user.DateOfBirth","user.CustomAttribute.colour"
"Jane_Miller@email.com","Jane","1961-11-14","purple"
"Joe_Jones@domain.com","Joe","1981-12-21",""

To format a CSV file for import into Mapp Engage, use the following guidelines:

1. Header Record:

   • The first line is a header record containing field names, which tell Mapp Engage the type of contact data in the import file. For example, "user.FirstName" indicates that the column contains the first names of the contacts.

   • If the header record is incorrectly formatted, the system will produce an error message, and the data will not be imported.

2. Data Records:

   • Subsequent lines contain the values to be saved, with each line representing one contact.

   • The first value must be the email address, mobile number, or mobile app alias used by Mapp Engage to uniquely identify the contact and store the profile data. It is also possible to update contact data in Mapp Engage with an import file that uses the external identifier as the primary identification. For more information, see Update Contacts with External Identifier.

3. Empty Fields:

   • If a contact record has no value for a particular field, use empty quotation marks ("").

Standard Attributes​

Mapp Engage provides several standard attributes to store contact profile data by default in every system.

For attribute references and required data formats, see Quick Reference: Contact Import CSV.

Custom Attributes​

Custom attributes store specific data relevant to your digital marketing needs. These are created specifically for your system and are not standard with Mapp Engage.

CSV Header Format for Custom Attributes:

"user.CustomAttribute.X"

Replace X with the attribute name, viewable in the Administration area.

• If the custom attribute exists, Mapp Engage adds the values to it.

• If it does not exist, Mapp Engage creates it with the header-defined name.

  By default, all new custom attributes that you create with a CSV import are enumerated. Mapp Engage creates an enumeration value for every value in the column for that attribute.

Sample CSV Structure:

"user.Email","user.CustomAttribute.city","user.CustomAttribute.product"
"Jane_Miller@email.com","London","shoes"
"Joe_Jones@email.com","Paris","coat"

Special Characters in Custom Attribute Names:

• Use quotation marks for the entire header item:

  "user.CustomAttribute.My Attribute with a Space"
  "user.CustomAttribute.Astrology / Horoscope"

• Alternatively, use square bracket notation:

  user.CustomAttribute['My Attribute with a Space']
  user.CustomAttribute['Astrology / Horoscope']

• Do not use square bracket notation for standard attributes.
  "user['Email']" causes an error during import.

• Do not use function notation for imports
  ${user['Email']} causes an error during import.

Member Attributes​

Member attributes store different information for the same contact across different groups.

CSV Header Format for Member Attributes:

"user.CampaignAttribute.X"

Replace X with the attribute name.

• If a member attribute with that name exists in the group, Mapp Engage adds the values to the existing attribute.

• If a member attribute with that name does not exist in the group, Mapp Engage creates an attribute to store the data. The attribute name is defined in the header.

Sample CSV Structure:

"user.Email","user.CampaignAttribute.LocalStore","user.CampaignAttribute.LastPurchase"
"Jane_Miller@email.com","London","shoes"
"Joe_Jones@example.com","Manchester","jacket"

• You can only create member attributes with import of an XML or CSV file. You cannot create member attributes manually on the Mapp Engage interface.

• Member attributes always use the ​String​ data type and cannot be enumerated. The member attribute value has a maximum length of 2000 characters.

Read Mode​

Read mode indicates how contacts prefer to receive messages, controlling channels like email, SMS, and mobile push. Preferences apply to group messages only and can be applied system-wide during import.

During import, you can choose to apply the read mode preferences system-wide. This option means that the read mode settings for each contact are overwritten for all groups this contact is a member of. This option is found in the ​Advanced Options​ area of the ​Import Contacts​ window.

You can edit the read mode setting for a single contact in the Mapp Engage interface. The preferences that you enter in Mapp Engage manually overwrite any read mode preferences that have been imported into Mapp Engage in an XML or CSV file.

Sample CSV Structure:

"user.Email","member.EmailChannel","member.EmailChannel","member.MobileChannel"
"Jane_Miller@email.com","prefer","email-html","allow"

Read Mode Values:

• allow, deny, prefer, none, any for channels.

• Email preferences: email-html, email-html-multipart, email-text.

• Mobile preference: mobile-sms.

Example:

The following file specifies that Jane Miller has three preferences: messages via email, HTML format (rather than text), and SMS.

Group Attributes​

Group attributes store one value for all group members. They must be imported in a separate CSV file for group attribute imports.

It is not possible to import group attributes in the same CSV file used for contact data import.

Importing the File​

You can import the file manually or set up a regularly scheduled automation. For detailed instructions, see:

• Automate Contact File Import​

• Import Contacts​