Install

mailerlite connector was created in a way, to not have any external package dependencies, so installation is straightforward. Simply install mailerlite module.

It does though have one non standard Odoo module dependency, called mass_mailing_contact_fields. This module adds extra fields on Mailing Contact, which is used to store extra information about MailerLite subscribers. This module will come bundled with main module when you download it.

Setup

To initially setup Odoo and MailerLite, so it would be possible to use connector, you need to do at minimum these things:

• Log in to your MailerLite account, navigate to account (top left corner) and click on Integrations button. Enable Developer API (if have not yet) and then click on it to open next page, where API key will be visible.
• Copy that key and open your Odoo. Go to Email Marketing / Configuration / MailerLite / Accounts (administrator access is needed). Click to create new account. Paste your key into API Key field. Click Confirm button. If everything OK, account state should go to Confirmed and some of your account data will be fetched (like your Timezone you selected in your MailerLite settings)

Search Options

On your account, there is Search section. Here you can define basic search behavior, when Odoo is fetching data from MailerLite:

• Default Search Limit defines number of records to fetch at a time. This value will be suggested by default, when using Sync wizard. Note that MailerLite has limitations how much records can be fetched. At the time of writing, maximum limit is 5000. Though in real case, it does not seem that MailerLite is capable of handling such amounts, because API hangs. More realistic number would be about 500, but there are other limitations, which reduces this number to much lower value. See MailerLite Limitations section to have better understanding about it. Recommended value is 60.
• Default Search Total defines number of how many records to search in total at one given time. 0 means there is no limit. Recomended value is 60.
• Offset fields. These fields define how many records to skip when searching respective documents. Can be kept at 0, unless you need to skip some old records all the time. For example, setting offset to 1000, means oldest 1000 records will be skipped. When using sync wizard or cron jobs to pull data, Odoo will automatically handle offset, so it would rotate to your defined search limit and search total. What it means, it that leaving cron job to do data sync, it will eventually rotate over all data avoiding MailerLite API limitations.
• Timezone: This value is important, because it allows Odoo to know which timezone your MailerLite account uses. There are some inconsistencies with MailerLite dates (where some dates are returned with timezone, some without), so some dates (that require it) are converted (by Odoo) back and forth to correct format, using Timezone information.
• URL this value is selected automatically, to define correct URL to connect to MailerLite. Though if for some reason, mailerlite Host would change, its possible to create new one.
• Other fields are currently used for information purposes.

Timezones

MailerLite does not use all standard timezones (specific to some countries / towns with their daylight savings etc.), to workaround that, Odoo stores timezones used by MailerLite, instead of using standard ones. You can find it at Email Marketing / Configuration / MailerLite / Timezones. Once you confirm your MailerLite account through Odoo, timezone scheduling is automatically activated and is periodically (once day) checked if timezone offset changed (e.g. daylight savings).

Logs

When syncing data, if some of records can't be synced (e.g. record was deleted, yet reference to its ID left on Odoo), but whole transaction completes, Odoo will create log record, to better understand what went wrong. You can find logs at Email Marketing / Configuration / MailerLite / Logs. Log saves header info and payload that was used when error happened.

Webhooks

When some specific action happens on MailerLite, it can send that event data to Odoo. This connector currently supports these kind of webhooks:

• Subscriber Create
• Subscriber Update
• Subscriber Added to Group
• Subscriber Removed from Group
• Campaign is Sent

Campaign is Sent webhook sends information about campaign, once it sends emails to subscribers (this can be few minutes after you initiated instant send or after it sent on scheduled date).

NOTE. Subscriber Create event does not send data about subscriber groups, so to work around that, Odoo does additional request to MailerLite (once it received data about new Subscriber) to check if its related to any groups, to make sure groups relation is updated correctly.

Groups

MailerLite manages subscribers using so called Groups. When sending campaign, you can select specific groups to send email to related subscribers.

On Odoo side, equivalent is Mailing List.

For example if group called G1 is created in MailerLite, Mailing List with same name will be created in Odoo too.

Data Synced

In MailerLite, excluding metadata, only group name field is used, which is synced by Odoo.

Subscribers

Subscribers are recipients that will receive your emails. In Odoo, they are called Mailing List Contacts (or just Mailing Contacts). When syncing, Odoo also keeps track of related groups and updates relation if it changes.

Another important thing is Opt Out option. In MailerLite, it is called Subscribed/Unsubscribed. If subscriber unsubscribes in MailerLite, such information will be synced with Odoo. Though there is a bit of difference how Odoo handles Opt Out option.

In Odoo you can have same subscriber/contact be opt out of one Mailing List, but opt in another. In MailerLite, there is no such option. You are either Opt In or Opt out fully.

To normalize that, once subscriber is unsubscribed, in Odoo subscriber will be opt out of all related Mailing Lists (groups).

Data synced

Fields that are synced:

• Name
• Email (will be required in Odoo if its MailerLite record)
• Company Name
• Country
• State
• City
• Zip
• Phone

NOTE. Last Name is not synced as in Odoo First and Last names are stored in single Name field.

Campaigns

To send emails MailerLite uses campaigns. In Odoo equivalent is Mailings.

It is possible to fully manage MailerLite campaigns via Odoo. You can send, schedule, cancel MailerLite campaigns directly from Odoo. You can also upload email template using Odoo Mass Mailing templates.

Note. Odoo also has campaigns, but they are used to send multiple emails, so its not equivalent to MailerLite campaigns, which is more simple version of that.

Uploading Campaign

When campaign is created in Odoo, for it to be useable, it must be created on MailerLite. For that click UPLOAD TO MAILERLITE button.

Sending

When you create MailerLite campaign in Odoo, you can either send that email to subscribers immediately or schedule it.

If you send without scheduling, MailerLite still takes few minutes to send it. So in that time, Mailing will be in In Queue state. Once it is sent, if webhook is enabled, it will send updated information indicating that campaign was sent and Odoo will change state to SENT.

If you send with scheduling, Odoo will save schedule date called Scheduled For, to know when to expect that campaign will be sent.

There are some extra options that can be used when sending campaign. If you go to Email Marketing / MailerLite / Campaigns and create new campaign and then open tab called MailerLite, there will be section called Options:

• Campaign Type: currently only Regular is supported, so nothing to choose here.
• Campaign Language: to indicate which language this campaign is for. It is sent to MailerLite as new value. If not set, will use your MailerLite account language.
• Email of Sender: what email to use as sender. Can keep empty to use the one defined in your MailerLite account.
• Name of Sender: What Name to give your email (e.g. Some Name <some@email.com>). leave empty to use the one defined on your account.
• Timezone: used only when scheduling. It is used to convert to different timezone than your account. Can be useful when sending to different timezones than your own.
• HTML Head Title: If set, will add <head>Your Title</head> in your HTML email body.

Uploading Mail Body

Once campaign is created, it is possible to upload your HTML mail body. This step is optional. If you want to manage your templates via MailerLite, you can do that and ignore template on Odoo side.

To upload, there are couple of requirements:

• HTML Template must have head and body tags. This step is done automatically by Connector.
• It must have unsubscribe link with expected variable, like <a href="{$unsubscribe}">Unsubscribe</a>. This is also done automatically, where it replaces Odoo unsubscribe href with expected variable. NOTE. MailerLite expects explicitly that unsubscribe a tag would not have any inner tags, otherwise it won't recognize it. Some Odoo templates have inner tags, which can make upload fail. To fix that, you can enable template HTML editor in Odoo and modify unsubscribe tag by removing inner tags (usually it does not change visuals).
• Must specify Plain body alternative. It can be specified on campaign record in MailerLite tab. Field is called Plain Text Mail. Plain body must have these variables specified (Read More Here): {$unsubscribe}, {$url}. As convenience, there is Plain Text Mail Template field that you can use to autofill it. You can create your own custom plain body templates by going at Email Marketing / Configuration / Plain Text Templates.

Now click button UPLOAD MAIL BODY button. If all is OK, you should see green message pop up at the top right corner, saying Mail Body Uploaded Successfully!. If you need to update your template, you can edit it and click same button again to update on MailerLite.

NOTE. You can only upload template in Draft state.

Data Syncing

There are multiple ways of syncing: push one ore multiple selected records, use sync wizard, use webhooks and or cron jobs.

Metadata

For connector to know which data was synced with which record from MailerLite, it stores some metadata fields. Most important ones are these:

• Is Mailerite Record: this field tells connector that such record must be synced with MailerLite. If this option is not checked, it is treated as normal record and syncing ignores it. If you for some reason need to not sync some records, you can uncheck this option.
• MailerLite ID: this is ID received from MailerLite. It lets connector know exactly to which record it is related on MailerLite side. This value is filled automatically once new record is synced.
• Recently synced: this value indicates whether record was synced recently. If record is modified, it unsets this value. Records with this option set are not pushed to MailerLite, unless explicitly pushed.

Some sync-able documents use not only primary identifier (Is MailerLite Record), but also secondary identifier. This allows to avoid some duplication when syncing. As it first tries to match records without primary identifier by secondary identifier.

Groups and Subscribers use second identifier. Groups second identifier is name field, where for Subscribers, its email field.

Groups & Subscribers

These entities can be synced both ways. You can either pull or push data. It means you can also overwrite data from one system to another. For example if you have same record in Odoo and In MailerLite and if their data differs, depending on your sync action, either Odoo data will be overwritten by MailerLite or vise versa.

Its best to use one strategy, where you keep your main data, instead of changing in both systems, to avoid data overwrite.

Campaigns

Campaigns differ in sync from Groups & Subscribers that MailerLite does not provide endpoints to fully manege bidirectional sync:

• You can only create campaign from Odoo and push it to MailerLite, because MailerLite does not provide a way to fully fetch all campaign data.
• Update works both ways, but it is limited to specific data. You manage full workflow of campaign from Odoo and can receive status updates from MailerLite afterwards, but you can't for example rename campaign (using connector) once it was created.
• Update also depends on campaign state. For example, you can upload HTML template in draft state only or cancel campaign while it is in In Queue (in MailerLite it is Outbox state) state.

Sync Wizard

To manually sync data, you can use synchronization wizard at Email Marketing / MailerLite / Sync.

There you can select what to sync and how to sync. As a precaution, if subscribers are marked for sync, groups will also be marked, to make sure relation stays correct.

There are four ways to sync:

• Pull: fetches data from MailerLite to Odoo, overwriting related records if there are any.
• Push: uploads data to MailerLite from Odoo, overwriting related records if there are any.
• Pull and Push: Pull and Pushed combined in one sync. First overwrite records from MailerLite to Odoo and not synced ones (remaining ones) push to MailerLite.
• Push and Pull: in reverse order of Push and Pull.

Push Filters

• Force Push Create: when pushing record that is not yet related with MailerLite, do not check if there is relation by secondary ID and always create new one. This reduces amount of requests and can be helpful when you know there is no relation (e.g. initially syncing by pushing all your records from Odoo to MailerLite).
• Push Limit: how many records to push. If not set, will try to push all records. Usually should set limit, to not hit MailerLite API limits.
• Filter Push Date & Push From: Sync records that that were updated since specified date. Filter Push Date acts as a helper to set dates some days back.

Pull Filters

• Limit: how many records to fetch in one request from MailerLite.
• Total: how many records to fetch in total.
• Pull Groups Offset, Pull Subscribers Offset, Pull Campaigns Offset: how many oldest records to skip. This can be set manually, when you want to skip some records specifically, but it is also done automatically when searching multiple times. Connector saves last search data to know how many records were found and then changes offset accordingly. It increments offset till all records are found, then offset is reset back to default again, so pull can fully rotate. This option is best combined with recurring cron jobs.

Pull & Push Cron Jobs

To update large amount of data consistently without resorting to manual import/export (and then need to map data between Odoo and MailerLite), it is possible to use cron jobs. There are two cron jobs already created for this purpose (in Odoo they are also called Scheduled Actions)

• MailerLite Exchange: Pull: by default pull 60 records every 2 minutes. This makes sure API limits are not hit.
• MailerLite Exchange: Push: by default force push 59 records every 2 minutes.

You should probably use one or the other cron job, not both at the same time, not overwrite each other. Cron jobs are deactivated by default on purpose.

Fine tuning was done by testing 10000 subscribers with 2 groups. Depending on your data, you might need to tune some of the numbers.

You can find them at Settings / Technical / Automation / Scheduled Actions

MailerLite API Limitations

As any system, MailerLite API has some limitations. It is good to know it, so connector can be used more productively.

According to MailerLite API Rate Limits documentation: "Our API has rate limits, which means that 60 requests on individual endpoints can be made per minute. If this limit is exceeded, you will need to wait until the quota resets."

What it means, is if you try to do many requests in one minute, MailerLite API will block your calls and you will have to wait till quota resets. This makes it hard to sync large amounts of data.

Knowing how many requests can be made per minute, it is possible to configure pull/push filters to not go over those limits. Cron jobs are specifically tuned like that, so you can activate it and leave it to sync data.

Contributors

• Andrius Laukavičius <andrius@timefordev.com>