Introduction: Sidebar SDK

The Mixmax sidebar is present in Gmail and Inbox (but soon all over the web!) with the Mixmax extension installed. Its primary purpose is to show contextual information about a particular email address (though this will change in the future as more APIs are added). In the top of the sidebar it shows the selected contact, and then beneath it lists tabs of "sidebar integrations" that you have installed. A sidebar integration is a standalone website that is loaded inside an iframe that can respond to a new contact being "selected" via a Javascript API.

Through the Mixmax Sidebar SDK discussed here, you can add your own sidebar to Mixmax. This makes it possible to extend Mixmax with your own tools.

Mixmax comes with two built-in sidebar integrations:

  • Contact profiles - lists contact profiles for the selected contact
  • Salesforce (Growth or above only) - syncs the contact to Salesforce
The Mixmax sidebar in GmailThe Mixmax sidebar in Gmail

The Mixmax sidebar in Gmail

Adding your sidebar integration to Mixmax

You can add a sidebar integration to Mixmax in your developer settings dashboard. You will need Growth or above for access—email [email protected] for a free trial.

This will add the sidebar integration for your personal use. You may also share it with individual users, by email, or with your Mixmax team(s). When you're ready to release your integration to all Mixmax users, email us at [email protected] with your request.


To add your sidebar integration, you will need a few pieces of information:


The name of your integration to show up in developer settings.


The URL of your integration. The webpage at this URL should use the Sidebar SDK, as described in the following sections, to communicate with the Mixmax extension.

Tab icon

There are two ways to specify the icon used to represent your integration's tab in the Mixmax extension:

  • you can provide the URL of an image, or
  • you can provide the name of a Font Awesome icon such as "info-circle" and a color, specified as a hex value, such as "#8a8a9e".

You must specify either an image or both the name and color.

Loading the Sidebar SDK

Include the following line of Javascript in your website:

<script defer src=""></script>

The script will create the global object Mixmax.sidebar. See below for its use.

If you're using a JavaScript bundler like Rollup or Webpack, instead of loading the SDK using a script tag, you can import the SDK from npm like

const Mixmax = require('@mixmaxhq/sdk');

Mixmax.sidebar.on('contactSelected', (contact) => console.log(contact));

If your bundler is capable of importing ES6 modules and understands pkg.module, you can import the SDK like

import { sidebar } from '@mixmaxhq/sdk';
sidebar.on('contactSelected', (contact) => console.log(contact));

// If your bundler understands [`pkg.browser`](
// like Rollup does when using rollup-plugin-node-resolve with
// [`browser: true`](,
// you can import the Sidebar SDK directly. This is not only a more concise
// import but may actually lead to bundling less JS due to 
import sidebar from '@mixmaxhq/sdk/sidebar';
sidebar.on('contactSelected', (contact) => console.log(contact));

Using the Sidebar SDK

Once you have loaded the sidebar object, you can use it to listen for events from the Mixmax extension telling you when and how to update your sidebar integration. The sidebar object is an eventemitter3 instance, so you register event listeners like

sidebar.on('contactSelected', (contact) => console.log(contact));


The events that the object emits are:

Event: 'contactSelected'


  • contact <Object> A contact that the user just selected, for instance by hovering over an email address in Gmail. This object will have the following properties:
    • email <String> The email address of the contact.
    • fullName <String> (Optional) The full name of the contact, if available.
    • image <String> (Optional) The URL of an image for the contact.

When you receive this event, you should populate your integration with information related to the contact. For instance, if your integration represented a task manager, your integration might display a list of tasks assigned to this contact.

Event: 'beforeContactSelected'


  • event <Event>

Listening to this event is optional. You should listen to this event if you wish to prevent the sidebar from selecting a new contact, perhaps because the user has not finished editing information in your integration related to the current contact. Calling event.preventDefault() will prevent the sidebar from updating to show the new contact. (The user will then have to re-select that contact at some later point, at which time this event will be emitted again.)

Event: 'clear'

No arguments.

When you receive this event, you should clear your integration of the information it is currently displaying. This event is not currently emitted but may be in the future.