Create Contact

Creates or updates a contact and optionally triggers a double opt-in (doi) process. Note that none of the attributes is required, however, the body needs to provide a XML representation of the contact, in the easiest case an empty contact: <contact></contact>.The email should not be part of the body as it is passed as a URL (resource) element. If you want to set an external ID make sure to never set the email address in the body. Valid expression: <contact><external_id>12345</external_id></contact>

POST https://api.maileon.com/1.0/contacts/email/:email

 

Attributes

Parameter	Default	Description
permission	1	Specifies the initial permission to be assigned to the contact.Please note: this is the initial permission that is assigned to the contact as soon as it is created. If a double-opt-in process is triggered, the permission is changed to DOI or DOI+ after the contact used the acknowledgement link in the DOI mailing. If the same contact is registered again after already acknowledging the DOI link (and thus, already has Permission 4 or 5) and you call this method with any other permission then 4 or 5 (less valuable), the permission will be ignored, since you already own a valid DOI(+) permission.
		Further, if Permission 4 or 5 is already set and the account is set up not to send DOI mailings if there is already a DOI permission, no DOI mailing is triggered when creating the contact a second time.Supported values:
		1: none
		2: single opt-in
		3: confirmed opt-in
		4: double opt-in
		5: double opt-in plus
		6: other
sync_mode	2	Specifies the synchronization option in case a contact with the provided email address already exists.Supported values:
		1: update (contact data will be updated)
		2: ignore (nothing will be done)
src		A string intended to describe the source of the contact. If provided, the string will be stored with the doi process.
subscription_page		In case where this method was called by a subscription page, this string offers the possibility to keep track of it for use in reports.
doi	false	Tells whether a double opt-in process should be started for the created contact. Note that the status code returned for this request does not mean that the doi process succeeded. Supported values are true and false. Notice: Please be aware that you can set up the behavior for (re-)sending DOI mails in your Maileon account under “Settings” -> “Lists & Contacts” -> “Contact Management”. Here you can define if a DOI mail should be sent to contacts not having finished the DOI process or contacts having a valid DOI permission already.
doiplus	false	This parameter is ignored if doi is not provided or false. In case the doi process succeeds, Maileon will be allowed to track opens and clicks of the contact.
doimailing		This parameter defines the DOI mailing key of the (active) DOI mailing to be used. Be aware, that this is not the ID of the DOI mail but the key that can be specified in the API or UI. It is ignored if doi is not provided or false. If not provided, the default doi mailing will be used.

Example

Request

POST https://api.maileon.com/1.0/contacts/email/max.mustermann%40xqueue.com?permission=1&sync_mode=2&doi=true&doiplus=true
Authorization: Basic XXXXXXXXXXXXXXX
Content-Type: application/vnd.maileon.api+xml; charset=utf-8

<contact>
  <!— Note that the email address is redundant because already specified in the URI. Therefore it can be omitted here. -->
  <email>max.mustermann@xqueue.com</email>
  <standard_fields>
    <field>
      <name>LASTNAME</name>
      <value>Mustermann</value>
    </field>
    <field>
      <name>FIRSTNAME</name>
      <value>Max</value>
    </field>
  </standard_fields>
  <custom_fields>
    <field>
      <name>COLOR</name>
      <value>BLUE</value>
    </field>
  </custom_fields>
</contact>

Response

Status: 201 Created
<id>3792111</id>

Example of contact with contact preferences

<contact>
  <id>12345</id>
  <email>max.mustermann@xqueue.com</email>
  <external_id>mustermann-ext-1956</external_id>
  <standard_fields>
    <field>
      <name>FIRSTNAME</name>
      <value>Max</value>
    </field>
    <field>
      <name>LASTNAME</name>
      <value>Mustermann</value>
    </field>
  </standard_fields>
  <custom_fields/>
  <preferences>
    <preference>
      <name>Shopware</name>
      <category>Developer</category>
      <value>true</value>
      <source nil="true"/>
    </preference>
    <preference>
      <name>Magento</name>
      <category>Developer</category>
      <value>false</value>
      <source nil="true"/>
    </preference>
  </preferences>
</contact>