Personalized Newsletters

This section shows the API used to manage newsletters subscribers.

For manual operation, please go on the dedicated page of your Ownpage dashboard.

Tokens

Calls to the Ownpage API are identified by temporary client tokens. Your client token should be put in the header X-Ownpage-Client-Token of all your requests. If your token expire, the API returns a 401 Unauthorized response and you should request a new one.

Get a token

GET https://services.ownpage.fr/v1/token?username=CLIENT&password=API_KEY

With:

Response example:

{
  "token": "78jkhs803lkjh27p081hdlk6m99"
}

New Lists API

This new List API lets you subscribe your users in differents lists and allows you to have several newsletters sent to different populations. To see the former Subscribers API, see here.


Lists

Get all your subscribers lists

GET https://services.ownpage.fr/v1/newsletters/lists
HEADER X-Ownpage-Client-Token

Response example:

[
    {"id":1,"name":"First list","created_at":"2017-06-09T08:48:43.000Z","updated_at":"2017-06-09T08:48:43.000Z"},
    {"id":2,"name":"Other list","created_at":"2017-06-09T09:06:55.000Z","updated_at":"2017-06-09T09:06:55.000Z"}
]

Subscribers

In all the requests below, you must replace the LIST_ID variable by the ID of the List you want to read/update.

Get subscribers count

The end-point to list subscribers is paginated. So you need to get the total number of subscribers first :

GET https://services.ownpage.fr/v1/newsletters/lists/LIST_ID/subscribers/count
HEADER X-Ownpage-Client-Token

Return example in JSON format:

{
    "subscribed" : 12034,
    "unsubscribed" : 83,
    "cause": {
        "HARD_BOUNCE": 30,
        "PUBLISHER": 1,
        "READER": 52
    }
}

Get all subscribers (paginated)

To get subscribers:

GET https://services.ownpage.fr/v1/newsletters/lists/LIST_ID/subscribers?status=STATUS&offset=OFFSET&count=COUNT&search=EMAIL
HEADER X-Ownpage-Client-Token

With the parameters:

Example, to get list in JSON:

curl -H "X-Ownpage-Client-Token:TOKEN" https://services.ownpage.fr/v1/newsletters/lists/LIST_ID/subscribers

Response example:

[
    { "email" : "email1@domaine.fr", "guid": "utilisateur1", "subscribed" : true, "subscribed_at": "2016-..." },
    { "email" : "email2@domaine.fr", "guid": "utilisateur2", "subscribed" : true, "subscribed_at": "2016-..." }
]

Subscription / Unsubscription

To subscribe or unsubscribe users to your personalized newsletter :

POST https://services.ownpage.fr/v1/newsletters/lists/LIST_ID/subscribers
HEADER X-Ownpage-Client-Token

Accepted parameters for a subscriber:

Request example:

curl -X POST --header "X-Ownpage-Client-Token:TOKEN" --header "Content-Type:application/json" --data REQUEST_DATA https://services.ownpage.fr/v1/newsletters/lists/LIST_ID/subscribers

With REQUEST_DATA:

{ 
    "email" : "jean-l@provider.com", 
    "subscribed" : true,
    "guid" : "123456",
    "data_firstname" : "Jean"
}

Response example:

{
    "report": {
        "errors": [],
        "unique_emails_count": 1,
        "duplicate_emails_count": 0,
        "duplicate_guid_count": 0,
        "nb_created": 0,
        "nb_subscribed": 1,
        "nb_unsubscribed": 0,
        "nb_data_changed": 0
    }
}

Response description :

Subscription / Unsubscription by batch

You can handle subscriptions by batch with a maximum of 20 000 lines.

Request json data example:

[
    { "email" : "jean-l@ownpage.fr", "guid" : "123456", "subscribed":true },
    { "email" : "claire-t@ownpage.fr", "guid" : "123457", "subscribed":false, "unsubscribed_cause":"READER" }
]

Subscription with double optin

You can benefit from our double optin mecanism by integrating your HTML forms with our API. Your subscribers will immediately receive a confirmation email and they will receive a follow up email if they have not confirmed after a few days. You need to have a form key first and your tracking key (send an email to support@ownpage.fr).

POST https://services.ownpage.fr/v1/subscribe/TRACKING_KEY

Accepted parameters for a subscriber:

Request example:

curl -X POST --header "Content-Type:application/json" --data REQUEST_DATA https://services.ownpage.fr/v1/subscribe/TRACKING_KEY

With REQUEST_DATA:

{
    "form_key": "YOUR FORM KEY",
    "email": "email@ownpage.fr"
}

Newsletters Events

If you need to track all events related to your newsletters, you can access them using the event API. This is useful if you have a DMP or any analytics tool.

Disclaimer: this is a premium feature, if you need to access newsletters events please contact support@ownpage.fr

Events are stored as CSV files, grouped by event type and event day. Each line of the CSV is an event. Since events are grouped by day, you have to wait midnight to download the full events file of the day. These are all the events we store for you:

Event name Description
nl_click When a newsletter is clicked
nl_display When a newsletter is opened
nl_send When a newsletter is sent to a subscriber
nl_subscribe When a user is subscribed (CSV import, API, optin...)
nl_unsubscribe When a user is unsubscribed (form, import, API...)
nl_bounce When an email has bounced (both soft and hard bounces)
nl_complaint When an email is marked as junk
Event name CSV Columns
nl_click date,email,campaign_id,newsletter_id,email_list_id,target_id,target_url,target_position
nl_display date,email,campaign_id,newsletter_id,email_list_id
nl_send date,email,campaign_id,newsletter_id,email_list_id
nl_subscribe date,email,email_list_id
nl_unsubscribe date,email,cause,email_list_id
nl_bounce date,email,campaign_id,newsletter_id,email_list_id,type,message
nl_complaint date,email,campaign_id,newsletter_id,email_list_id,type
GET https://services.ownpage.fr/v1/newsletters/events/EVENT_NAME/DATE
HEADER X-Ownpage-Client-Token

With the parameters:

Example, to get clicks events in CSV:

curl -H "X-Ownpage-Client-Token:TOKEN" https://services.ownpage.fr/v1/newsletters/events/nl_click/2018-02-15

Response example:

date,email,campaign_id,newsletter_id,email_list_id,target_id,target_url,target_position
2018-02-15 23:51:51,email@ownpage.fr,78,6435,131,5117917,http://www.url.com,8