Skip to main content
Mailrify can send real-time HTTP requests to your application when specific events occur, such as email bounces, spam complaints, or custom events. This is done by creating a workflow that uses the Webhook step to forward event data to your own endpoint.

​
How it works

Webhooks in Mailrify are powered by the workflow system. The basic flow is:
  1. An event occurs in Mailrify (e.g. an email bounces, a contact subscribes, or a custom event is tracked)
  2. A workflow is triggered by that event
  3. The workflow executes a Webhook step, sending an HTTP request to your URL with relevant data
This means you can receive notifications for any event Mailrify tracks, including both system events and your own custom events.

​
Internal events

Mailrify automatically tracks a set of internal events that you can use as workflow triggers. These events cannot be manually tracked via the API — they are generated by the system.

​
Email events

EventDescription
email.sentAn email was successfully sent
email.deliveryAn email was delivered to the recipient
email.openA contact opened an email for the first time
email.clickA contact clicked a link in an email for the first time
email.bounceAn email bounced (hard or soft bounce)
email.complaintA contact marked an email as spam
email.receivedAn email was received at your verified domain (requires inbound setup)

​
Contact events

EventDescription
contact.subscribedA contact’s subscription status changed to subscribed
contact.unsubscribedA contact’s subscription status changed to unsubscribed

​
Segment events

EventDescription
segment.<name>.entryA contact entered a segment
segment.<name>.exitA contact exited a segment
Segment events use a slugified version of the segment name. For example, a segment called “VIP Users” would produce the events segment.vip-users.entry and segment.vip-users.exit.

​
Setting up a webhook

1

Create the workflow

Navigate to the Workflows section in the dashboard and create a new workflow. Choose the event you want to listen for as the trigger. For example, to receive notifications when an email bounces, use email.bounce as the trigger event.
2

Add a Webhook step

After the trigger, add a Webhook step and configure it:
  • URL: The endpoint on your server that will receive the webhook (e.g. https://api.example.com/webhooks/mailrify)
  • Method: The HTTP method to use. Defaults to POST, which is recommended for most use cases.
  • Headers (optional): Custom headers to include in the request, provided as JSON. This is useful for authentication.
{
  "Authorization": "Bearer your-secret-token"
}
3

Enable the workflow

Once configured, enable the workflow. It will start sending webhook requests whenever the trigger event occurs.

​
Webhook payload

When using the default payload (no custom body configured), Mailrify sends a JSON request with the following structure: 
{
  "contact": {
    "email": "[email protected]",
    "subscribed": true,
    "data": {
      "name": "John",
      "plan": "pro"
    }
  },
  "workflow": {
    "id": "wf_abc123",
    "name": "Bounce Notifications"
  },
  "execution": {
    "id": "exec_xyz789",
    "startedAt": "2025-01-15T10:30:00.000Z"
  },
  "event": {
    "subject": "Welcome to Mailrify",
    "from": "[email protected]",
    "bounceType": "Permanent"
  }
}
The event field contains the data associated with the event that triggered the workflow. The exact contents depend on the event type.

​
Event data by type

The event field varies depending on which event triggered the workflow:
EventFields in event
email.sentsubject, from, messageId, templateId, campaignId, sourceType
email.opensubject, from, openedAt, isFirstOpen
email.clicksubject, from, clickedAt, clicks, isFirstClick
email.bouncesubject, from, bounceType, bouncedAt
email.complaintsubject, from, complainedAt
email.receivedmessageId, from, fromHeader, to, subject, timestamp, recipients, hasContent, spamVerdict, virusVerdict, spfVerdict, dkimVerdict, dmarcVerdict, processingTimeMillis
Custom eventsWhatever data you passed when tracking the event

​
Common use cases

​
Bounce and complaint monitoring

Create a workflow triggered by email.bounce or email.complaint to forward these events to your application. This allows you to keep your own database in sync with Mailrify’s contact statuses. You can use additional workflow steps before the webhook to add logic:
  • Condition: Only send the webhook for hard bounces by checking the bounceType field
  • Delay: Add a short delay to batch-process related events
  • Update Contact: Mark the contact with metadata before sending the webhook

​
Syncing unsubscribes

Trigger a workflow on contact.unsubscribed to notify your application when a contact opts out. This is useful for keeping subscription status synchronized across multiple systems.

​
Custom event forwarding

If you track custom events in Mailrify (e.g. user.signup, order.completed), you can forward those same events to other services via webhooks. This turns Mailrify into an event router — track once, distribute to multiple endpoints.

​
Adding conditions and delays

Since webhooks are part of the workflow system, you can combine them with other step types for more advanced setups:
  • Use a Condition step to only fire the webhook when certain criteria are met (e.g. only notify for contacts on a specific plan)
  • Use a Wait for Event step to wait for a follow-up event before sending the webhook (e.g. wait to see if a bounced contact re-subscribes)
  • Use a Delay step to add a time buffer before the webhook fires