This page describes the data fields of a contact and how to de-/serialize a contact as XML.

This section describes the attributes of a contact. The entry “Passed as XML” describes if this attribute is submitted to the API as XML (if “yes”) or as parameter of the REST call (if “no”).

Attribute Type Default Passed as XML Description
id / long No The ID of a contact
permission / Permission / 1 No The permission can be one of: (1) none, (2) single-opt-in, (3) confirmed-opt-in, (4) double-opt-in, (5) double-opt-in-plus or (6) other and needs to be identified by the code (the number in the brackets)
email / String Yes The email address of the contact
external_id / String Yes If an external system needs to identify a contact, this ID can be used. This external ID is not guaranteed to be unique as it is managed by an external system.
anonymous / boolean Yes If this flag is set to true, the contact will be handled anonymously in Maileon and will only be shown in reports in anonymized form
standard_fields Map<StandardContactField, String> Yes A map of StandardContactFields and their (String) value
custom_fields / Map<String, String> Yes A map of custom data field names and values
created timestamp Yes (possible but value will be omitted) The timestamp of the creation date of the contact
updated timestamp Yes (possible but value will be omitted) The timestamp of the last update of the contact

XML Representation

This is an example of an XML representation of a contact:

<contact>
   <email>max.mustermann@xqueue.com</email>
   <permission>1</permission>
   <external_id>someExternalId</external_id>
   <anonymous>1</anonymous>
   <created>2014-10-13 09:44:30.0</created>
   <updated>2015-03-19 18:57:36.0</updated>
   <standard_fields>
      <field>
         <name>FIRSTNAME</name>
         <value>Max</value>
      </field>
      <field>
         <name>LASTNAME</name>
         <value>Mustermann</value>
      </field>
   </standard_fields>
   <custom_fields>
      <field>
         <name>Eye Color</name>
         <value>Blue</value>
      </field>
   </custom_fields>
</contact>

Sample Java-Deserializer

This code example shows a deserializer for contacts (written in Java):

public Contact fromXml(Element e) {
    Contact contact = new Contact();
    String idStr = e.elementText("id");
    if (idStr != null) {
        contact.setId(Long.parseLong(idStr));
    }
    String permissionStr = e.elementText("permission");
    if (permissionStr != null) {
        contact.setPermission(Permission.get(Integer.parseInt(permissionStr)));
    }
    contact.setEmail(e.elementText("email"));
    contact.setExternalId(e.elementText("external_id"));
    String anonymous = e.attributeValue("anonymous");
    if (anonymous != null) {
        contact.setAnonymous(Boolean.parseBoolean(anonymous));
    }
    Element standardFields = e.element("standard_fields");
    if (standardFields != null) {
        List<Field> l = parseFields(standardFields.elements("field"));
        for (Field f : l) {
            contact.getStandardFields().put(StandardContactField.parse(f.getName()), f.getValue());
        }
    }
    Element customFields = e.element("custom_fields");
    if (customFields != null) {
        List<Field> l = parseFields(customFields.elements("field"));
        for (Field f : l) {
            contact.getCustomFields().put(f.getName(), f.getValue());
        }
    }
    return contact;
}

De-/Serializing Multiple Contacts

Some methods like getContacts or synchronizeContacts require to pass several contacts at once. Serializing several contacts is done using a wrapping <contacts></contacts> tag.

<contacts>
    <contact>
        <email>max.mustermann@xqueue.com</email>
        [...]
    </contact>
    <contact>
        <email>erika.mustermann@xqueue.com</email>
        [...]
    </contact>
</contacts>