Webhooks

Webhooks notify external systems about events in mail2many. For specific events, an external URL is called, for example on opt-in confirmation or unsubscribe.

As a developer, you can use webhooks to synchronize your system. For example, you can use opt-in events for your CRM or opt-out events to remove contacts from your own list.

Create webhooks

Webhooks can be created in account settings (admin role required). When creating a webhook, you define:

• Name – A unique name for the webhook
• Events – Which events should trigger the webhook
• Target URL – The URL that should be called

An account can have multiple webhooks with different events and URLs:

Account 1 (Customer A)
│
├─ Webhook 1: "CRM Sync"
│  ├─ Events: optin, optin_additional_channels
│  └─ URL: https://crm.example.com/webhook
│
├─ Webhook 2: "Unsubscribe Handler"
│  ├─ Events: optout, optout_individual_channels
│  └─ URL: https://app.example.com/unsubscribe
│
└─ Webhook 3: "Analytics"
   ├─ Events: optin, optout
   └─ URL: https://analytics.example.com/events

info

Important: You can use the same URL for multiple events or configure different URLs per event. The URL must be publicly reachable, secured via HTTPS, and accept POST requests.

Secret & validation

After creation, mail2many displays a webhook secret. It is shown only once and must be stored securely — treat it like a password.

info

Security: The X-Mail2Many-Signature header is used for authentication. It contains an HMAC-SHA256 signature generated from the request body and the secret. Always compare the computed signature with the header value to verify the authenticity of the incoming call.

Request format

When an event occurs, mail2many sends a POST request to the configured URL.

HTTP-Header

The most important headers:

• X-Mail2Many-Account-Id – Account ID
• X-Mail2Many-Event – Event type
• X-Mail2Many-Event-Date – Timestamp (UTC)
• X-Mail2Many-Event-Id – Unique event ID
• X-Mail2Many-Signature – HMAC signature for validation

JSON-Payload

The JSON payload contains basic information:

• accountId – Account ID
• event – Event type
• date – Event timestamp

Additional fields depend on the event (for example subscriber data). Details for each event are listed below.

Verify signature

To verify webhook authenticity, validate the HMAC signature using your secret.

Beispiel: PHP

$secret = 'your_webhook_secret';

$headers = getallheaders();

$payload = file_get_contents('php://input');

$signature = $headers['X-Mail2many-Signature'] ?? '';

$computedSignature = hash_hmac('sha256', $payload, $secret);

if (hash_equals($computedSignature, $signature)) {

    // Request is authentic
    $data = json_decode($payload, true);

    // Process webhook data
    http_response_code(200);
    exit;
} else {

    // Request is not authentic
    http_response_code(401);
    exit;
}

Security notes

Webhook metadata (event ID, timestamp, event, signature) is included in HTTP headers. This lets you verify authenticity before parsing the body. It helps reject invalid requests early and follows common platform best practices.

Best Practices:

• Validate the signature using the raw body.
• Check the allowed time window (Event-Date).
• Ensure the event ID is not processed twice (prevent replay attacks).
• The URL must be publicly reachable and return a 2xx status code.

info

Important: If your URL is unreachable or does not return a 2xx response, the webhook is retried multiple times and eventually marked as failed.

Available events

mail2many currently supports the following webhook events:

Event	Name	Description
optin	Opt-in confirmation	Subscriber was inactive, confirms opt-in, and is now active.
optin_additional_channels	Opt-in confirmation (additional channels)	Subscriber was already active in at least one channel and confirms opt-in for additional channels.
optout	Full unsubscribe	Subscriber was active, unsubscribes from all channels, and is now inactive.
optout_individual_channels	Unsubscribe (individual channels)	Subscriber unsubscribes from individual channels but remains active in at least one channel.

Event payloads

All events use the same base payload with the following fields:

Key	Description	Example
accountId	ID of the account where the event occurred.	1
event	Event type.	optin
date	Event timestamp (UTC).	2025-11-27 09:52:31
email	Subscriber email address.	john.doe@example.com
title	Academic title.	Dr.
firstname	First name.	John
lastname	Last name.	Doe
genderId	Gender: 1=male, 2=female, 3=non-binary, 4=not specified.	1
ip	IP address at event time.	192.168.1.1
channelIds	IDs of channels that were subscribed/unsubscribed.	[1, 2]
newsletterId	Newsletter ID.	1
newsletterSubject	Newsletter subject.	Welcome to our newsletter!

Additional events may be added in the future. For special requirements, please contact support.