Skip to main content
Automation workflows are typically used for:
  • Welcome emails when users sign up
  • Onboarding drip campaigns
  • Abandoned cart reminders
  • Re-engagement campaigns
  • Post-purchase follow-ups
  • Event-triggered notifications

​
How automation workflows work

Automation workflows are event-driven. When you send an event via API, MailDiver checks if there are any active workflows configured for that event and creates an execution.
  1. Your application sends an event (e.g., user_signed_up) via the API
  2. MailDiver finds all active workflows configured for that event
  3. An execution is created for each workflow
  4. The workflow steps are executed in order (send email, wait, conditional logic, etc.)
  5. Emails are sent to the contact with personalized data
Multiple workflows can be triggered by the same event. Each workflow creates a separate execution.

​
Step-by-step guide

​
Step 1. Create a workflow in the dashboard

Workflows can only be created in the MailDiver dashboard. You cannot create workflows via API - this is intentional to ensure workflows are properly designed and tested. In the workflow builder, you can:
  • Configure the trigger event (e.g., user_signed_up, purchase_completed)
  • Add steps: Send Email, Wait, Conditional Split
  • Use contact properties for personalization and conditions

​
Step 2. Send an event via API to trigger the workflow

Once your workflow is active, send events from your application to trigger it: 
const response = await fetch('https://api.maildiver.com/v1/events', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer your-api-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_name: 'user_signed_up',
    email: 'user@example.com',
    properties: {
      first_name: 'John',
      plan: 'pro',
      signup_date: '2024-01-15',
    },
  }),
});
The properties object contains contact metadata that can be used in your email templates and workflow conditions. These properties are merged with existing contact data. You can also update contact properties directly via the Update Contact API without triggering workflows.

​
Step 3. Monitor executions and emails

After sending events, you can monitor workflow executions in the MailDiver dashboard:
  • View all executions for a workflow
  • See the current step each execution is on
  • Check execution status: IN_PROGRESS, WAITING, COMPLETED, FAILED, or CANCELLED
  • Review sent emails and their delivery status
You don’t need to know any API if you use the MailDiver dashboard. Everything can be monitored visually. The API is available for programmatic access if needed.
If you need programmatic access, use the API: 
// List executions for a workflow
GET / v1 / workflows / { workflow_id } / executions;

// Get specific execution details
GET / v1 / executions / { execution_id };

// List emails sent during an execution
GET / v1 / executions / { execution_id } / emails;

​
Step 4. How unsubscribe works

Include the {{ unsubscribe_url }} variable in your email templates: 
<a
  href="{{ unsubscribe_url }}"
  style="color: #3b82f6; text-decoration: underline;"
>
  Unsubscribe
</a>
When a contact clicks the unsubscribe link:
  1. They are immediately unsubscribed from that specific workflow
  2. All active executions for that contact+workflow are automatically cancelled
  3. The cancellation_reason is set to “User unsubscribed from workflow”
  4. Future events will not trigger that workflow for this contact
Unsubscribe is workflow-specific. If a contact unsubscribes from “Welcome Email” workflow, they can still receive emails from other workflows like “Purchase Confirmation”.

​
Contact properties and personalization

Contact properties are merged using deep merge with null deletion:
  • Omitted fields: Preserved unchanged
  • Fields with values: Updated or added
  • Fields set to null: Explicitly deleted
  • Nested objects: Recursively merged (not replaced)
  • Arrays: Replaced entirely
Example - updating a contact’s plan: 
// First event creates contact
{
  event_name: 'user_signed_up',
  email: 'user@example.com',
  properties: {
    first_name: 'John',
    plan: 'free'
  }
}

// Later event updates plan (first_name is preserved)
{
  event_name: 'plan_upgraded',
  email: 'user@example.com',
  properties: {
    plan: 'pro'
  }
}

// Result: { first_name: 'John', plan: 'pro' }
You can also update contact properties via the API without triggering workflows: 
PATCH / v1 / automation / contacts / { email };
For more details about contact property updates and deep merge behavior, see the API Reference.

​
Key concepts

  • Events trigger workflows: Send events from your application to automatically trigger workflows
  • One contact, multiple executions: A single contact can have multiple executions (different workflows, or same workflow triggered multiple times)
  • Automatic cancellation: Executions are automatically cancelled when a user unsubscribes
  • Contact properties persist: Properties sent with events are stored and can be used across all workflows
  • Dashboard-only workflow creation: Workflows can only be created in the dashboard for safety and proper design
That’s it! You now understand how automation workflows work in MailDiver.
⌘I