Mixpanel destination
Beta
Data Destinations is currently available as a Private Beta product and the information contained in this document is subject to change. Data Destinations is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI. To learn more, see Private beta legal information.
Mixpanel is a product and behavioral analytics platform that lets you turn Twilio events into named, user-attributed events for funnels, retention, and segmentation analysis.
- Category: Analytics
- Release status: Beta
- Authentication: Basic authentication
- Regional availability: US1
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
Identifier-restricted eligibility: Twilio can only send events that contain an end-user identifier (such as a phone number or user ID) to Mixpanel. Mixpanel requires every event to carry a Distinct ID, and unlike some other analytics destinations, Mixpanel has no anonymous or device-level fallback identity. Twilio never uses your Account SID as a substitute identifier, since doing so would collapse unrelated events onto a single Mixpanel identity.
Twilio can currently send the following event types to Mixpanel:
- Messaging: inbound message received, message queued, message sent, message delivered, message failed, message undelivered, message read
- Voice: call answered, call initiated, call ringing, call completed, call redirected, call requested, call transferred, dial finished, enqueue finished, gather finished, record finished, media fetched
- Voice Insights: call summary complete
All other event types aren't currently eligible for this destination. See event types for the full list of available event types.
Before you set up a Mixpanel destination, make sure you have:
- A Mixpanel project.
- A Mixpanel Service Account with the Owner or Admin role on that project. The Import API this destination uses rejects service accounts with lesser roles. Create one in your project's Service Accounts settings.
- The service account's Username and Secret. Mixpanel shows the secret only once, when you create it, so save it securely.
- Your Mixpanel project's numeric Project ID.
Info
See Set up a destination for the full UI and Destinations API setup flow common to every destination type.
To create a Mixpanel destination in the Twilio Console:
- From your Mixpanel account, gather the settings listed in Destination settings.
- In the Twilio Console, go to Data > Data Destinations > Destinations > Add destination subscription.
- Complete the Add destination subscription wizard.
To create a Mixpanel destination through the Destinations API, send a POST request to the Destinations endpoint and set destinationType to mixpanel. For authentication and the other request body fields, see Create a destination.
POST "https://destinations.twilio.com/v1/ControlPlane/Destinations"
Set the config object in the request body as follows:
| Name | Type | Description |
|---|---|---|
credentials.credentialType (Required) | string | Set to BASIC. |
credentials.serviceAccountSecret (Required) | string | Your Mixpanel service account secret, which Mixpanel shows once when you create the account. |
credentials.serviceAccountUsername (Required) | string | Your Mixpanel service account username. The account needs the Owner or Admin role on the project. |
projectId (Required) | string | Your Mixpanel numeric project ID. |
region | enum<string> | Your Mixpanel data residency region. The default is US. Valid values: US, EU, IN. |
The following example shows a request body. Replace the uppercase placeholder values with your own.
1{2"destinationType": "mixpanel",3"name": "My Mixpanel destination",4"config": {5"credentials": {6"credentialType": "BASIC",7"serviceAccountSecret": "SERVICE_ACCOUNT_SECRET",8"serviceAccountUsername": "SERVICE_ACCOUNT_USERNAME"9},10"projectId": "PROJECT_ID"11}12}
Use mixpanel as the destinationType.
| Field | Description | Required | Default or choices |
|---|---|---|---|
| Service Account Username | Your Mixpanel Service Account username. Sent as the HTTP Basic Auth username on every request. | Yes | N/A |
| Service Account Secret | Your Mixpanel Service Account secret. Sent as the HTTP Basic Auth password on every request. Sensitive (stored encrypted). | Yes | N/A |
| Project ID | Your Mixpanel project's numeric ID. | Yes | N/A |
| Region | Your Mixpanel project's data residency. | No | US (default), EU, IN |
Twilio authenticates to Mixpanel by using HTTP Basic Auth. Twilio sends your Service Account Username and Service Account Secret on every request. Twilio requires a service account rather than a project token because only service account credentials can be verified with a live check when you save the destination.
| Field | Mixpanel field |
|---|---|
| Event type | Event Name |
| End-user identifier (for example, phone number) | Distinct ID |
| Event time | Time |
| CloudEvent ID | Insert ID (used for delivery deduplication) |
| Event payload | Properties |
Mixpanel truncates string property values over 255 characters, limits events to 255 properties, and limits nesting depth to 3. Twilio doesn't modify or drop properties beyond what Mixpanel enforces on ingest. Twilio sends your end-user identifier to Mixpanel unhashed. If you need it hashed, apply your own transformation in the subscription's binding mapping.
When you save a Mixpanel destination, Twilio validates your Service Account Username and Secret against Mixpanel before marking the destination active. This check doesn't confirm that the service account has the Owner or Admin role on your Project ID. A service account with a lesser role passes validation, and Mixpanel rejects it the first time Twilio tries to import events.
Twilio doesn't currently offer a way to manually trigger a test event for this destination, from either the Console or the CLI. To confirm delivery works, wait for a real event of a subscribed type to occur.
| Cause | What you'll see | Fix |
|---|---|---|
| Invalid or revoked Service Account credentials | Validation fails with an auth error | Re-check the username and secret in Mixpanel and update the destination |
| Service Account lacks Owner/Admin role on the project | Passes validation, then delivery errors reported in the Debugger | Grant the Service Account Owner or Admin role on the project |
| Event missing an end-user identifier | Event is not delivered to Mixpanel | See Eligible events. Twilio can send only events that carry an identifier |
| Mixpanel rejects the request as too large (413) | Delivery errors reported in the Debugger | Reduce the size of your event payload |
| Mixpanel rate-limiting requests (429) | Delivery errors reported in the Debugger | Retry is automatic. Sustained errors might indicate you've exceeded the Mixpanel rate limit |
| Mixpanel rejects specific events in a batch as malformed (400) | Only the flagged events fail; other events in the same batch still deliver, as reported in the Debugger | Check the flagged events' payload shape; sibling events don't need to be resent |
Mixpanel returns 200 but imports fewer events than sent (num_records_imported below the batch size) | No error is reported. Twilio treats the whole batch as delivered | This is a rare partial-import quirk on Mixpanel's side; cross-check your Mixpanel event counts if you suspect data loss |
If Twilio can't deliver events to your destination, Twilio sends an error notification to the Debugger (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error.