|
| 1 | +--- |
| 2 | +pageTitle: 'Activity Tracking' |
| 3 | +title: 'Activity Tracking' |
| 4 | +description: 'Learn how to enable activity tracking to get real-time delivery and engagement events like delivered, opened, and clicked from your email providers.' |
| 5 | +--- |
| 6 | + |
| 7 | +Activity tracking gives you visibility into what happens to notifications after they are sent to the subscriber. With it, Novu receive and process real-time events from third-party providers, so that you know when the notification is delivered, opened, clicked, or bounced. |
| 8 | + |
| 9 | +## How activity tracking works |
| 10 | + |
| 11 | +When your provider emits an event (for example, an email delivered or bounced), Novu: |
| 12 | +- Receives the event via inbound webhooks. |
| 13 | +- Create step-run trace, so the event is visible in the activity feed. |
| 14 | +- Forwards supported events to outbound webhooks if they are enabled in your project. |
| 15 | +- Enriches the workflow-run lifecycle with engagement and delivery data, which empowers analytics and workflow variables. |
| 16 | + |
| 17 | +With activity tracking enabled, you get a full picture of the workflow-run lifecycle, not just that a message was “sent,” but whether it reached the recipient, was opened, or engaged with. This closes the feedback loop and allows you to build more reliable notification experiences. |
| 18 | + |
| 19 | +## How to enable activity tracking |
| 20 | + |
| 21 | +First [create the integration](/platform/integrations/email/adding-email). After that, you can enable activity tracking by following these steps: |
| 22 | +1. Log in to the Novu dashboard |
| 23 | +2. Navigate to the **Integrations Store** page from the sidebar of your Novu dashboard. |
| 24 | +3. Click **Connect Provider** and select the email provider you want to configure. |
| 25 | +4. Scroll down to find the **Email Activity Tracking** section and click the toggle to enable it. |
| 26 | +  |
| 27 | + When enabled, Novu will auto-configure delivery webhooks using your existing API key. |
| 28 | +  |
| 29 | + |
| 30 | +## Manual configuration |
| 31 | + |
| 32 | +If auto-configuration fails or isn’t supported for your provider, you will need to set it up manually. You can do that by following these provider specific guides: |
| 33 | + |
| 34 | +<Cards> |
| 35 | + <Card title="Email" href="/platform/integrations/email"> |
| 36 | + Amazon SES |
| 37 | + </Card> |
| 38 | + <Card title="SMS" href="/platform/integrations/sms"> |
| 39 | + Mailgun |
| 40 | + </Card> |
| 41 | + <Card title="SendGrid" href="/platform/integrations/email/activity-tracking/manual-configuration/sendgrid"> |
| 42 | + SendGrid manual configuration |
| 43 | + </Card> |
| 44 | + <Card title="Chat" href="/platform/integrations/chat"> |
| 45 | + Resend |
| 46 | + </Card> |
| 47 | +</Cards> |
| 48 | + |
| 49 | +## Event semantics in Novu |
| 50 | + |
| 51 | +Inbound webhook events are normalized into a consistent set of Novu event statuses. These statuses let you track the full lifecycle of a notification across providers in a unified way. |
| 52 | + |
| 53 | +| Novu status | Meaning | |
| 54 | +| -------------- | ------------------------------------------------------------------------------------- | |
| 55 | +| `bounced` | The message was rejected by the recipient’s server (hard or soft bounce). | |
| 56 | +| `clicked` | The recipient clicked a link inside the message. | |
| 57 | +| `complaint` | The recipient marked the message as spam or filed a complaint. | |
| 58 | +| `delayed` | The provider delayed the message delivery (for example, due to throttling). | |
| 59 | +| `delivered` | The provider confirmed that the message was delivered to the recipient’s server. | |
| 60 | +| `dropped` | The provider dropped the message before attempting delivery. | |
| 61 | +| `opened` | The recipient opened the message (tracked via the provider’s open logic). | |
| 62 | +| `rejected` | The provider could not send the message (for example, invalid address, failed policy check). | |
| 63 | +| `sent` | The provider has accepted the message for delivery. | |
| 64 | +| `unsubscribed` | The recipient unsubscribed from further messages. | |
| 65 | + |
| 66 | +## Supported providers and events |
| 67 | + |
| 68 | +Novu currently supports inbound webhooks for several email providers. Each provider sends events in its own format, which Novu normalizes into a consistent set of internal statuses. These normalized statuses are used in the activity feed, step-run traces, and outbound webhook forwarding. |
| 69 | + |
| 70 | +Events not listed in the tables below are ignored. |
| 71 | + |
| 72 | +### SendGrid |
| 73 | + |
| 74 | +| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) | |
| 75 | +| ---------------------------------- | ---------------------------------- | |
| 76 | +| `bounce` | `bounced` | |
| 77 | +| `click` | `clicked` | |
| 78 | +| `delivered` | `delivered` | |
| 79 | +| `dropped` | `dropped` | |
| 80 | +| `open` | `opened` | |
| 81 | + |
| 82 | +### Mailgun |
| 83 | + |
| 84 | +| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) | |
| 85 | +| ---------------------------------- | ---------------------------------- | |
| 86 | +| `clicked` | `clicked` | |
| 87 | +| `complained` | `complaint` | |
| 88 | +| `delivered` | `delivered` | |
| 89 | +| `opened` | `opened` | |
| 90 | +| `permanent_fail`, `failed` | `rejected` | |
| 91 | +| `unsubscribed` | `unsubscribed` | |
| 92 | + |
| 93 | +### Resend |
| 94 | + |
| 95 | +| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) | |
| 96 | +| ---------------------------------- | ---------------------------------- | |
| 97 | +| `email.bounced` | `bounced` | |
| 98 | +| `email.clicked` | `clicked` | |
| 99 | +| `email.complained` | `complaint` | |
| 100 | +| `email.delivered` | `delivered` | |
| 101 | +| `email.delivery_delayed` | `delayed` | |
| 102 | +| `email.failed` | `rejected` | |
| 103 | +| `email.opened` | `opened` | |
| 104 | +| `email.sent` | `sent` | |
| 105 | + |
| 106 | +### Amazon SES |
| 107 | + |
| 108 | +| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) | |
| 109 | +| ---------------------------------- | ---------------------------------- | |
| 110 | +| `Bounce` | `bounced` | |
| 111 | +| `Complaint` | `complaint` | |
| 112 | +| `Click` | `clicked` | |
| 113 | +| `Delivery` | `delivered` | |
| 114 | +| `DeliveryDelay` | `delayed` | |
| 115 | +| `Open` | `opened` | |
| 116 | +| `Reject` | `rejected` | |
| 117 | +| `Send` | `sent` | |
| 118 | + |
| 119 | +## Viewing event data |
| 120 | + |
| 121 | +Once your inbound webhooks are configured, Novu will start processing events from your provider. You can see this new data in two key places within the platform. |
| 122 | + |
| 123 | +### Activity feed |
| 124 | + |
| 125 | +The Activity Feed provides the most direct view of the notification lifecycle. After a notification is sent, you will see new status updates such as Delivered, Opened, and Clicked appear in the timeline as they are received from your provider. This gives you a complete, real-time picture of subscriber engagement for each notification. |
| 126 | + |
| 127 | +### Outbound webhooks integration |
| 128 | + |
| 129 | +Inbound webhooks don’t just update Novu internally, they can also trigger outbound webhooks, allowing you to send normalized events to your own systems in real time. This makes it possible to extend Novu’s notification lifecycle into your existing infrastructure. |
| 130 | + |
| 131 | +How it works: |
| 132 | + |
| 133 | +1. A provider emits an event (for example, delivered). |
| 134 | +2. Novu receives and normalizes the event (for example, → delivered). |
| 135 | +3. Novu updates its internal message entity and step-run trace. |
| 136 | +4. If outbound webhooks are enabled, Novu forwards the normalized event to your configured outbound webhook endpoint. |
| 137 | + |
| 138 | +This is useful in a number of use cases including: |
| 139 | +- Internal logging: Forward all events into your organization’s centralized logging pipeline. |
| 140 | +- Custom analytics: Combine Novu’s lifecycle data with your own metrics to measure engagement and delivery performance. |
| 141 | +- Workflow triggers: Kick off custom business logic when specific events occur (for example, flagging accounts with high bounce rates). |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?v=4&size=40){kind=avatar}
0 commit comments