Skip to content

Synchronize your contacts

Learn how to do a proper script to synchronize your contacts between your Opper Mail contact list and your own database.

The recommended solution is to consider your database as the source of truth and replicate new subscriptions and new unsubscriptions to the Opper Mail database. The steps are the following :

  • Extract all subscribers from Opper Mail database
  • Extract all subscribers from your database
  • Subscribe in Opper Mail the users which are subscribed in your database, but not in Opper Mail's
  • Unsubscribe in Opper Mail the users which are subscribed in Opper Mail's database, but not in your's

The code bellow is an example and should be adjusted to match your needs. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
require 'rest-client'
require 'json'

CLIENT_NAME = "your_client_name"
API_KEY = "your_api_key"
LIST_ID = "your_list_id"

OWNPAGE_API_PREFIX = "https://services.ownpage.fr/v1"
MAX_USERS_IN_BATCH = 10000

# Get a token
token_response = RestClient::Request.execute(method: :get, url: "#{OWNPAGE_API_PREFIX}/token?username=#{CLIENT_NAME}&password=#{API_KEY}")
token = JSON.parse(token_response)['token']

# Get the number of subscribed users
subscribers_count_response = RestClient::Request.execute(
    method: :get, 
    url: "#{OWNPAGE_API_PREFIX}/newsletters/lists/#{LIST_ID}/subscribers/count",
    headers: {'X-Ownpage-Client-Token' => token}
)
subscribers_count = JSON.parse(subscribers_count_response)['subscribed']

# Get subscribed users in Opper Mail database
ownpage_subscribers = []
offset = 0
while offset < subscribers_count
    subscribers_request = RestClient::Request.execute(
        method: :get, 
        url: "#{OWNPAGE_API_PREFIX}/newsletters/lists/#{LIST_ID}/subscribers?status=subscribed&offset=#{offset}&count=#{MAX_USERS_IN_BATCH}",
        headers: {'X-Ownpage-Client-Token' => token}
    )

    # We just keep the email address and we store it in the ownpage_subscribers array
    ownpage_subscribers += JSON.parse(subscribers_request).map{|subscriber| subscriber['email']}

    offset += MAX_USERS_IN_BATCH
end

# You must implement this function depending on your needs
# We will assume that the result is an array of email addresses
local_subscribers = get_subscribed_users_from_your_database()

# Find users to subscribe and unsubsribe by substracting arrays
to_subscribe = local_subscribers - ownpage_subscribers
to_unsubscribe = ownpage_subscribers - local_subscribers

# Format data and put everything together
data_to_send_to_ownpage = to_subscribe.map{|email| {email: email, subscribed: true}} + to_unsubscribe.map{|email| {email: email, subscribed: false}}

# Send data to Ownpage API by batch of 10k users
data_to_send_to_ownpage.each_slice(MAX_USERS_IN_BATCH) do |slice_of_data_to_send|
    response = RestClient::Request.execute(
        method: :post, 
        url: "#{OWNPAGE_API_PREFIX}/newsletters/lists/#{LIST_ID}/subscribers",
        headers: {
            'X-Ownpage-Client-Token' => token,
            accept: :json,
            content_type: :json
        },
        payload: slice_of_data_to_send.to_json
    )

    # You can log and/or use the response to track what has been done (number of subscribed, unsubscribed...)
    puts response.body
end

Warning

Using this solution, your newsletter must have a unsubscription link pointing to your website and directly updating your database.

Subscribe/Unsubscribe users without checking the diff

You could call the Opper Mail API as soon as a user subscribe or unsubscribe on your website. This solution could work just fine but you would need to be very careful about error handling.

Warning

If for any reason, a request made to the Opper Mail's API fails, you should be able to retry the action until it succeeds. If done badly, the risk is to desynchronize the two databases. E.g.: your system calls Opper Mail API to unsubscribe a user but it fails and does not retry : we will still send emails to this user despite being unsubscribed in your database.

Remove everything from Opper Mail's list then duplicate your database

A quick way to sync your Opper Mail's list with your database would be to clean everything from Opper Mail list before loading again every subscribed users. That way, you are certain that the Opper Mail's database is same as your's, and you don't have to get every subscribers from Opper Mail to make a complicated diff.

The problem

Deleting subscribers each time will also delete attached data, like the dates at which the user has opened or clicked in your newsletter. You will loose behavioral information on your subscribers, and the ability to filter based on subscribers activity (eg: send only to users who have opened a newsletter in the last 30 days)

Let Opper Mail do the job

We are able to automatically synchronize your contact list with any of these Email Service Providers / Identity Management Platforms :

  • Mailjet
  • Mailchimp
  • Smartfocus
  • Gigya

If you are using one these, feel free to contact support-ownpage@opper.io to setup your integration.

Comments