Out of the box, Mixmax is a powerful tool for making your communication more powerful, compelling, and efficient. Did you know that it’s also an extensible platform that a developer can quickly and easily customize to fit their organization’s specific needs?

One of the ways Mixmax can be extended is through the creation of “slash commands”. These are commands that start with a slash character (/) and allow you to insert rich content into your message without ever taking your hands off the keyboard.

Webtask.io, like its name implies, is a great platform for hosting web-accessible code that performs simple online tasks on demand. It’s designed to provide a developer–even a novice!–with an environment and tools to get their code up and running on the web with minimal effort.

In this tutorial–which is designed to be accessible to anyone regardless of developer skill level or familiarity with Mixmax–I’m going to show you a quick and simple way to use Webtask.io to provide the interactive backend that powers a Mixmax slash command. In order to complete this tutorial, you need to have a Mixmax account connected to your Gmail. If you haven’t signed up for a Mixmax account yet, go do so!

What makes a slash command

A Mixmax slash command has three key parts:

• The command itself that you’ll type to start creating your rich content,
• A way to provide suggestions for the inserted content, and
• A way to resolve the command and insert the finalized content into the email.

In case you’re unfamiliar with Mixmax slash commands, let’s try one out. In your Gmail account with Mixmax connected, click the “Compose” button to start writing a new email, and in the email body, type a slash: /.

You’ll immediately see a popup with a list of available slash commands, each of which can insert HTML content into your message to make it more powerful, interesting, funny, interactive, or relevant. Try typing /image toast and you’ll see the suggested images.

Select one, either by scrolling with the up and down arrow keys and pressing return or by clicking with your mouse, and watch it be inserted automatically.

In this example, the slash command is /image, the suggestions are the popup list of images matching the search term “toast”, and the resolution of the command is what happens when you select an image and it gets inserted into your email.

To create our own slash command, we’ll be handling all three of these.

Getting started

The first step is to tell Mixmax that you’re creating a new slash command. To do this, click the Mixmax button in the Gmail header to launch the Mixmax Dashboard.

Then, in the sidebar of the Mixmax Dashboard, click “Settings”, and finally within the Settings page, click “Developer”. (Don’t worry if your menus don’t look exactly like this; different Mixmax plans have access to different features.) You’ll end up at the Developer Settings page.

At the bottom of the list of built-in slash commands, click the “Add Slash Command” button to display the form where you’ll set up your slash command.

The slash command we’re going to build will allow you to dynamically generate a QR code and insert it into your email, so that people who are viewing the email on their laptop or desktop can quickly access the QR code’s content (which could be a URL, for example) on their mobile device.

In the “Name” box, type “Generate QR Code”, in the “Command” box, type “qr”, and in the “Parameter placeholder” box, type “[URL or other text to encode]”.

With these values filled out, we’re ready to start making our command work by building the two API endpoints necessary.

Suggestions API vs. Resolver API

What’s the difference between the suggestions API and the resolver API? Remember, the idea behind a slash command is to help the user get something done quickly that makes their communication better. By providing a suggestions API as part of a slash command, we can immediately start giving the user options to insert content as soon as they provide us with some input, and Mixmax will show those options in a popup for easy access.

However, those suggestions don’t necessarily contain every bit of rich content that the end result will, which is why a slash command uses a resolver API to flesh things out. When the user selects one of the suggestions, that data is passed to the resolver which can add even more data before creating the resulting HTML that will be added to the email.

Getting set up with Webtask.io

To build our endpoints, we’re going to use Webtask.io, which lets us write code right within our browser (or on the command line, if you prefer), and then run that code by loading the URL provided to us.

In a new tab, head over to Webtask.io, click “Try it now!”, and sign in with one of your existing accounts. Within moments, you’ll be looking at an empty code editor, ready for you to start writing.

Setting up your suggestions endpoint

A slash command’s suggestions endpoint needs to do three things:

1. Accept the text that the user has typed after the slash command,
2. Generate a list of possible values that correspond to that text, and
3. Deliver that list with some metadata back to the slash command.

When you type some text after a slash command in a Mixmax message compose window, it sends that text in the query string of a `GET` request to the suggestions API URL for that slash command. It also includes some other information about the user making the request: their email address and what Mixmax thinks their timezone is, in case that’s helpful for your command. That means the data will be sent as something like example.com/suggestions?user=you%40gmail.com&timezone=America%2FNew_York&text=your+text+here. The only bit of that we need is the text.

In Webtask.io parlance, we’ll receive the text from the context object that is automatically passed as an argument to our function, and use the callback function also provided to deliver it as our response. The rest is up to us.

Let’s get started creating the endpoint for our slash command’s suggestions API. Click “Create a new one” in the middle of the screen, then hover over “Webtask Function” and click “Create empty”.

Name your new webtask function qr-suggestions and click “Save”. You’ll be presented with an empty code stub. Delete all of the existing code and replace it with the following:

  module.exports = function (context, callback) {
    callback(null, [
      {
        title: "Type a URL or other text and press return.",
        text: context.query.text
      }
    ]);
  }

The slash command’s suggestions API is supposed to return a list of suggested possibilities for the output of the command. However, a QR code is a QR code, so a list of suggestions doesn’t really make much sense in this context. Instead, our suggestions API just tells the user to go ahead and type their content and press return. When they do so, Mixmax will send their text to the resolver API endpoint, which is where the real work is done.

Click the save icon in the top right (or press ⌘-S or Ctrl-S). Then, at the bottom of the screen, you’ll notice a URL that ends with qr-suggestions. This is your webtask’s API URL. Copy it, head back to the Mixmax Developer Settings tab that you left open, and paste that URL into the “Command Parameter Suggestions API URL” box. Only one piece left!

Setting up your resolver endpoint

Back in the Webtask.io editor, we need to create another webtask function to be our command resolver. Click the “Create new” button in the sidebar at the far left, then again hover over “Webtask function” and click “Create empty”. Name this function qr-resolver.

In order to generate the QR code image that we’re going to return when we resolve our command, we’ll need to use an existing service. GoQR.me generously offers a free, open API for doing just this. Even better, their API requires no setup or authentication–all we have to do is generate the right URLs and they’ll give us a QR code PNG image in return.

Once again, delete the default code in the editor and replace it with the following:

  module.exports = function (context, callback) {
    callback(null, {
      body: `<img src="https://api.qrserver.com/v1/create-qr-code/?size=100x100&qzone=1&data=${encodeURIComponent(context.query.text)}">`
    });
  }

In a nutshell, we’re taking the text that the user sends, and resolving it to an HTML img tag with the URL of a generated QR code with that text encoded. Using encodeURIComponent ensures that no matter what text the user types, we’ll create a valid URL, so the img tag won’t fail to display.

Save this code, copy the URL from the bottom of the page, and in your Mixmax Developer Settings, paste it into the “Command Parameter Resolver API URL” box. At this point, you can click “Add Slash Command” and see that “Generate QR Code” has appeared in your list of slash commands.

Trying it out

Head back to Gmail, and in your Mixmax message compose window, type /qr. You’ll see that the command is now available from within your email message.

Type some text, like “https://mixmax.com”, and you’ll see the output from your suggestions API. When you press return, your resolver API will take that text and send back the HTML necessary to render a QR code right in your email.

Using a barcode scanner app on your phone, give it a try!

The sky’s the limit

Now that you’ve created your first Mixmax slash command using Webtask.io, the possibilities are endless. We’ve barely scratched the surface of what’s possible in this tutorial; both tools give you immense power to create and automate workflows within your email communications that can make your life easier and your work more efficient and effective.

If you’re interested in learning more about how you can use the Mixmax API and other developer tools to make Mixmax work for you, head over to Mixmax Developer to start digging deeper. And if you want to use Mixmax to empower your team and your organization and make your communications more efficient, effective, and impactful, get in touch with us today!

Finally, if you want to work on products that help people communicate better, improve the way the world does business, and are exciting and just plain fun, we’re hiring!