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) |
/ 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>