This topic describes how to import contact and profile attribute data with a CSV file.

For general information, see

Basic File Structure​

Example: "user.Email","user.FirstName","user.DateOfBirth","user.CustomAttribute.colour" "","Jane","1961-11-14","purple" "","Joe","1981-12-21",""

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

  • The first line is a header record. The header record contains field names. The field names tell Mapp Engage what kind of contact data is in the import file. For example, the header name "user.FirstName" tells Mapp Engage that the column data contains the first name of each contact.
    If the header record is not correctly formatted, the system produces an error message. The data is not imported.

  • The second and following lines contain the values to be saved. Each line contains data for one contact.

  • The first value of the record must be the email address, mobile number, or mobile app alias. Mapp Engage uses this unique information to identify the contact and to store the profile data in the correct profile.
    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​.

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

Standard Attributes​

Mapp Engage offers several standard attributes to store contact profile data. These attributes are offered by default in every system.

For a list of the attribute references and information about required data formats, see Quick Reference: Contact Import CSV​.

Custom Attributes​

Custom attributes store data about a contact. This type of attribute is created specifically for your system. Custom attributes are specific to your system, and do not come standard with Mapp Engage. You can create custom attributes to the store the data about your contacts that is relevant to your digital marketing needs and strategies.

In the CSV header, the field names for custom attributes have the following format: user.CustomAttribute.X

  • Replace X with the name of the attribute. You can view the name of the profile attributes in your system in the ​Administration​ area.

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

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


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.product" "","London","shoes" "","Paris","coat"


If your custom attribute names contain special characters, you have two options:

  • Place all items in the header in quotation marks. For example:

    • "user.CustomAttribute.My Attribute with a Space"

    • "user.CustomAttribute.Astrology / Horoscope"

  • Use square bracket notation. For example:

    • 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 let you save different information for the same contact in different groups. For more information, see Attributes​.

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.

You can view member attributes in the contact profile. To do so, search for the contact on the ​Memberships​ tab in the ​Contact Management​ area.

Member attributes always use the ​String​ data type and cannot be enumerated. A value that is stored in a member attribute has a maximum length of 2000 characters.

The field names for member attributes have the following format: user.CampaignAttribute.X

  • Replace X with the name of the attribute.

  • 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" "","London","shoes" "","Manchester","Jacket"

Read Mode​

The read mode stores information about how contacts want to receive messages.

Mapp Engage uses the read mode to decide which channel to use when it sends messages to your contacts. The read mode controls the following channels: email, SMS, and mobile push.

Read mode preferences apply to group messages only. Read mode preferences do not apply to system messages.


By default, read mode preferences are only valid within a specific group. These settings do not apply for messages that the contact receives from other Mapp Engage groups.

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.

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

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






​Allow or Deny​





If available, a group message is sent to the contact in this channel.


Group messages are never sent to the contact in this channel.


The contact prefers this channel for communication.


No messages are sent to this contact via email, SMS, or mobile push. To deactivate contacts temporarily, use this value.


No sendout channel preference has been indicated.

​Specify Email Preference​



The preferred email message format is HTML.


The preferred email message format is a multipart email with both HTML and plain text.


The preferred email message format is plain text.

​Specify Mobile Preference​



The preferred mobile format is standard SMS (160 characters).

Group Attributes​

A group attribute stores one value for all members of a group. The value is identical for all group members.


It is not possible to import group attributes in a CSV file that is used for contact data import. Group attributes must be imported in a separate CSV file. For more information, see CSV Format for Group Attribute Imports​.

Importing the File​

You can import the file manually, or set up a regularly scheduled automation.