Contacts

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>