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ö mahdolliset virheelliset sähköpostiosoitteet estolistalle, jolloin niihin ei lähetetä viestejä jatkossa (suositus).

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}' -X POST

Oletettu kutsu (JSON):

{
  "name": "Listan nimi",
  "language": "fi",
  "auto_suppress": 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,
    "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,
    "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,
      "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}' -X PUT

Oletettu kutsu (JSON):

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

Kaikki kentät ovat valinnaisia päivityksessä — lähetä vain ne, joita haluat muuttaa.

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,
    "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."
}