01 · Quick start

Your first subscriber in one request.

Copy your API token from the panel: Account → API.
Send it in the Authorization header as a bearer token, with Accept: application/json.
Take the list UID from the list page in the panel (or from GET /api/v1/lists) and add a subscriber.

Base URL: https://app.mailcraft.eu/api/v1
Auth: Authorization: Bearer <token>
Format: JSON responses; form or JSON bodies

POST /api/v1/subscribers

curl -X POST https://app.mailcraft.eu/api/v1/subscribers \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -d list_uid=YOUR_LIST_UID \
  -d EMAIL=jane@example.com \
  -d FIRST_NAME=Jane \
  -d tag=shop,newsletter

If the list uses double opt-in, the subscriber gets the confirmation email first.

02 · REST API

What you can do over the API.

The full reference with every parameter is in the panel - log in and open the API documentation.

Lists

List, create and delete mailing lists, add custom fields.

Subscribers

Add, update, find by email, tag, subscribe, unsubscribe and delete.

Campaigns

List and create campaigns, pause and resume, download open, click, bounce and unsubscribe logs.

Automations

List automations and start the ones triggered by an API call.

Webhooks

Add, list and remove webhook endpoints of your account.

Full API reference (after login) →

03 · Webhooks

Events pushed to your app, signed.

Add an HTTPS address in the panel and MailCraft sends a JSON POST for every event on your account: all lists, campaigns and automations, usually within a minute.

subscriber.subscribed: someone joined a list (form, API, confirmation, shop integration)
subscriber.unsubscribed: someone left a list
email.opened: a recipient opened an email
email.clicked: a recipient clicked a link
email.bounced: an email bounced
email.complained: a recipient marked an email as spam

HMAC-SHA256 signature in X-MailCraft-Signature, with a timestamp against replays

X-MailCraft-Delivery stays the same across retries, so you can drop duplicates

Retries after 1 min, 5 min, 30 min, 2 h and 8 h when your server does not answer 2xx

An endpoint that keeps failing is switched off and you get an email about it

No code of your own? Paste the address of a Zapier or Make webhook trigger

Set up webhooks in the panel →

Payload

{
  "id": "01k6c3v9m2x8q4r7t5y1w0z3ab",
  "event": "email.clicked",
  "occurred_at": "2026-09-30T10:15:02+00:00",
  "data": {
    "subscriber": {"email": "jane@example.com", "status": "subscribed"},
    "list": {"uid": "6a14...", "name": "Newsletter"},
    "source": {"type": "campaign", "name": "September", "subject": "News"},
    "url": "https://your-shop.com/sale"
  }
}

Verify the signature (PHP)

$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_MAILCRAFT_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', $sig['t'] . '.' . $body, getenv('MAILCRAFT_WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) $sig['t']) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);   // $event['event'], $event['data']
http_response_code(200);

04 · Webhooks over the API

Subscribe and unsubscribe from your code.

Integrations that switch themselves on and off can add their own webhook address when a user connects and remove it when they disconnect. Same token, same rules as in the panel: up to 5 endpoints, HTTPS only.

GET /api/v1/webhooks

your endpoints (secrets are never listed)

POST /api/v1/webhooks

add an endpoint: url + events (a list or "*"); the answer carries the secret

GET /api/v1/webhooks/{uid}

one endpoint

DELETE /api/v1/webhooks/{uid}

remove an endpoint

GET /api/v1/webhooks/events

event names

GET /api/v1/webhooks/samples?event=...

latest real payloads of that event, or a sample in the same shape

POST /api/v1/webhooks

curl -X POST https://app.mailcraft.eu/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.com/mailcraft", "events": ["subscriber.subscribed", "email.bounced"]}'

# 201 -> {"data": {"uid": "01k6...", "events": [...], "secret": "whsec_..."}}

Build on MailCraft with plain HTTP.

Your first subscriber in one request.

What you can do over the API.

Events pushed to your app, signed.

Subscribe and unsubscribe from your code.

Building something bigger?