curl --request POST \
  --url https://api.maildiver.com/v1/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event_name": "user_signed_up",
  "email": "user@example.com",
  "properties": {
    "user": {
      "profile": {
        "tier": "pro",
        "is_verified": true,
        "credits": 100
      }
    },
    "signup_source": "landing_page",
    "referral_code": "MAILDIVER2025",
    "accepted_terms": true
  }
}
'

{
  "status": "processed",
  "event_id": "0199f234-d327-7cd8-9dc5-4fd8e5e249df",
  "timestamp": "2024-03-15T10:30:45.123Z"
}

Automation Event

Send event

Endpoint: v1/events

Send an event to trigger automation workflows. Events are matched against workflow triggers based on the event name and optional conditions.

Deduplication: Workflows have deduplication enabled by default with a 5-minute window. If the same event for the same email is sent within this time window, the duplicate event will be ignored and return a deduplicated status response. This prevents accidentally triggering the same workflow multiple times for the same user.

You can configure deduplication settings when creating workflows in the dashboard (up to 30 days maximum window).

curl --request POST \
  --url https://api.maildiver.com/v1/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event_name": "user_signed_up",
  "email": "user@example.com",
  "properties": {
    "user": {
      "profile": {
        "tier": "pro",
        "is_verified": true,
        "credits": 100
      }
    },
    "signup_source": "landing_page",
    "referral_code": "MAILDIVER2025",
    "accepted_terms": true
  }
}
'

{
  "status": "processed",
  "event_id": "0199f234-d327-7cd8-9dc5-4fd8e5e249df",
  "timestamp": "2024-03-15T10:30:45.123Z"
}

Authorizations

Authorization

string

header

required

API key with format "Bearer {your-api-key}"

Body

application/json

event_name

string

required

Name of the event to trigger.

Required, non-empty string
Maximum 100 characters
Automatically normalized to lowercase and trimmed

Maximum string length: 100

Example:

"user_signed_up"

email

string<email>

required

Contact's email address

Maximum string length: 255

Example:

"recipient@example.com"

properties

object

Event properties used for workflow condition matching and email personalization.

Workflow Conditions: Properties enable dynamic workflow branching based on condition rules. Each property can be evaluated using:

Comparison: equals, not_equals, greater_than, less_than
Text matching: contains, not_contains, begins_with, ends_with
Existence: exists, not_exists

Multiple rules can be combined with AND/OR logic for complex conditions.

Supported Types:

Strings: "pro", "landing_page"
Numbers: 99.99, 1
Booleans: true, false
Arrays: ["item1", "item2"]

Nested Properties: Use dot notation to access nested values (e.g., "user.profile.tier").

Example Use Case: Send different welcome emails based on subscription plan:

If plan equals "pro" → send premium welcome email
If plan equals "free" → send standard welcome email

Example:

{
  "plan": "pro",
  "signup_source": "landing_page"
}

Response

Event successfully processed or deduplicated

Update contact List workflows