Creamailer REST API – Quick Guide for Developers

1. Base URL & Versioning

The current stable endpoint is:

https://api.cmfile.net/v1/api

Breaking changes will appear under new version paths (/v2/, /v3/, …).

2. Rate Limits

• 100 requests per hour per account.
• If the limit is exceeded the API returns HTTP 400 and a Retry-After header (seconds to wait).

3. Transport & Data Formats

• HTTPS only.
• Request & response body: UTF-8 encoded JSON.
• Select the response format via the Accept header (application/json, application/xml, application/php) or by appending an extension (e.g. /lists.json).

4. Authentication & Request Signature

1. Create an Access Token and Shared Secret under Settings → API in Creamailer.
2. For every call compute a SHA-1 hash:
   signature = sha1(API_URL + route + json_body + unix_timestamp + shared_secret)
3. Send these headers with each request:

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

Example (PHP)

$signature = sha1(
  'https://api.cmfile.net/v1/api/lists.json' .
  '{"name":"My list","language":"fi","auto_suppress":true}' .
  time() .
  $sharedSecret
);

5. Endpoints

All endpoints accept/return .json, .xml, or .php (serialized). Examples below use JSON.

5.1 Mailing Lists (/lists)

Field definitions: id (int, auto), name (2–50 chars), language (fi, en, es …), auto_suppress (bool).

5.2 Subscribers (/subscribers)

Important fields: email (required), name, status (active, unsubscribed, bounced, spamreport, deleted), custom fields array.

5.3 Suppression List (/suppressions)

Optional reason: unsubscribed, bounced, spamreport, deleted.

6. Retrieving a List ID

Inside the Creamailer UI: Mailing Lists → select list → More actions → Settings, then copy the numeric “ID” field.

7. Error Handling

• 200 OK / 201 Created – success
• 400 Bad Request – validation error or rate-limit; check body
• 401 Unauthorized – invalid token or signature
• 404 Not Found – wrong path or ID
• 5xx – temporary service error (retry with back-off)

8. Example cURL – Create a List

curl -i https://api.cmfile.net/v1/api/lists.json \
  -H "X-Access-Token:${ACCESS_TOKEN}" \
  -H "X-Request-Signature:${REQUEST_SIGNATURE}" \
  -H "X-Request-Timestamp:${TIMESTAMP}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"My new list","language":"en","auto_suppress":true}' \
  -X POST

Successful response:

{
  "success": true,
  "message": "List added",
  "id": "1234"
}

9. Client Implementation Tips

1. Calculate the request signature inside your integration code (e.g., JavaScript, Python, PHP).
2. If your workload might exceed 100 requests/hour, implement throttling, queuing, or exponential back-off.
3. Store Access Token and Shared Secret in environment variables or a secrets-manager; never commit them to source control.
4. Paginate large subscriber fetches using the pagesize and page parameters.
5. When a response includes Retry-After, pause for the indicated seconds before retrying.

10. Need More?

• Join the Creamailer API mailing list for change notifications.
• SDKs and additional language samples are available in the Creamailer Support Center.