Skip to main content

​
Overview

AutoSend webhooks support three categories of events:
  1. Email Lifecycle Events - Track email sending and delivery
  2. Email Engagement Events - Track how recipients interact with your emails
  3. Email Subscription Events - Track unsubscribe and resubscribe actions
  4. Contact Events - Track changes to your contact database
All webhook payloads follow this structure: 
{
  "type": "event.type",
  "createdAt": "2025-11-12T10:30:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "from": "sender@yourdomain.com",
    "to": {
      "email": "user@example.com",
      "name": "John Doe"
    },
    "subject": "Email Subject",
    "test": false,
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2",
    "templateId": "64f1a2b3c4d5e6f7g8h9i0j4",
    "workflowAutomationId": "64f1a2b3c4d5e6f7g8h9i0j5",
    "batchId": "64f1a2b3c4d5e6f7g8h9i0j6"
    // Additional event-specific fields
  }
}
Common Fields (for most email events):
  • emailId - Unique identifier for the email activity
  • from - Sender email address
  • to - Recipient object containing email and name
  • subject - Email subject line
  • test - Boolean indicating if this is a test email (true) or production (false)
  • campaignId - Campaign identifier (optional)
  • templateId - Template identifier (optional)
  • workflowAutomationId - Workflow automation identifier (optional)
  • batchId - Batch identifier (optional)
Note: Subscription events (email.unsubscribed, email.group_unsubscribed, email.group_resubscribed) and contact events have different structures for privacy reasons. See individual event details below.

​
Supported Event Types

Email Lifecycle:
  • email.sent - Email successfully sent to the recipient’s mail server
  • email.delivered - Email successfully delivered
  • email.deferred - Email delivery temporarily delayed
  • email.bounced - Email failed to deliver
Email Engagement:
  • email.opened - Recipient opened the email
  • email.clicked - Recipient clicked a link in the email
  • email.spam_reported - Recipient marked email as spam
Email Subscription:
  • email.unsubscribed - Recipient unsubscribed globally from all emails
  • email.group_unsubscribed - Recipient unsubscribed from a specific email group
  • email.group_resubscribed - Recipient resubscribed to a specific email group
Contact Management:
  • contact.created - New contact created
  • contact.updated - Contact information updated
  • contact.deleted - Contact deleted

​
Email Lifecycle Events

​
email.sent

Triggered when an email is successfully sent to the recipient’s mail server via SES.
Sample Payload:
{
  "type": "email.sent",
  "createdAt": "2025-11-12T10:00:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "from": "sender@yourdomain.com",
    "to": {
      "email": "user@example.com",
      "name": "John Doe"
    },
    "subject": "Welcome to AutoSend",
    "test": false,
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2",
    "templateId": "64f1a2b3c4d5e6f7g8h9i0j4",
    "workflowAutomationId": "64f1a2b3c4d5e6f7g8h9i0j5",
    "batchId": "64f1a2b3c4d5e6f7g8h9i0j6"
  }
}
Data Fields:
  • emailId - Unique identifier for the email activity
  • from - Sender email address
  • to - Recipient object with email and name
  • subject - Email subject line
  • test - Boolean indicating whether this is a test email (true) or production (false)
  • campaignId - Campaign ID (optional, if sent as part of a campaign)
  • templateId - Template ID used for the email (optional)
  • workflowAutomationId - Workflow automation ID (optional, if sent from automation)
  • batchId - Batch ID (optional, if sent as part of a batch)
Use Cases:
  • Track when emails are successfully accepted by SES
  • Monitor email sending activity
  • Trigger follow-up workflows after email dispatch

​
email.delivered

Triggered when AutoSend successfully delivers an email to the recipient’s mail server.
Sample Payload:
{
  "type": "email.delivered",
  "createdAt": "2025-11-12T10:15:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "from": "sender@yourdomain.com",
    "to": {
      "email": "user@example.com",
      "name": "John Doe"
    },
    "subject": "Welcome to AutoSend",
    "test": false,
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2",
    "templateId": "64f1a2b3c4d5e6f7g8h9i0j4",
    "workflowAutomationId": "64f1a2b3c4d5e6f7g8h9i0j5",
    "batchId": "64f1a2b3c4d5e6f7g8h9i0j6"
  }
}
Data Fields:
  • emailId - Unique identifier for the email activity
  • from - Sender email address
  • to - Recipient object with email and name
  • subject - Email subject line
  • test - Boolean indicating whether this is a test email (true) or production (false)
  • campaignId - Campaign ID (optional, if applicable)
  • templateId - Template ID used (optional)
  • workflowAutomationId - Workflow automation ID (optional, if sent from automation)
  • batchId - Batch ID (optional, if sent as part of a batch)
Use Cases:
  • Confirm successful email delivery
  • Update delivery status in your database
  • Track delivery times and patterns

​
email.deferred

Triggered when email delivery is temporarily delayed by the recipient’s mail server.
Sample Payload:
{
  "type": "email.deferred",
  "createdAt": "2025-11-12T10:10:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "from": "sender@yourdomain.com",
    "to": {
      "email": "user@example.com",
      "name": "John Doe"
    },
    "subject": "Welcome to AutoSend",
    "test": false,
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2",
    "templateId": "64f1a2b3c4d5e6f7g8h9i0j4",
    "workflowAutomationId": "64f1a2b3c4d5e6f7g8h9i0j5",
    "batchId": "64f1a2b3c4d5e6f7g8h9i0j6",
    "delayType": "InternalFailure",
    "delayReason": "Temporary connection failure",
    "expirationTime": "2025-11-12T14:10:00.000Z"
  }
}
Data Fields:
  • emailId - Unique identifier for the email activity
  • from - Sender email address
  • to - Recipient object with email and name
  • subject - Email subject line
  • test - Boolean indicating whether this is a test email (true) or production (false)
  • campaignId - Campaign ID (optional, if applicable)
  • templateId - Template ID used (optional)
  • workflowAutomationId - Workflow automation ID (optional, if sent from automation)
  • batchId - Batch ID (optional, if sent as part of a batch)
  • delayType - Type of delay, e.g., “InternalFailure”, “MailboxFull” (optional)
  • delayReason - Human-readable explanation of the delay (optional)
  • expirationTime - ISO 8601 timestamp when delivery attempts will stop (optional)
Use Cases:
  • Monitor temporary delivery issues
  • Track mail server responsiveness
  • Alert on persistent deferral patterns

​
email.bounced

Triggered when an email bounces (fails to deliver).
Sample Payload:
{
  "type": "email.bounced",
  "createdAt": "2025-11-12T10:20:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "from": "sender@yourdomain.com",
    "to": {
      "email": "invalid@example.com",
      "name": "Invalid User"
    },
    "subject": "Welcome to AutoSend",
    "test": false,
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2",
    "templateId": "64f1a2b3c4d5e6f7g8h9i0j4",
    "workflowAutomationId": "64f1a2b3c4d5e6f7g8h9i0j5",
    "batchId": "64f1a2b3c4d5e6f7g8h9i0j6",
    "bounceType": "Permanent",
    "bounceSubType": "General",
    "reason": "550 5.1.1 The email account that you tried to reach does not exist"
  }
}
Data Fields:
  • emailId - Unique identifier for the email activity
  • from - Sender email address
  • to - Recipient object with email and name
  • subject - Email subject line
  • test - Boolean indicating whether this is a test email (true) or production (false)
  • campaignId - Campaign ID (optional, if applicable)
  • templateId - Template ID used (optional)
  • workflowAutomationId - Workflow automation ID (optional, if sent from automation)
  • batchId - Batch ID (optional, if sent as part of a batch)
  • bounceType - Bounce classification: “Permanent” or “Transient” (optional)
  • bounceSubType - Detailed bounce category, e.g., “General”, “NoEmail”, “Suppressed” (optional)
  • reason - Human-readable bounce reason from the mail server (optional)
Bounce Types:
  • Permanent: Hard bounce - invalid email address, domain doesn’t exist
  • Transient: Soft bounce - mailbox full, server temporarily unavailable
Use Cases:
  • Remove hard bounced emails from your list
  • Retry soft bounces later
  • Monitor bounce rates for sender reputation

​
Email Engagement Events

​
email.opened

Triggered when a recipient opens an email.
Sample Payload:
{
  "type": "email.opened",
  "createdAt": "2025-11-12T10:30:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "from": "sender@yourdomain.com",
    "to": {
      "email": "user@example.com",
      "name": "John Doe"
    },
    "subject": "Welcome to AutoSend",
    "test": false,
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2",
    "templateId": "64f1a2b3c4d5e6f7g8h9i0j4",
    "workflowAutomationId": "64f1a2b3c4d5e6f7g8h9i0j5",
    "batchId": "64f1a2b3c4d5e6f7g8h9i0j6"
  }
}
Data Fields:
  • emailId - Unique identifier for the email activity
  • from - Sender email address
  • to - Recipient object with email and name
  • subject - Email subject line
  • test - Boolean indicating whether this is a test email (true) or production (false)
  • campaignId - Campaign ID (optional, if applicable)
  • templateId - Template ID used (optional)
  • workflowAutomationId - Workflow automation ID (optional, if sent from automation)
  • batchId - Batch ID (optional, if sent as part of a batch)
Privacy Note: This event does NOT include ipAddress, userAgent, device, or location information for privacy protection.Use Cases:
  • Track email engagement rates
  • Identify best send times
  • Segment engaged vs unengaged contacts

​
email.clicked

Triggered when a recipient clicks a link in an email.
Sample Payload:
{
  "type": "email.clicked",
  "createdAt": "2025-11-12T10:35:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "from": "sender@yourdomain.com",
    "to": {
      "email": "user@example.com",
      "name": "John Doe"
    },
    "subject": "Welcome to AutoSend",
    "test": false,
    "clickedUrl": "https://example.com/product",
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2",
    "templateId": "64f1a2b3c4d5e6f7g8h9i0j4",
    "workflowAutomationId": "64f1a2b3c4d5e6f7g8h9i0j5",
    "batchId": "64f1a2b3c4d5e6f7g8h9i0j6"
  }
}
Data Fields:
  • emailId - Unique identifier for the email activity
  • from - Sender email address
  • to - Recipient object with email and name
  • subject - Email subject line
  • test - Boolean indicating whether this is a test email (true) or production (false)
  • clickedUrl - The URL that was clicked (optional)
  • campaignId - Campaign ID (optional, if applicable)
  • templateId - Template ID used (optional)
  • workflowAutomationId - Workflow automation ID (optional, if sent from automation)
  • batchId - Batch ID (optional, if sent as part of a batch)
Privacy Note: This event does NOT include ipAddress, userAgent, or device information for privacy protection.Use Cases:
  • Track which links are most popular
  • Identify highly engaged contacts
  • Trigger follow-up campaigns based on clicked links

​
email.spam_reported

Triggered when a recipient marks an email as spam or files a complaint.
Sample Payload:
{
  "type": "email.spam_reported",
  "createdAt": "2025-11-12T10:45:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "from": "sender@yourdomain.com",
    "to": {
      "email": "user@example.com",
      "name": "John Doe"
    },
    "subject": "Welcome to AutoSend",
    "test": false,
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2",
    "templateId": "64f1a2b3c4d5e6f7g8h9i0j4",
    "workflowAutomationId": "64f1a2b3c4d5e6f7g8h9i0j5",
    "batchId": "64f1a2b3c4d5e6f7g8h9i0j6",
    "complaintType": "abuse"
  }
}
Data Fields:
  • emailId - Unique identifier for the email activity
  • from - Sender email address
  • to - Recipient object with email and name
  • subject - Email subject line
  • test - Boolean indicating whether this is a test email (true) or production (false)
  • campaignId - Campaign ID (optional, if applicable)
  • templateId - Template ID used (optional)
  • workflowAutomationId - Workflow automation ID (optional, if sent from automation)
  • batchId - Batch ID (optional, if sent as part of a batch)
  • complaintType - Type of complaint: “abuse”, “fraud”, “virus”, “other” (optional)
Use Cases:
  • Automatically suppress emails that file complaints
  • Monitor spam complaint rates
  • Improve email content and targeting to reduce complaints
  • Protect sender reputation

​
Email Subscription Events

​
email.unsubscribed

Triggered when a recipient globally unsubscribes from all emails.
Sample Payload:
{
  "type": "email.unsubscribed",
  "createdAt": "2025-11-12T10:40:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "test": false,
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2",
    "templateId": "64f1a2b3c4d5e6f7g8h9i0j4",
    "workflowAutomationId": "64f1a2b3c4d5e6f7g8h9i0j5",
    "batchId": "64f1a2b3c4d5e6f7g8h9i0j6"
  }
}
Data Fields:
  • emailId - Unique identifier for the email activity (optional - only present if triggered from an email)
  • test - Boolean indicating whether this is a test email (true) or production (false)
  • campaignId - Campaign ID (optional - only present if triggered from a campaign email)
  • templateId - Template ID (optional - only present if triggered from an email)
  • workflowAutomationId - Workflow automation ID (optional - only present if triggered from automation email)
  • batchId - Batch ID (optional - only present if triggered from batch email)
Important Notes:
  • This event does NOT include from, to, or subject fields for privacy protection
  • Fields like emailId, campaignId, templateId, workflowAutomationId, and batchId are optional and only present when the unsubscribe is triggered from an email context
Use Cases:
  • Automatically remove contacts from all mailing lists
  • Update contact preferences in your CRM
  • Track global unsubscribe reasons for analytics
  • Ensure compliance with email regulations

​
email.group_unsubscribed

Triggered when a recipient unsubscribes from a specific email group or suppression group (but not all emails).
Sample Payload:
{
  "type": "email.group_unsubscribed",
  "createdAt": "2025-11-12T10:42:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "test": false,
    "unsubscribeGroupId": "newsletter-marketing",
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2",
    "templateId": "64f1a2b3c4d5e6f7g8h9i0j4",
    "workflowAutomationId": "64f1a2b3c4d5e6f7g8h9i0j5",
    "batchId": "64f1a2b3c4d5e6f7g8h9i0j6"
  }
}
Data Fields:
  • emailId - Unique identifier for the email activity (optional - only present if triggered from an email)
  • test - Boolean indicating whether this is a test email (true) or production (false)
  • unsubscribeGroupId - The specific group ID they unsubscribed from (optional)
  • campaignId - Campaign ID (optional - only present if triggered from a campaign email)
  • templateId - Template ID (optional - only present if triggered from an email)
  • workflowAutomationId - Workflow automation ID (optional - only present if triggered from automation email)
  • batchId - Batch ID (optional - only present if triggered from batch email)
Important Notes:
  • This event does NOT include from, to, or subject fields for privacy protection
  • Fields like emailId, campaignId, templateId, workflowAutomationId, and batchId are optional and only present when the unsubscribe is triggered from an email context
Use Cases:
  • Remove contacts from specific mailing lists or segments
  • Allow granular subscription management
  • Track which email categories users opt out of
  • Maintain subscriber preferences across different email types

​
email.group_resubscribed

Triggered when a recipient resubscribes to a specific email group they previously unsubscribed from.
Sample Payload:
{
  "type": "email.group_resubscribed",
  "createdAt": "2025-11-12T11:00:00.000Z",
  "data": {
    "emailId": "64f1a2b3c4d5e6f7g8h9i0j1",
    "test": false,
    "unsubscribeGroupId": "newsletter-marketing",
    "campaignId": "64f1a2b3c4d5e6f7g8h9i0j2"
  }
}
Data Fields:
  • emailId - Unique identifier for the email activity (optional)
  • test - Boolean indicating whether this is a test email (true) or production (false)
  • unsubscribeGroupId - The specific group ID they resubscribed to (optional)
  • campaignId - Campaign ID (optional)
Important Notes:
  • This event does NOT include from, to, or subject fields for privacy protection
Use Cases:
  • Re-add contacts to specific mailing lists
  • Track re-engagement patterns
  • Update subscription preferences in your CRM
  • Resume sending specific types of emails to the contact

​
Contact Events

​
contact.created

Triggered when a new contact is created in your AutoSend project.
Sample Payload:
{
  "type": "contact.created",
  "createdAt": "2025-11-12T09:00:00.000Z",
  "data": {
    "contactId": "64f1a2b3c4d5e6f7g8h9i0j3",
    "email": "newuser@example.com",
    "name": "John Doe"
  }
}
Data Fields:
  • contactId - Unique identifier for the contact (optional)
  • email - Contact’s email address (optional)
  • name - Contact’s name (optional)
Note: Additional custom fields may be included based on your contact schema.Use Cases:
  • Sync new contacts to your CRM
  • Trigger welcome email sequences
  • Update analytics dashboards
  • Initialize contact tracking in external systems

​
contact.updated

Triggered when an existing contact’s information is updated.
Sample Payload:
{
  "type": "contact.updated",
  "createdAt": "2025-11-12T09:30:00.000Z",
  "data": {
    "contactId": "64f1a2b3c4d5e6f7g8h9i0j3",
    "email": "user@example.com",
    "name": "Jonathan Doe",
    "changedFields": ["name"]
  }
}
Data Fields:
  • contactId - Unique identifier for the contact (optional)
  • email - Contact’s email address (optional)
  • name - Contact’s name (optional)
  • changedFields - List of field names that were changed (optional)
Note: Additional custom fields may be included based on your contact schema.Use Cases:
  • Keep contact data synchronized across systems
  • Track contact lifecycle changes
  • Trigger workflows based on specific field changes
  • Update contact profiles in external databases

​
contact.deleted

Triggered when a contact is deleted from your AutoSend project.
Sample Payload:
{
  "type": "contact.deleted",
  "createdAt": "2025-11-12T09:45:00.000Z",
  "data": {
    "contactId": "64f1a2b3c4d5e6f7g8h9i0j3",
    "email": "deleteduser@example.com"
  }
}
Data Fields:
  • contactId - Unique identifier for the deleted contact (optional)
  • email - Contact’s email address for reference (optional)
Use Cases:
  • Remove contacts from external systems
  • Update contact counts and analytics
  • Maintain data consistency across platforms
  • Ensure GDPR/privacy compliance in external systems

​
Event Handling Examples

app.post("/webhooks/autosend", async (req, res) => {
  const { type, data } = req.body;

  switch (type) {
    case "email.sent":
      await handleEmailSent(data);
      break;

    case "email.delivered":
      await handleEmailDelivered(data);
      break;

    case "email.deferred":
      await handleEmailDeferred(data);
      break;

    case "email.opened":
      await handleEmailOpened(data);
      break;

    case "email.clicked":
      await handleEmailClicked(data);
      break;

    case "email.bounced":
      await handleEmailBounced(data);
      break;

    case "email.spam_reported":
      await handleSpamReport(data);
      break;

    case "email.unsubscribed":
      await handleGlobalUnsubscribe(data);
      break;

    case "email.group_unsubscribed":
      await handleGroupUnsubscribe(data);
      break;

    case "email.group_resubscribed":
      await handleGroupResubscribe(data);
      break;

    case "contact.created":
      await handleContactCreated(data);
      break;

    case "contact.updated":
      await handleContactUpdated(data);
      break;

    case "contact.deleted":
      await handleContactDeleted(data);
      break;

    default:
      console.log(`Unhandled event: ${type}`);
  }

  res.status(200).json({ received: true });

});

​
Get Available Events via API

You can programmatically fetch the list of available events: 
curl -X GET https://api.autosend.io/v1/webhooks/events/available \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-project-id: YOUR_PROJECT_ID"
Response: 
{
  "success": true,
  "data": {
    "events": [
      "email.sent",
      "email.delivered",
      "email.deferred",
      "email.opened",
      "email.clicked",
      "email.bounced",
      "email.spam_reported",
      "email.unsubscribed",
      "email.group_unsubscribed",
      "email.group_resubscribed",
      "contact.created",
      "contact.updated",
      "contact.deleted"
    ]
  }
}

Introduction

Getting started with webhooks

Retries and Replays

Automatic retry logic and best practices

Verify Webhook Requests

Security and signature verification

Webhooks

Manage your webhooks from the AutoSend sidebar