Skip to content

Create and update subscribers

Subscribes or unsubscribes a user or multiple users to a given subscriber list

Endpoint URI

1
POST https://services.ownpage.fr/v1/newsletters/lists/LIST_ID/subscribers

Endpoint parameters

  • LIST_ID : the email list you want to modify

Headers

  • X-Ownpage-Client-Token : a valid token

Payload (JSON)

The data should be a JSON array of subscribers. Each subscribers can have these parameters :

  • email : (mandatory) the user's email address
  • subscribed : (true|false) the status subscribed/unsubscribed. If not provided or invalid value :
    • If the email address is already in your list : the status is not changed
    • If not in your list : the address is subscribed
  • unsubscribed_cause : unsubscription cause (READER: reader decision, PUBLISHER: publisher decision), used when subscribed = false. Default value is READER
  • guid : the ID of the user in your database. This id must match the one used in navigation tracking. If not provided, the value of the guid is md5(email)

  • data_* : you can attach additional data to your subscribers using parameters prefixed by data_. Example : data_firstname

    Payload is limited to 20.000 users per request.

Response

The response is a summary of what has been done during the call. You can find different information, such as :

  • errors : errors detected in your payload
  • unique_emails_count : number of unique subscribers found in the payload
  • duplicate_emails_count : number of subscribers ignored because their address is present several times in the payload
  • duplicate_guid_count : number of subscribers ignored because their guid is present several times in the payload
  • nb_created : number of newly created subscribers
  • nb_subscribed : number of users subscribed by your request (including new and re-subscribed users)
  • nb_unsubscribed : number of users unsubscribed by your request
  • nb_data_changed : number of users which had their data attributes (first_name, last_name...) changed by your request

Example

We add a new subscribed user to the list with id #123

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

With REQUEST_DATA:

1
2
3
4
5
6
[{ 
    "email" : "jean-l@provider.com", 
    "subscribed" : true,
    "guid" : "123456",
    "data_firstname" : "Jean"
}]

Response: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "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
    }
}

Comments