+49 69 83008980 service@xqueue.com
Benötigen Sie Hilfe?

Im Maileon Help-Center finden Sie umfassende Dokumentationen zu unserem System.

Beliebte Suchanfragen: Importe | Rest-API | Integrationen | SMS

Synchronize Contacts

Sie sind hier:

Synchronizes (updates) the contacts in the account with the data from a list of contacts and returns a detailed report with stats and validation errors. This method is meant to update large sets of contacts while “Create Contact” and “Update Contact” are used to update single contacts only. With this method, e.g. flags for contact filters can be updated to update the set of contacts that shall receive a certain mailing.

Duplicates (e.g. contacts with the same email address when the email address is the primary identificator) are not allowed in one call and will be ignored as it is not defined which one should possibly override the other.

Contact Preferences: If the source of a contact preference is not available in XML, the source will not be updated, even if the value changes. If the XML node is available but empty or null, source will be deleted, if source is filled the source for the preference will be set, nevertheless if the value itself changed or not. If value changes or if source changes but value stays the same, last_modified will be updated.

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

Attributes

Parameter Default Description
permission 1 Specifies the permission to be assigned to the contact. Supported values are 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 identifier (external id or email address) already exists:1: update, 2: ignore
use_external_id false If set to true, the external id is used as identifier for the contacts. Otherwise the email address is used as identifier. If ‚use_external_id‘ and ‚prefer_maileon_id‘ are set to true, a bad request (400) will be returned.
prefer_maileon_id false If set to true, the maileon id is used as identifier for the contacts. If no id is set, the email will be used instead. If ‚prefer_maileon_id‘ and ‚use_external_id‘ are set to true, a bad request (400) will be returned.
ignore_invalid_contacts false If set to true, invalid contacts are ignored and the synchronization succeeds for valid contacts. A report object will be returned, which contains all failed contacts with a reason code which can be found here: Synchronize Contacts Error Codes.
override_permission true If set to true the permission of existing and non existing contacts will be set to the given permission. If the permission is not set, permission ’none‘ will be set for new contacts and the permission of existing contacts will not be changed. If set to false, the permission will be used for new contacts only and the permission of existing contacts will not be changed.
reimport_unsubscribed_contacts true If set to true unsubscribed contacts will be reimported, else, they will be ignored.
update_only false If set to true only existing contacts will be updated. Not existing contacts will not be created.

Example (Request)

POST https://api.maileon.com/1.0/contacts?permission=5&sync_mode=1
Authorization: Basic XXXXXXXXXXXXXXX
Content-Type: application/vnd.maileon.api+xml; charset=utf-8

<contacts>
  <contact>
    <email>max.mustermann@xqueue.com</email>
    <external_id>external-id-1</external_id>
    <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>
  <contact>
    <email>erika.mustermann@xqueue.com</email>
    <external_id>external-id-2</external_id>
    <standard_fields>
      <field>
        <name>LASTNAME</name>
        <value>Mustermann</value>
      </field>
      <field>
        <name>FIRSTNAME</name>
        <value>Erika</value>
      </field>
    </standard_fields>
    <custom_fields>
      <field>
        <name>COLOR</name>
        <value>RED</value>
      </field>
    </custom_fields>
  </contact>
</contacts>

Example with Contact Preferences

POST https://api.maileon.com/1.0/contacts?permission=5&sync_mode=1
Authorization: Basic XXXXXXXXXXXXXXX
Content-Type: application/vnd.maileon.api+xml; charset=utf-8

<contacts>
  <contact>
    <email>max.mustermann@xqueue.com</email>
    <external_id>external-id-1</external_id>
    <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>
    <preferences>
      <preference>
        <name>Shopware</name>
        <category>Development</category>
        <value>true</value>
        <source>test</source>
      </preference>
      <preference>
        <name>Magento</name>
        <category>Development</category>
        <value>false</value>
        <source>test</source>
      </preference>
    </preferences>
  </contact>
  <contact>
    <email>erika.mustermann@xqueue.com</email>
    <external_id>external-id-2</external_id>
    <standard_fields>
      <field>
        <name>LASTNAME</name>
        <value>Mustermann</value>
      </field>
      <field>
        <name>FIRSTNAME</name>
        <value>Erika</value>
      </field>
    </standard_fields>
    <custom_fields>
      <field>
        <name>COLOR</name>
        <value>RED</value>
      </field>
    </custom_fields>
    <preferences>
      <preference>
        <name>Shopware</name>
        <category>Development</category>
        <value>true</value>
        <source>test</source>
      </preference>
      <preference>
        <name>Magento</name>
        <category>Development</category>
        <value>false</value>
        <source>test</source>
      </preference>
    </preferences>
  </contact>
</contacts>

Report when ignore_invalid_contatcts is set to true

<report>
    <success>false</success>
    <count_contacts>3</count_contacts>
    <count_existing_contacts>0</count_existing_contacts>
    <count_new_contacts>0</count_new_contacts>
    <count_invalid_contacts>2</count_invalid_contacts>
    <count_unsubscribed_contacts>0</count_unsubscribed_contacts>
    <invalid_contacts>
        <contact>
            <email>max.mustermann.3@xqueue</email>
            <external_id nil="true"/>
            <error code="3">
                <error_field>max.mustermann.3@xqueue</error_field>
            </error>
        </contact>
        <contact>
            <email>max.mustermann.2@xqueue.com</email>
            <external_id nil="true"/>
            <error code="21">
                <error_field>test</error_field>
            </error>
        </contact>
    </invalid_contacts>
</report>

In this case the documentation helps resolving the code 3 to „invalid email address“ and 21 to „no such custom field“ with name „test“. See „Synchronize Contacts Error Codes„.

Inhaltsverzeichnis