---
title: "XML Format for Contact Imports"
slug: "xml-format-for-contact-imports"
updated: 2026-07-30T13:17:37Z
published: 2026-07-30T13:17:37Z
canonical: "docs.mapp.com/xml-format-for-contact-imports"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XML Format for Contact Imports

This page explains the XML format required to import contact data into Mapp Engage. It describes the file structure, available elements and attributes, and how to configure them correctly during import.

---

## Basic File Structure

To format your XML file correctly, follow these rules:

- XML element and attribute names are case-sensitive.
- During import, Mapp Engage compares attribute names case-insensitively to avoid duplicates caused by capitalization.
- The first line of your file must include the XML declaration and character encoding. Make sure the encoding matches your input file, and select the same encoding during import.

**Component Table**

| **Component** | **Description** |
| --- | --- |
| **XML Declaration and Encoding** | The first line defines the XML version and character encoding. |
| **Tags** | Elements are marked with a start tag `<elementname>` and an end tag `</elementname>`. |
| **XML Elements** | Elements hold contact data and define where it is stored. - **userdata** – Holds all contact data; includes XML namespace `xmlns="http://webservices.ecircle-ag.com/ecm"`. - **list** – Defines new custom attributes for the import. - **user** – Holds one contact’s data, identified by `email`, `mobilenumber`, or `faxnumber`. |
| **XML Attributes** | Elements can include attributes written as `name="value"`. Example: in `<xml version="1.0" encoding="UTF-8">`, `encoding` is the name and `"UTF-8"` is the value |

```xml
<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
	<list>
		<namedattr-definition enum="false" type="date" name="LastPurchase"/>
		<namedattr-definition enum="false" type="number" name="HouseholdSize"/>
		<namedattr-definition enum="false" type="string" name="Hobbies"/>
			<user>
				<email>joseph.example@emaildomain.com</email>
				<mobilenumber>498912345678</mobilenumber>
				<faxnumber>00000000</faxnumber>
				<identifier>11122233abc</identifier>
				<firstname>Joseph</firstname>
				<lastname>Example</lastname>
				<nickname>Joe</nickname>
				<dateofbirth>1983-06-23</dateofbirth>
				<title>1</title>
				<zipcode>12345</zipcode>
				<partnerid>12345</partnerid>
				<isolanguagecode>en</isolanguagecode>
				<isocountrycode>US</isocountrycode>
				<timezone>Europe/Berlin</timezone>
				<namedattr name="TotalPurchases">944.76</namedattr>
				<namedattr name="LastPurchase">15.03.2010</namedattr>
				<namedattr name="HouseholdSize">3</namedattr>
				<namedattr name="Hobbies">Dancing</namedattr>
				<memberattr name="LastPurchase">shoes</memberattr>
				<memberattr name="LocalStore">Manchester</memberattr>
				<channel type="email" mode="prefer" format="email-html"/>
				<channel type="mobile" mode="allow"/>
				<channel type="fax" mode="deny"/>
				<maxmessages number="2" period="7"/>
			</user>
	</list>
</userdata>
```

---

## Standard Attributes

Mapp Engage provides several standard attributes for contact profile data. These are available by default in every system. For details on formats, see the [Attribute Reference](/docs/xml-format-for-contact-imports#attribute-reference) section below.

---

## Custom Attributes

In an XML import, custom attributes are defined with the `namedattr` element. The `name` attribute specifies the attribute name, and the value is placed between the start and end tags.

```xml
<namedattr name="LastPurchase">15.03.2016</namedattr>
```

- If the attribute already exists, Mapp Engage adds the value.
- If it does not exist, Mapp Engage creates the attribute.
- Best practice: specify the data type and whether the attribute is enumerated during import.

**Example**

```xml
<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
  <list>
    <user>
      <email>Jane.Miller@email.com</Email>
      <mobilenumber>498912345678</MobileNumber>
      <firstname>Jane</FirstName>
      <namedattr name="LastPurchase">15.03.2016</namedattr>
    </user>
  </list>
</userdata>
```

---

## New Custom Attributes

You can create new custom attributes when you import a file. Define the data type and whether the attribute is enumerated with the `namedattr-definition` element.

**Example**

```xml
<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
  <list>
    <namedattr-definition enum="false" type="date" name="LastPurchase"/>
    <namedattr-definition enum="true"  type="number" name="HouseholdSize"/>
    <namedattr-definition enum="false" type="string" name="Hobbies"/>
  </list>
</userdata>
```

> [!NOTE]
> **Note**
> 
> You can only define data types and enumerations for attributes that do not already exist in Mapp Engage. If you include these settings for an existing custom attribute, the import fails.

**XML Attributes**

| **XML Attribute** | **Description** | **Possible Values** |
| --- | --- | --- |
| **enum** | Defines whether the attribute is enumerated. By default, new custom attributes are enumerated, and all values in the file are added. An enumerated attribute can contain up to 1000 values; if more are present, the import fails. | `true`, `false` |
| **type** | Sets the data type. Defaults to `string` if not specified. | `string`, `number`, `date` |
| **name** | Names the attribute. Cannot contain underscores or special characters; periods are allowed. | (Custom text) |

---

## Member Attributes

Member attributes let you store different values for the same contact across different groups.

You can only create member attributes by importing an XML or CSV file. They cannot be created manually in the Mapp Engage interface. Member attributes always use the `string` data type.

In the XML file, member attributes are defined with the `memberattr` element. The `name` attribute specifies the member attribute, and the value is placed between the start and end tags.

**Example**

```xml
<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
  <list>
    <user>
      <email>jose.example@email.com</Email>
      <memberattr name="LastPurchase">shoes</memberattr>
      <memberattr name="LocalStore">Manchester</memberattr>
    </user>
  </list>
</userdata>
```

- If the member attribute already exists in the group, the new value is added to it.
- If it does not exist, Mapp Engage creates the attribute and stores the value.

---

## Group Attributes

Group attributes cannot be imported in the same XML file as contact data. They must be imported separately.

For details, see [Import Group Attributes](/v1/docs/import-group-attributes).

---

## Read Mode

Read mode defines how a contact prefers to receive group messages (email, SMS, push). It does not apply to system messages or single messages.

In the XML file, read mode is set with the `channel` element.

**Example**

```xml
<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
  <user>
    <email>Jane.Miller@email.com</Email>
    <channel type="email" mode="prefer" format="email-html"/>
    <channel type="mobile" mode="allow"/>
    <channel type="fax" mode="deny"/>
  </user>
</userdata>
```

- Preferences apply only within the current group.
- You can extend them system-wide during import (Advanced Options in *Import Contacts*).
- Manual edits in Mapp Engage always overwrite imported values.

**XML Attributes**

| **XML Attribute** | **Description** | **Possible Values** |
| --- | --- | --- |
| **type** | Defines the channel. | `email`, `mobile`, `fax` |
| **mode** | Sets the preference for the channel. | `prefer`, `allow`, `deny` |
| **format** | Defines the message format for email. | `email-html`, `email-text`, `email-multipart` |

---

## Message Limitation

You can limit the number of messages a contact receives within a defined period. This applies to all Mapp Engage channels (email, SMS, push) but not to system or single messages.

In the XML file, message limitations are set with the `maxmessages` element.

**Example**

```xml
<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
  <user>
    <email>Jane.Miller@email.com</Email>
    <maxmessages number="2" period="7"/>
  </user>
</userdata>
```

- In this example, the contact receives no more than two messages in seven days.
- After the limit is reached, no further messages are delivered until the period resets.

**XML Attributes**

| **XML Attribute** | **Description** | **Possible Values** |
| --- | --- | --- |
| **number** | Maximum messages a contact can receive. Use `0` to block all messages temporarily. | `1–99` = messages allowed `0` = no messages sent |
| **period** | Timeframe in days. Once the limit is reached, no more messages are sent during that period. | `1–31` = days |

---

## Attribute Reference

The following tables provide a quick reference for the standard elements, date and time formatting, and the additional elements used in contact import XML files.

### Standard Attributes

The following elements are nested inside the `user` element.

| XML Element | Description | Data Type |
| --- | --- | --- |
| `email` | Must be formatted as a standard email address (`localpart@domain.com`). | String |
| `mobilenumber` | Must include the area code. A plus sign (`+`) before the number is optional. Extra leading zeroes are not allowed. | String |
| `faxnumber` | Previously used to store fax numbers; now stores the alias for the mobile app. Accepts letters, numbers, and special characters (including periods and underscores). Values are not validated. Maximum length: 2000 characters. | String |
| `identifier` | Stores an external identifier (for example, from a CRM system). Accepts letters, numbers, and special characters (including periods and underscores). Values are not validated. To import contacts identified by an external identifier, a special import procedure is required. See [Update Contacts with External Identifier](/v1/docs/update-contacts-with-external-identifier). | String |
| `firstname` | Stores the contact’s first name. No special formatting is required. Values are not validated. Maximum length: 2000 characters. | String |
| `lastname` | Stores the contact’s last name. No special formatting is required. Values are not validated. Maximum length: 2000 characters. | String |
| `nickname` | Stores the preferred name of the contact. No special formatting is required. Values are not validated. Maximum length: 2000 characters. | String |
| `dateofbirth` | Must be formatted as `YYYY-MM-DD` (for example, `1965-08-08`) or as a full ISO-8601 timestamp (for example, `1965-08-08T12:00:00+00:00`). | Date |
| `title` | Stores the preferred title as a numeric value:• `1` = Mr.• `2` = Mrs.• `-1` = Unknown | Number |
| `zipcode` | Stores the ZIP or postal code. Format depends on the country. This attribute accepts letters and numbers. Values are not validated. Maximum length: 2000 characters. | String |
| `partnerid` | Stores a numeric value that identifies an external source of the contact address. Limited to a maximum of 5 numeric characters. | Number |
| `isocountrycode` | Must conform to ISO 3166-1 standards. For more information, see [https://en.wikipedia.org/wiki/ISO_3166-1](https://en.wikipedia.org/wiki/ISO_3166-1). | String |
| `isolanguagecode` | Must conform to ISO 639 standards. For more information, see [https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). | String |
| `timezone` | Must conform to the tz database (IANA) format, such as `America/New_York` or `Europe/Berlin`. For more information, see [https://en.wikipedia.org/wiki/Tz_database](https://en.wikipedia.org/wiki/Tz_database). | String |

---

### Date and Time Formatting

Mapp Engage uses ISO-8601 date formats.

Time zones must be entered using the following structure:

```bash
YYYY-MM-DDThh:mm:ss(+/-)GMT offset
```

**Example:** US/Eastern - `2012-12-25T15:15:15-05:00`

ISO-8601 formatting is recommended for all date and time values in the import file. Deprecated formats are not fully supported.

---

### Additional Information

The following elements are also nested inside the `&lt;user&gt;` element. The maximum number of characters per value is 2000.

| Attribute or Setting | XML Element | XML Attributes |
| --- | --- | --- |
| **Custom Attributes** | `namedattr` | `name` |
| **New Custom Attributes** | `namedattr-definition` | - `enum` (true or false) - `type` (string, number, date, or boolean) - `name` |
| **Member Attributes** | `memberattr` | `name` |
| **Read Mode** | `channel` | See [Read Mode](/docs/xml-format-for-contact-imports#read-mode) |
| **Message Limitation** | `maxmessages` | - `number` (maximum number of messages) - `period` (period in days) |

## Related

- [Automate Contact File Import](/automate-contact-file-import.md)
- [Import Contacts](/system-import-contacts.md)
- [Read Mode](/read-mode-configure-sent-message-format.md)