API – Tilaajat – Creamailer

API:n avulla voidaan lisätä, poistaa sekä päivittää tilaajien tietoja, ajaa bulk-importteja sekä hakea tilaajan koko viestihistoria CRM-integraatioita varten. Tilaajatietojen päivitystä varten tarvittava listan ID löytyy API:n avulla tai Postituslistan asetukset -sivulta.

Kenttien kuvaus

Nimi	Tyyppi	Kirjoitusoikeus	Pakollinen	Tiedot
`id`	integer	ei	ei	Tilaajan id. Muodostetaan automaattisesti tilaajan lisäyksen yhteydessä.
`email`	string	kyllä	kyllä	Sähköpostiosoite. 2-100 merkkiä.
`new_email`	string	kyllä	ei	Uusi sähköpostiosoite (osoitteen vaihtaminen). 2-100 merkkiä. Käytetään vain päivityskutsussa.
`name`	string	kyllä	ei	Tilaajan nimi. 2–100 merkkiä.
`company`	string	kyllä	ei	Yritys. 2–50 merkkiä.
`title`	string	kyllä	ei	Tehtävänimike. 2–50 merkkiä.
`address`	string	kyllä	ei	Lähiosoite. 2–100 merkkiä.
`city`	string	kyllä	ei	Postitoimipaikka. 2–50 merkkiä.
`zip_code`	string	kyllä	ei	Postinumero. 2–5 merkkiä.
`country`	string	kyllä	ei	Maa. 2–20 merkkiä.
`phone`	string	kyllä	ei	Puhelin. 2–20 merkkiä.
`customer_number`	string	kyllä	ei	Asiakasnumero. 1–20 merkkiä.
`send_autoresponders`	boolean	kyllä	ei	Lähetetäänkö postituslistan automaattiset viestit (oletus = false).
`send_autoresponders_if_exists`	boolean	kyllä	ei	Lähetetäänkö automaattiset viestit vaikka tilaaja olisi jo listalla (oletus = false). Päivityskutsussa vaaditaan yhdessä send_autoresponders-arvon kanssa.
`status`	string	osittain	ei	Tilaajan status. API:lla voi asettaa arvot: active = aktiivinen, unsubscribed = perunut uutiskirjeen, deleted = poistettu. Arvoja bounced (virheellinen) ja spamreport (roskapostimerkkaus) ei voi asettaa API:n kautta — ne muodostuvat alustan toimesta automaattisesti. Vastauksissa voivat esiintyä kaikki viisi arvoa.
`custom_fields`	object	kyllä	ei	Personoidut kentät objektina (avain = kentän nimi, arvo = string / number / datetime). Listan custom-kentät voi hakea endpointilla `GET /v2/api/lists/{LISTID}/fields`.
`joined`	datetime	ei	ei	Tilaajan liittymispäivämäärä (YYYY-MM-DD HH:MM:SS). Muodostetaan automaattisesti tilaajan lisäyksen yhteydessä.

Tilaajien lisääminen

Toiminnon avulla voidaan lisätä tilaajia olemassa olevaan postituslistaan. Postituslistan automaattiset viestit lähetetään API-kutsun yhteydessä vain, jos tilaaja on uusi ja kutsun mukana välitetään parametri send_autoresponders arvolla true.

Huom. Jos haluat yhdessä kutsussa joko lisätä uuden tai päivittää olemassa olevan tilaajan, käytä Usean tilaajan lisääminen/päivittäminen -päätepistettä parametrillä "update_existing": true.

Yksittäisen tilaajan lisääminen

{LISTID}: Listan id

POST /v2/api/lists/{LISTID}/subscribers

cURL-esimerkki:

curl -i https://api.cmfile.net/v2/api/lists/{LISTID}/subscribers -H 'X-Access-Token:{ACCESS_TOKEN}' -H 'X-Request-Signature:{REQUEST_SIGNATURE}' -H 'X-Request-Timestamp: {TIMESTAMP}' -H "Content-Type: application/json" -d '{"email":"erkki@esimerkki.com"}' -X POST

Oletettu kutsu (JSON):

{
  "email": "erkki@esimerkki.com",
  "name": "Erkki Esimerkki",
  "company": "Yritys",
  "address": "Mannerheimintie 1",
  "city": "Helsinki",
  "zip_code": "00100",
  "country": "Suomi",
  "phone": "040 123 456",
  "customer_number": "2345",
  "custom_fields": {
    "website": "http://example.com"
  },
  "send_autoresponders": false
}

Oletettu vastaus (JSON):

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

{
  "message": "Subscriber created.",
  "data": {
    "id": 789,
    "email": "erkki@esimerkki.com",
    "name": "Erkki Esimerkki",
    "company": "Yritys",
    "title": "",
    "address": "Mannerheimintie 1",
    "city": "Helsinki",
    "zip_code": "00100",
    "country": "Suomi",
    "phone": "040 123 456",
    "customer_number": "2345",
    "status": "active",
    "joined": "2026-05-15 13:21:20"
  }
}

Mahdolliset virhevastaukset: 409 Conflict kun tilaaja on jo listalla tai sähköposti on estolistalla; 422 Unprocessable Entity validointivirheen tapauksessa (per-kenttä-viestit errors-objektissa).

Usean tilaajan lisääminen/päivittäminen

Toiminnolla voidaan lisätä useita tilaajia samalla kutsulla. Voit antaa kunkin tilaajan tiedoissa "update_existing": true -parametrin, jolloin entuudestaan löytyvän tilaajan tiedot päivitetään yksittäisellä rivillä.

Huom. Bulk-importissa on rajoitus: yhteen API-kutsuun voi sisällyttää enintään 500 sähköpostiosoitetta. Mikäli haluat lisätä tai päivittää suuremman määrän tilaajia, jaa ne useampaan erilliseen kutsuun.

{LISTID}: Listan id

POST /v2/api/lists/{LISTID}/subscribers/import

cURL-esimerkki:

curl -i https://api.cmfile.net/v2/api/lists/{LISTID}/subscribers/import -H 'X-Access-Token:{ACCESS_TOKEN}' -H 'X-Request-Signature:{REQUEST_SIGNATURE}' -H 'X-Request-Timestamp: {TIMESTAMP}' -H "Content-Type: application/json" -d '{"subscribers":[{"email":"erkki@esimerkki.com","name":"Erkki"},{"email":"pentti@esimerkki.com","name":"Pentti"}]}' -X POST

Oletettu kutsu (JSON):

{
  "subscribers": [
    {
      "email": "erkki@esimerkki.com",
      "name": "Erkki Esimerkki",
      "company": "Yritys",
      "address": "Mannerheimintie 1",
      "city": "Helsinki",
      "zip_code": "00100",
      "country": "Suomi",
      "phone": "040 123 456",
      "customer_number": "2345",
      "custom_fields": {
        "website": "http://example.com"
      },
      "send_autoresponders": false,
      "update_existing": true
    },
    {
      "email": "tauno@esimerkki.com",
      "name": "Tauno Esimerkki"
    },
    {
      "email": "pentti@esimerkki.com",
      "name": "Pentti Esimerkki"
    }
  ]
}

Oletettu vastaus (JSON):

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

{
  "message": "Import completed.",
  "data": {
    "subscribers_submitted": 3,
    "subscribers_added": 3,
    "subscribers_updated": 0,
    "subscribers_found": 0,
    "subscribers_duplicate": 0,
    "subscribers_suppressed": 0,
    "subscribers_validation_errors": 0
  }
}

Jos jollain rivillä on virhe, vastauksen data-objektiin sisältyy myös subscribers_error_details-lista:

{
  "message": "Import completed.",
  "data": {
    "subscribers_submitted": 5,
    "subscribers_added": 1,
    "subscribers_updated": 0,
    "subscribers_found": 2,
    "subscribers_duplicate": 1,
    "subscribers_suppressed": 0,
    "subscribers_validation_errors": 1,
    "subscribers_error_details": [
      { "email": "erkki@esimerkki",      "code": 1, "message": "Tarkista sähköpostiosoite." },
      { "email": "erkki@esimerkki.fi",   "code": 2, "message": "Subscriber found." },
      { "email": "pentti@esimerkki.fi",  "code": 2, "message": "Subscriber found." },
      { "email": "tauno@esimerkki.fi",   "code": 3, "message": "Duplicate email." }
    ]
  }
}

Tilaajan tiedot

Toiminnon avulla voidaan hakea yksittäisen tilaajan tiedot sähköpostiosoitteen perusteella. Jos haluat hakea kaikki listan tilaajat, se onnistuu listan toiminnoista.

{LISTID}: Listan id
email: Tilaajan sähköpostiosoite

GET /v2/api/lists/{LISTID}/subscribers/show?email=erkki@esimerkki.com

cURL-esimerkki:

curl -i 'https://api.cmfile.net/v2/api/lists/{LISTID}/subscribers/show?email=erkki@esimerkki.com' -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": {
      "Esimerkkitietue 1": "Esimerkki data 1",
      "Esimerkkitietue 2": "Esimerkki data 2"
    }
  }
}

Tilaajan päivittäminen

Toiminnolla voidaan päivittää yksittäisen tilaajan tiedot. Jos haluat päivittää sähköpostiosoitteen, käytä new_email-parametriä.

Huom. Tunnissa rajapintaan voidaan tehdä vain 100 kutsua. Jos päivität useita tilaajia kerralla (esim. statuksen vaihtaminen), on suositeltavaa käyttää Usean tilaajan lisääminen/päivittäminen -toimintoa "update_existing": true -parametrilla.

{LISTID}: Listan id

PUT /v2/api/lists/{LISTID}/subscribers

cURL-esimerkki:

curl -i https://api.cmfile.net/v2/api/lists/{LISTID}/subscribers -H 'X-Access-Token:{ACCESS_TOKEN}' -H 'X-Request-Signature:{REQUEST_SIGNATURE}' -H 'X-Request-Timestamp: {TIMESTAMP}' -H "Content-Type: application/json" -d '{"email":"erkki@esimerkki.com","name":"Erkki Esimerkki"}' -X PUT

Oletettu kutsu (JSON):

{
  "email": "erkki@esimerkki.com",
  "name": "Erkki Esimerkki",
  "company": "Yritys",
  "address": "Mannerheimintie 1",
  "city": "Helsinki",
  "zip_code": "00100",
  "country": "Suomi",
  "phone": "040 123 456",
  "customer_number": "2345",
  "status": "active",
  "custom_fields": {
    "website": "http://example.com"
  }
}

Sähköpostin vaihto:

{
  "email":     "old@example.com",
  "new_email": "new@example.com"
}

Oletettu vastaus (JSON):

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

{
  "message": "Subscriber updated.",
  "data": { ... tilaajan päivittynyt resurssi ... }
}

Mahdolliset virhevastaukset: 404 jos tilaajaa ei löydy, 409 Conflict jos new_email on jo käytössä tai estolistalla.

Status-suojaus: tilaajia, joiden status on bounced tai spamreport, ei voi muuttaa API:n kautta — tämä suojaa toimitettavuutta.

Tilaajan poistaminen

Toiminnon avulla voidaan poistaa tilaaja aktiivisista tilaajista. Tilaajan statukseksi päivitetään deleted. Tilaajan statuksen päivittämiseen voidaan käyttää Tilaajan päivitys -toimintoa, jossa voit määritellä myös muita statuksia kuten unsubscribed.

Huom. Tunnissa rajapintaan voidaan tehdä vain 100 kutsua. Jos poistat useita tilaajia kerralla, on suositeltavaa käyttää Usean tilaajan lisääminen/päivittäminen -toimintoa "update_existing": true -parametrilla.

{LISTID}: Listan id
email: Tilaajan sähköpostiosoite

DELETE /v2/api/lists/{LISTID}/subscribers?email=erkki@esimerkki.com

cURL-esimerkki:

curl -i 'https://api.cmfile.net/v2/api/lists/{LISTID}/subscribers?email=erkki@esimerkki.com' -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": "Subscriber deleted."
}

Tilaajan viestihistoria (CRM-integraatio)

v2:n uusi endpoint, jolla saa tilaajan koko viestihistorian kaikilta listoilta — jokainen lähetetty kampanja, avaukset, klikit, bounces, unsubscribed sekä suora selaimessa avattava linkki kuhunkin viestiin. Tämä on ihanteellinen sisällyttäväksi CRM-järjestelmään, jotta asiakaspalvelu pystyy näkemään, mitä viestejä yhteyshenkilö on saanut.

email: Tilaajan sähköpostiosoite

Valinnaiset parametrit: pagesize (oletus 20, max 1000), page (oletus 1).

GET /v2/api/subscribers/activity?email=erkki@esimerkki.com&pagesize=20

cURL-esimerkki:

curl -i 'https://api.cmfile.net/v2/api/subscribers/activity?email=erkki@esimerkki.com&pagesize=20' -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": {
    "email": "erkki@esimerkki.com",
    "summary": {
      "total_messages":     46,
      "total_opens":        37,
      "total_clicks":       53,
      "total_bounces":      0,
      "total_unsubscribes": 3,
      "first_message_date": "2021-06-06 17:43:17"
    },
    "messages": {
      "current_page": 1,
      "last_page":    3,
      "data": [
        {
          "campaign_name":   "Maaliskuun uutiskirje",
          "subject":         "Maaliskuun päivitykset",
          "sender_name":     "Yritys Oy",
          "sender_email":    "news@yritys.fi",
          "sent_date":       "2026-03-01 09:00:00",
          "opens":           3,
          "clicks": [
            { "url": "https://yritys.fi/tarjous", "count": 2 }
          ],
          "web_version_url": "https://asiakas.creamailer.fi/email/abc1234567890"
        }
      ],
      "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
      "meta":  { "current_page": 1, "last_page": 3, "per_page": 20, "total": 46 }
    }
  }
}

Vinkki: web_version_url-linkit ovat julkisia (eivät vaadi kirjautumista) ja näyttävät sähköpostin täsmälleen siinä muodossa kuin tilaaja sen sai. Liitä ne CRM-näkymään, niin tukihenkilöt voivat tarkistaa, minkä viestin asiakas on nähnyt.

Tämän osion artikkelit

API – Tilaajat

Kenttien kuvaus

Tilaajien lisääminen

Yksittäisen tilaajan lisääminen

Usean tilaajan lisääminen/päivittäminen

Tilaajan tiedot

Tilaajan päivittäminen

Tilaajan poistaminen

Tilaajan viestihistoria (CRM-integraatio)

Kommentit

Tämän osion artikkelit

Kenttien kuvaus

Tilaajien lisääminen

Yksittäisen tilaajan lisääminen

Usean tilaajan lisääminen/päivittäminen

Tilaajan tiedot

Tilaajan päivittäminen

Tilaajan poistaminen

Tilaajan viestihistoria (CRM-integraatio)

Aiheeseen liittyvät artikkelit