Our Email Webhooks API enables developers to configure and manage webhook endpoints for real-time email event notifications. The API provides comprehensive webhook management capabilities including webhook registration, retrieval, and deletion for various email event types.

Permissions Required

To access Email Webhooks API endpoints, the user must have valid permissions associated with their account:

  • EmailWebhook_Create - Required for creating and updating webhook configurations
  • EmailWebhook_Read - Required for reading webhook configurations
  • EmailWebhook_Delete - Required for deleting webhook configurations

Fact Sheet

FeatureSupportRemark
Webhook RegistrationYesRegister webhook endpoints for real-time email event notifications
Multiple Webhook TypesYesSupport for 7 different webhook types (delivered, opened, click, etc.)
Webhook Type ManagementYesRetrieve and manage different webhook types per account
Account-based OrganizationYesWebhooks are organized by logical account IDs
Webhook URL ValidationYesValidate webhook URLs during registration
Webhook DeletionYesRemove webhook configurations by type

Managing Email Webhooks

The Email Webhooks API allows you to register webhook endpoints to receive real-time notifications for email events such as deliveries, bounces, clicks, and opens. Each webhook is associated with a logical account and webhook type.

Webhook Configuration

Create/Update Webhook Configuration

Register a new webhook or update an existing webhook configuration for email event notifications.

POST /v1/accounts/{logicalAccountId}/create
Content-Type: application/json

Path Parameters

ParameterTypeRequiredDescription
logicalAccountIdUUIDYesThe logical account identifier

Request Headers

Header NameTypeRequiredDescription
Content-TypestringYesMust be "application/json"
AuthorizationstringYesValid authorization token

Request Body Example

{
  "webhookType": "delivered",
  "webhookUrl": "https://your-domain.com/webhook/email-events"
}

Successful Response (200)

{
  "isSuccess": true,
  "statusCode": "Ok",
  "message": "Successfully created/updated webhook with id 123",
  "data": 123
}

Error Responses

Invalid Request Body (400)

{
  "isSuccess": false,
  "statusCode": "InvalidRequest",
  "message": "Request body is not valid",
  "data": 0
}

Invalid Account ID (400)

{
  "isSuccess": false,
  "statusCode": "InvalidRequest", 
  "message": "Logical account id is not valid",
  "data": 0
}

Invalid Webhook Type (400)

{
  "isSuccess": false,
  "statusCode": "InvalidRequest",
  "message": "Webhook type is not valid",
  "data": 0
}

Invalid Webhook URL (400)

{
  "isSuccess": false,
  "statusCode": "InvalidRequest",
  "message": "Provide a valid url for webhook",
  "data": 0
}

Get Webhook Configuration

Retrieve webhook configuration for a specific account and webhook type.

GET /v1/accounts/{logicalAccountId}/list?webhookType={webhookType}

Path Parameters

ParameterTypeRequiredDescription
logicalAccountIdUUIDYesThe logical account identifier

Query Parameters

ParameterTypeRequiredDescription
webhookTypestringNoSpecific webhook type to retrieve (e.g., "delivered", "bounces")

Successful Response - Specific Webhook (200)

{
  "isSuccess": true,
  "statusCode": "Ok", 
  "message": "Successfully retrieved webhook for account 903e1cef-84b3-4500-a9a5-b2ca219f76f5 and type delivered",
  "data": {
    "webhookType": "delivered",
    "url": "https://your-domain.com/webhook/email-events"
  }
}

Successful Response - No Webhook Found (200)

{
  "isSuccess": true,
  "statusCode": "Ok",
  "message": "No webhook found for account 903e1cef-84b3-4500-a9a5-b2ca219f76f5 and type delivered",
  "data": null
}

Successful Response - Webhook Types (200)

When webhookType is empty or "-1", returns available webhook types:

{
  "isSuccess": true,
  "statusCode": "Ok",
  "message": "Successfully retrieved webhook type for account 903e1cef-84b3-4500-a9a5-b2ca219f76f5",
  "data": "global"
}

Error Responses

Invalid Account ID (400)

{
  "isSuccess": false,
  "statusCode": "InvalidRequest",
  "message": "Invalid account ID provided",
  "data": null
}

Webhook Not Found (404)

{
  "isSuccess": false,
  "statusCode": "NotFound",
  "message": "Webhook type not found",
  "data": null
}

Delete Webhook Configuration

Remove a webhook configuration for a specific account and webhook type.

DELETE /v1/accounts/{logicalAccountId}/delete?webhookType={webhookType}

Path Parameters

ParameterTypeRequiredDescription
logicalAccountIdUUIDYesThe logical account identifier

Query Parameters

ParameterTypeRequiredDescription
webhookTypestringYesWebhook type to delete (e.g., "delivered", "bounces", "click")

Successful Response (200)

{
  "statusCode": "Ok",
  "statusMessage": "Successfully deleted 1 webhook(s)"
}

No Webhook Found Response (200)

{
  "statusCode": "Ok", 
  "statusMessage": "No webhook found to delete"
}

Error Responses

Invalid Account ID (400)

{
  "statusCode": "InvalidRequest",
  "statusMessage": "Invalid account ID provided"
}

Invalid Webhook Type (400)

{
  "statusCode": "InvalidRequest",
  "statusMessage": "Webhook type is not valid"
}

Webhook Types

The system supports the following webhook types for different email events:

Webhook TypeEnum ValueDescriptionEvents Included
global0All email eventsAll email events in single webhook
delivered1Successful email deliveriesEmail delivered to recipient's inbox
opened2Email opensRecipient opened the email
click3Email link clicksRecipient clicked on email links
bounces4Email bounces (hard and soft)Failed delivery attempts
unsubscribes5Unsubscribe eventsRecipient unsubscribed
spamreports6Spam complaintsEmail marked as spam

Request Parameters

Webhook Configuration Request Body Fields

FieldTypeRequiredDescription
webhookTypestringYesType of webhook: "global", "delivered", "opened", "click", "bounces", "unsubscribes", "spamreports"
webhookUrlstringYesHTTPS URL endpoint to receive webhook notifications

Webhook Response Object

FieldTypeDescription
webhookTypestringType of webhook events
urlstringConfigured webhook endpoint URL

Webhook URL Requirements

RequirementDescription
ProtocolMust use HTTPS for security
AccessibilityMust be publicly accessible from CM servers
ResponseShould respond with 200 status for successful receipt

Status Codes

Status CodeDescription
200OK: Request processed successfully
400Bad Request: Invalid request data or parameters
404Not Found: Requested webhook not found
500Internal Server Error: Server-side error

Webhook Event Payload Structure

When events occur, webhooks will receive POST requests with payloads like:

{
  "eventType": "delivered",
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "recipient": "[email protected]",
  "sender": "[email protected]",
  "timestamp": "2024-03-15T10:30:00Z",
  "accountId": "903e1cef-84b3-4500-a9a5-b2ca219f76f5",
  "eventData": {
    "subject": "Welcome to our service",
    "status": "delivered",
    "deliveryTime": "2024-03-15T10:30:00Z"
  }
}

Best Practices

  1. HTTPS Only: Always use HTTPS URLs for webhook endpoints to ensure data security
  2. Idempotency: Design webhook handlers to be idempotent as events may be delivered multiple times
  3. Quick Response: Respond quickly (within 30 seconds) with HTTP 200 status to acknowledge receipt
  4. Error Handling: Implement proper error handling and logging in webhook endpoints
  5. Authentication: Consider implementing webhook signature validation for additional security

Example Use Cases

Email Delivery Tracking

Configure a webhook to track successful email deliveries:

{
  "webhookType": "delivered",
  "webhookUrl": "https://your-app.com/webhooks/email-delivery"
}

Bounce Management

Set up bounce handling for email list hygiene:

{
  "webhookType": "bounces", 
  "webhookUrl": "https://your-app.com/webhooks/bounce-handler"
}

Engagement Tracking - Opens

Track email opens for analytics:

{
  "webhookType": "opened",
  "webhookUrl": "https://analytics.your-app.com/email-opens"
}

Engagement Tracking - Clicks

Track email clicks for analytics:

{
  "webhookType": "click",
  "webhookUrl": "https://analytics.your-app.com/email-clicks"
}

Unsubscribe Management

Handle unsubscribe events:

{
  "webhookType": "unsubscribes",
  "webhookUrl": "https://your-app.com/webhooks/unsubscribe-handler"
}

Spam Report Monitoring

Monitor spam complaints:

{
  "webhookType": "spamreports",
  "webhookUrl": "https://your-app.com/webhooks/spam-reports"
}

Global Event Handler

Receive all email events in a single webhook:

{
  "webhookType": "global",
  "webhookUrl": "https://your-app.com/webhooks/all-email-events"
}

Comprehensive Multi-Webhook Setup Example

Configure different webhooks for different event types:

# Delivery tracking
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
  "webhookType": "delivered",
  "webhookUrl": "https://your-app.com/webhooks/delivered"
}

# Bounce management
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
  "webhookType": "bounces",
  "webhookUrl": "https://your-app.com/webhooks/bounces"
}

# Open tracking
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
  "webhookType": "opened",
  "webhookUrl": "https://analytics.your-app.com/email-opens"
}

# Click tracking
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
  "webhookType": "click",
  "webhookUrl": "https://analytics.your-app.com/email-clicks"
}

# Unsubscribe handling
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
  "webhookType": "unsubscribes",
  "webhookUrl": "https://your-app.com/webhooks/unsubscribes"
}

# Spam report monitoring
POST /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/create
{
  "webhookType": "spamreports",
  "webhookUrl": "https://your-app.com/webhooks/spam-reports"
}