Creamailer REST API – Developer Quick Start Guide

1. Base URL & Versioning

The current stable endpoint is:

https://api.cmfile.net/v2/api

Version v1 (https://api.cmfile.net/v1/api) is still available for backwards compatibility, but all new integrations should use v2.

Version v2 introduces:

• HMAC-SHA256 request signatures
• typed error responses
• bulk imports
• subscriber activity
• custom-field metadata

2. Rate Limits

The API allows 100 requests per hour per API key.

If the limit is exceeded, the API returns HTTP 429 Too Many Requests.

To avoid issues, implement request queuing or exponential back-off in your integration.

3. Transport & Data Formats

• HTTPS is required for all requests
• Request and response bodies must be UTF-8 encoded JSON
• Always include Content-Type: application/json for POST and PUT requests

4. Authentication & Request Signature

Create an Access Token and Shared Secret in Creamailer under Settings → API.

For each request, calculate an HMAC-SHA256 signature:

signature = HMAC-SHA256(base_url + "/" + path + query_string + body + timestamp, shared_secret)

Send the following headers with every request:

X-Access-Token: <ACCESS_TOKEN>
X-Request-Signature: <signature>
X-Request-Timestamp: <unix_timestamp>

Signature components:

• base_url = https://api.cmfile.net (no trailing slash)
• path = e.g. v2/api/lists (without leading slash)
• query_string includes the leading ? or is empty
• body is the raw JSON string (empty for GET and DELETE)
• timestamp must be a Unix timestamp within ±5 minutes of server time

To debug your implementation, call:

GET /v2/api/connection-test

A successful response returns:

{"message":"Connection successful."}

Example (PHP)

$timestamp = (string) time();
$body      = '{"name":"My list","language":"fi","auto_suppress":true}';
$data      = 'https://api.cmfile.net' . '/' . 'v2/api/lists' . '' . $body . $timestamp;
$signature = hash_hmac('sha256', $data, $sharedSecret);

5. Endpoints

All endpoints return JSON. Paths are relative to https://api.cmfile.net.

5.1 Mailing Lists (/lists)

• Get all: GET /v2/api/lists
• Get one: GET /v2/api/lists/{LIST_ID}
• Create list: POST /v2/api/lists
  Body: {"name":"List name","language":"fi","auto_suppress":true}
• Update: PUT /v2/api/lists/{LIST_ID}
• Delete: DELETE /v2/api/lists/{LIST_ID}
• Custom fields: GET /v2/api/lists/{LIST_ID}/fields

Field definitions:

• id (integer, auto-generated)
• name (2–50 characters)
• language (fi, en, es …)
• auto_suppress (boolean)

5.2 Subscribers

• List subscribers: GET /v2/api/lists/{LIST_ID}/subscribers
  Optional parameters: status, pagesize, page, date
• Get one: GET /v2/api/lists/{LIST_ID}/subscribers/show?email=user@example.com
• Add one: POST /v2/api/lists/{LIST_ID}/subscribers
  Body: {"email":"user@example.com"}
• Update one: PUT /v2/api/lists/{LIST_ID}/subscribers
• Delete / unsubscribe: DELETE /v2/api/lists/{LIST_ID}/subscribers?email=user@example.com
• Bulk add/update: POST /v2/api/lists/{LIST_ID}/subscribers/import
• Activity: GET /v2/api/subscribers/activity?email=user@example.com

Maximum 500 entries can be sent in one bulk import request. Use "update_existing": true to update existing subscribers.

Important fields:

• email (required)
• name
• status (active, unsubscribed, deleted)
• custom_fields (object)

The following statuses are read-only and set automatically:

• bounced
• spamreport

These cannot be assigned via the API.

5.3 Suppression List (/suppressions)

• List addresses: GET /v2/api/suppressions
• Add address: POST /v2/api/suppressions
  Body: {"email":"user@example.com"}
• Remove address: DELETE /v2/api/suppressions?email=user@example.com

Reason values:

• unsubscribed
• bounced
• spamreport
• deleted

6. Retrieving a List ID

From the Creamailer UI:

Mailing Lists → select list → More actions → Settings → copy the "ID"

Via API:

GET /v2/api/lists

7. Error Handling

• 200 OK / 201 Created – success
• 401 Unauthorized – invalid token, signature, or timestamp
• 403 Forbidden – insufficient permissions or inactive account
• 404 Not Found – invalid endpoint or resource
• 409 Conflict – duplicate subscriber or suppressed email
• 422 Unprocessable Entity – validation error with field-level messages
• 429 Too Many Requests – rate limit exceeded
• 5xx – temporary server error

8. Example cURL – Create a List

TOKEN="your-access-token"
SECRET="your-shared-secret"
BASE_URL="https://api.cmfile.net"
PATH="v2/api/lists"
TIMESTAMP=$(date +%s)
BODY='{"name":"My new list","language":"en","auto_suppress":true}'

DATA="${BASE_URL}/${PATH}${BODY}${TIMESTAMP}"
SIGNATURE=$(echo -n "$DATA" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -i "${BASE_URL}/${PATH}" \
  -H "X-Access-Token: ${TOKEN}" \
  -H "X-Request-Signature: ${SIGNATURE}" \
  -H "X-Request-Timestamp: ${TIMESTAMP}" \
  -H "Content-Type: application/json" \
  -d "$BODY" \
  -X POST

Successful response:

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

{
  "message": "List created.",
  "data": {
    "id": 1234,
    "name": "My new list",
    "language": "en",
    "auto_suppress": true,
    "created": "2026-05-15 09:00:00"
  }
}

9. Client Implementation Tips

• Use the official PHP SDK if integrating with PHP
• Calculate request signatures in your application code
• Implement throttling or queuing for rate limits
• Store credentials securely using environment variables or a secrets manager
• Use pagination with pagesize and page; the maximum pagesize is 1000
• Split bulk imports larger than 500 rows into multiple requests

10. Need More?

• Join the Creamailer API mailing list for updates
• See detailed documentation: Postituslistat, Tilaajat, Estolista
• Signature examples: API-tarkistesumman laskeminen