API - Postituslistat

API:n avulla voidaan lisätä, poistaa sekä päivittää postituslistoja, hakea listan tilaajat sekä lukea listan custom-kenttien skeema.

Kenttien kuvaus

Listan lisääminen

Toiminnon avulla luodaan postituslista, johon voidaan myöhemmin lisätä tilaajia. Listalle annetaan nimi ja kieli sekä määritellään, lisätäänkö listalta peruneet sähköpostiosoitteet estolistalle, jolloin niihin ei lähetetä viestejä jatkossa (suositus).

Halutessasi voit lisäksi määrittää, ohitetaanko listalla estolista (disable_suppression). Oletuksena estolistaa ei ohiteta. API:lla luotu lista saa muuten samat asetukset kuin Creamailerissa luotu lista.

Huom. Kun disable_suppression on true, estolistalla olevat osoitteet hyväksytään listalle, kun tilaajia lisätään, päivitetään tai tuodaan API:lla tai tuodaan Creamailerissa, ja listalle (myös sen segmenteille) lähetetyt viestit lähetetään myös niille. Julkinen tilauslomake, tilauksen vahvistus (double opt-in) ja API v1 noudattavat estolistaa asetuksesta riippumatta. Käytä asetusta vain, kun vastaanottajilla on varmasti voimassa oleva lupa.

POST /v2/api/lists

cURL-esimerkki:

curl -i https://api.cmfile.net/v2/api/lists -H 'X-Access-Token:{ACCESS_TOKEN}' -H 'X-Request-Signature:{REQUEST_SIGNATURE}' -H 'X-Request-Timestamp: {TIMESTAMP}' -H "Content-Type: application/json" -d '{"name":"Listan nimi","language":"fi","auto_suppress":true,"disable_suppression":false}' -X POST

Oletettu kutsu (JSON):

{
  "name": "Listan nimi",
  "language": "fi",
  "auto_suppress": true,
  "disable_suppression": false,
  "remove_bounced_automatically": true,
  "allow_resubscribe": true
}

Oletettu vastaus (JSON):

HTTP/1.1 201 Created
Content-Type: application/json

{
  "message": "List created.",
  "data": {
    "id": 1234,
    "name": "Listan nimi",
    "language": "fi",
    "auto_suppress": true,
    "disable_suppression": false,
    "remove_bounced_automatically": true,
    "allow_resubscribe": true,
    "created": "2026-05-15 10:37:22"
  }
}

Listan tiedot

Toiminnon avulla voit hakea listan perustiedot.

Yksittäinen lista

{LISTID}: Listan id

GET /v2/api/lists/{LISTID}

cURL-esimerkki:

curl -i https://api.cmfile.net/v2/api/lists/{LISTID} -H 'X-Access-Token:{ACCESS_TOKEN}' -H 'X-Request-Signature:{REQUEST_SIGNATURE}' -H 'X-Request-Timestamp: {TIMESTAMP}' -X GET

Oletettu vastaus (JSON):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": 1234,
    "name": "My list",
    "language": "fi",
    "auto_suppress": true,
    "disable_suppression": false,
    "remove_bounced_automatically": true,
    "allow_resubscribe": true,
    "created": "2013-09-13 10:37:22"
  }
}

Kaikki listat

GET /v2/api/lists

cURL-esimerkki:

curl -i https://api.cmfile.net/v2/api/lists -H 'X-Access-Token:{ACCESS_TOKEN}' -H 'X-Request-Signature:{REQUEST_SIGNATURE}' -H 'X-Request-Timestamp: {TIMESTAMP}' -X GET

Oletettu vastaus (JSON):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 1234,
      "name": "My list",
      "language": "fi",
      "auto_suppress": true,
      "disable_suppression": false,
      "remove_bounced_automatically": true,
      "allow_resubscribe": true,
      "created": "2013-09-14 10:37:22"
    },
    ...
  ]
}

Listan päivittäminen

Toiminnon avulla voidaan päivittää listan nimi sekä sen asetuksia.

{LISTID}: Listan id

PUT /v2/api/lists/{LISTID}

cURL-esimerkki:

curl -i https://api.cmfile.net/v2/api/lists/{LISTID} -H 'X-Access-Token:{ACCESS_TOKEN}' -H 'X-Request-Signature:{REQUEST_SIGNATURE}' -H 'X-Request-Timestamp: {TIMESTAMP}' -H "Content-Type: application/json" -d '{"name":"Listan nimi","language":"fi","auto_suppress":true,"disable_suppression":false}' -X PUT

Oletettu kutsu (JSON):

{ "name": "Listan nimi", "language": "fi", "auto_suppress": true, "disable_suppression": false }

Kaikki kentät ovat valinnaisia päivityksessä — lähetä vain ne, joita haluat muuttaa. Esimerkiksi estolistan ohituksen saa päälle kutsulla:

{ "disable_suppression": true }

Oletettu vastaus (JSON):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "List updated.",
  "data": {
    "id": 1234,
    "name": "Listan nimi",
    "language": "fi",
    "auto_suppress": true,
    "disable_suppression": false,
    "remove_bounced_automatically": true,
    "allow_resubscribe": true,
    "created": "2013-09-13 10:37:22"
  }
}

Listan custom-kentät

v2 tarjoaa oman endpointin, jolla voi hakea listalle määritellyt personoidut kentät (custom fields) ja niiden tyypit. Vastauksen name-arvot ovat samat, joilla custom-arvot annetaan tilaajan custom_fields-objektissa.

{LISTID}: Listan id

GET /v2/api/lists/{LISTID}/fields

Oletettu vastaus (JSON):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "id": 1, "name": "department", "type": "string" },
    { "id": 2, "name": "birthday",   "type": "date" }
  ]
}

Listan tilaajat

Hae postituslistan tilaajat. Polku on muuttunut v2:ssa REST-tyyliseksi.

{LISTID}: Listan id

Valinnaiset parametrit

• status: Tilaajien status jotka halutaan hakea, oletus all (all = kaikki, active = aktiiviset, unsubscribed = peruneet, bounced = virheelliset, spamreport = roskapostiksi merkanneet, deleted = poistettu ylläpidosta)
• pagesize: Montako riviä palautetaan per sivu, oletus 100, maksimi 1000
• page: Sivu jolta tiedot palautetaan, oletus 1
• date: Päivämäärä jonka jälkeen lisätyt tilaajat halutaan hakea (YYYY-MM-DD), ei pakollinen

GET /v2/api/lists/{LISTID}/subscribers?status={all|active|unsubscribed|bounced|spamreport|deleted}&pagesize=100&page=1&date=2024-12-24

cURL-esimerkki:

curl -i 'https://api.cmfile.net/v2/api/lists/{LISTID}/subscribers?status=active&pagesize=100&page=1&date=2024-12-24' -H 'X-Access-Token:{ACCESS_TOKEN}' -H 'X-Request-Signature:{REQUEST_SIGNATURE}' -H 'X-Request-Timestamp: {TIMESTAMP}' -X GET

Oletettu vastaus (JSON):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 789,
      "email": "erkki@esimerkki.com",
      "name": "Erkki Esimerkki",
      "company": "Esimerkki Oy",
      "title": "Toimitusjohtaja",
      "address": "Mannerheimintie 1",
      "city": "Helsinki",
      "zip_code": "00100",
      "country": "Suomi",
      "phone": "010 123 456",
      "customer_number": "123456",
      "status": "active",
      "joined": "2013-02-13 13:49:42",
      "custom_fields": {
        "department": "Sales",
        "birthday":   "1990-05-20"
      }
    },
    ...
  ],
  "custom_fields_schema": {
    "1": "department",
    "2": "birthday"
  },
  "links": {
    "first": "https://api.cmfile.net/v2/api/lists/1234/subscribers?page=1",
    "last":  "https://api.cmfile.net/v2/api/lists/1234/subscribers?page=12",
    "prev":  null,
    "next":  "https://api.cmfile.net/v2/api/lists/1234/subscribers?page=2"
  },
  "meta": {
    "current_page": 1,
    "last_page":    12,
    "per_page":     100,
    "total":        1187
  }
}

Huom. v2:ssa custom_fields palautuu objektina (avain = kentän nimi) eikä enää avain-arvo-objektien listana.

Vastaus on aina sivutettu — käytä links.next-osoitetta tai kasvata page-parametria käydäksesi kaikki sivut läpi.

Listan poistaminen

Postituslistan poistaminen toiminnon avulla.

{LISTID}: Listan id

DELETE /v2/api/lists/{LISTID}

cURL-esimerkki:

curl -i https://api.cmfile.net/v2/api/lists/{LISTID} -H 'X-Access-Token:{ACCESS_TOKEN}' -H 'X-Request-Signature:{REQUEST_SIGNATURE}' -H 'X-Request-Timestamp: {TIMESTAMP}' -X DELETE

Oletettu vastaus (JSON):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "List removed."
}