This documentation gathers best practices for implementing plugins for third party apps that connect those apps with Maileon. This documentation is not specialized on technical details but should help getting an understanding of business processes. Considering contact synchronization between a shop system and Maileon. First, it sounds rather simple but there is certain set of “hidden” details, not everyone thinks of, e.g. what happens if a customer changes the email in the shop? Will it be changed in Maileon, too? Is the permission then still valid or does it have to be revoked? Is the subscription maybe independent and changing some email in some shop does not affect the subscription for a contact in Maileon at all?
As experience with developing plugins grows, this documentation should grow along and help partners, customers, or independent agencies to think of those details and decide what to include in the plugin.
What should be synchronized?
Maileon contact profiles can be filled with standard fields like first and last name and a flexible amount of custom fields which can be created by the administrators of an account or using the API. However, according to German law the principle of data avoidance (German: “Datenvermeidung”) or data economy (German “Datensparsamkeit”) should be followed for personalized data. Only data required for operating Maileon should be submitted, not more.
Please check the necessity of the data processing before transferring personal data and obey the relevant legal data processing requirements (e.g. the principle of data parsimony and avoidance according to the Federal Data Protection Act, as well as the rules for data transmission to commissioned data processors or third parties).
You are obligated to have provable consent of the addressees before sending them advertising e-mails as well as for processing their response data at single user level (single user tracking).
How do I start?
Important: When using the API make sure you are using UTF-8 to submit data to our servers.
If you can host PHP files and are just interested in providing a subscription, personalization, or unsubscription form, you can generate working forms for your account when you log into your Maileon Account. Go to “Settings” à “PHP Code Generator”, select the API-Key the form should use – maybe you have to create one first – and the contact fields you need. Once you generated the forms you can download them using the download button on the right. Now you can upload them to your web server but make sure that PHP mod cURL is enabled as it is mandatory for the client to communicate with the REST API.
For all deeper integrations, Maileon provides a REST API. The general documentation can be found here:
However, most of the time implementation process can be accelerated by using one of the provided API clients:
These clients ease development by already implementing the authentication, de-/serialization, and the resources you need, including parameters, mime types, etc..
If you are planning a project in C#, there is also a client to be found on Github from a partner of ours.
Synchronizing Single Contacts
Most often the first step for integration is to synchronize contacts between Maileon and some other system. However, synchronizing contacts is sometimes a complicated problem. Some ideas of discussions before implementing a solution:
- Is the leading database the customer database or Maileon? Both is possible but while some customers work inside Maileon and only use their website to collect newsletter subscriptions, other companies might use their own CRM (Customer Relation Management) tool and operate there to control subscribed contacts.
- Another question a customer should ask: “do I just push data to Maileon and use it there or do I need feedback”? Examples:
- Did a contact bounce?
- Did a contact click the DOI link?
- Did a contact unsubscribe?
- Does my system know if the contact unsubscribed or not? Who decides if an unsubscriber is still unsubscribed or resubscribed?
In this section we will roughly describe the full synchronization with some feedback but feel free to leave parts out in your implementation. The process usually looks like this:
- Contact fills newsletter subscription form on the web page
- CreateContact is used to create a contact in Maileon. Sometimes also GetContact is used to check if that contact is already subscribed and maybe display some hint.
You should always use a DOI process to collect the user’s permission. Therefore create a DOI-Mailing in Maileon and assign a DOI-Key or set the DOI-Mailing in the “Settings” -> “Contact Management” as default mailing. Then set parameter “doi“ to “true“,“doiplus“ to “true” (if you want to collect personalized single user data like clicks) and, if you don’t want to use the default mailing, the parameter “doimailing” to the DOI-Mailing key.
- Now a contact without permission should be created in the Maileon account and as soon as the contact acknowledges the DOI-Link, you can use webhooks to notify your system. This works for DOI acknowledgements as well as for unsubscriptions and bounces.
- If there is a possibility to unsubscribe in the external system, you should use UnsubscribeContact to unsubscribe the contact also in Maileon.
The process could be realized as roughly shown in Figure 1. You can set up the Maileon Webhook Controller to call a resource (URL) in case of different events in Maileon, e.g. when a user has clicked the DOI link or unsubscribed. The URL will be called with a configurable set of parameters and to ensure that no one just manually calls the webhook and changes random data there are two common approaches to secure the call:
1. Submitting the Maileon contact ID and checksum.
This can be used to request contact details from Maileon in a secure way as guessing some contact ID and some checksum usually ends up in an invalid result, for more details, see FAQ.
2. It is also possible to secure the call by just using the email address and some secret key that can be defined as a static parameter and has to be checked in the receiving resource. Since the connection should be SSL encrypted, those parameters are also encrypted and cannot be sniffed.
If it is impossible to reach your system from the internet, webhooks might not be suitable. In this case you should implement a cron job checking e.g. the unsubscriptions since the last run.
If it is possible to update contact data from the external system you can use the same CreateContact method but make sure the parameter “sync_mode” is set to “1” ( = update). The scenario would then maybe look like shown in Figure 2.
Synchronizing Many Contacts
If you are not interested in submitting single contact changes in real time to Maileon, but you want to submit large chunks of contacts at once, there are other Methods than calling CreateContact for every single contact.
1. The most efficient method is to use the FTP import job. You can create an FTP server in Maileon or specify an own FTP server and place a CSV with contacts and unsubscribers there. Maileon can import that data on a regular base using a configured field mapping. See the handbook or ask our service team, if you want to know more about the procedure.
2. If you want more control, you can go the API way and use a method called SynchronizeContacts. Here a blocking call can be made submitting large chunks of contacts and getting a report if everything worked as expected. However, as this is a blocking call, think about chunking your list of contacts to avoid long running connections causing a possible timeout in some systems. Submitting 5000 contacts in one call is usually a good tradeoff.