Mixmax API Client

Common errors

• Error: Request failed with status code 401

  cause Invalid or missing Mixmax API key provided during client initialization. The API token might be incorrect, expired, or have insufficient permissions.
  fix Verify that your `MIXMAX_API_KEY` is correct and active. Ensure it's retrieved from your Mixmax settings (Settings > Integrations > API Token) and passed correctly to the `MixmaxAPI` constructor.

• Error: Request failed with status code 404 - Sequence not found

  cause The provided sequence ID does not exist, or the authenticated user does not have access to it.
  fix Double-check the `sequenceID` used in your code against your Mixmax dashboard. Ensure the API key corresponds to a Mixmax account that has permission to access that specific sequence.

• Error: Request failed with status code 429 - Too Many Requests

  cause Your application has exceeded the Mixmax API rate limits (120 requests per minute per user and IP address).
  fix Implement rate limiting on your client-side application or use a retry-with-backoff strategy to handle `429` responses. Respect the `Retry-After` header if provided in the API response.

• TypeError: api.sequences.sequence is not a function

  cause This error typically occurs if the `api` object was not correctly initialized with a `MixmaxAPI` instance, or if there's a typo in `sequences` or `sequence`. It could also indicate a fundamental change in the library's API if using an incompatible version.
  fix Ensure `const api = new MixmaxAPI(apiKey);` executed successfully and `apiKey` was valid. Verify the correct casing and property names (`sequences`, `sequence`). If updating, check the changelog for breaking changes related to the client's structure.

Warnings

• breaking Version 1.3.0 included a fix to 'update HTTP calls to use new format'. While described as a fix, this indicates changes to the underlying Mixmax API or how the wrapper interacts with it. Older versions might experience connectivity issues or incorrect behavior if the Mixmax API has since diverged significantly.
  Fix: Ensure you are using `mixmax-api` version 1.3.0 or higher. Regularly test API interactions after any Mixmax platform updates or if you experience unexpected errors with older library versions.
• gotcha The package has not been updated since December 2020. This means it may not support newer features of the Mixmax platform or gracefully handle recent changes to the Mixmax API. The official Mixmax API documentation continues to be updated, suggesting potential discrepancies.
  Fix: Review the official Mixmax Developer Portal and API documentation for any features or endpoints not covered by this library. Be prepared to directly use the Mixmax REST API for new functionalities or if this wrapper becomes incompatible with future Mixmax changes.
• gotcha Mixmax API requests are subject to rate limits (120 requests per minute per user and IP address). Exceeding these limits will result in errors.
  Fix: Implement proper error handling and retry mechanisms with exponential backoff for rate limit errors. Monitor your API usage and design your application to respect these limits, especially for bulk operations. Check the `Retry-After` header in error responses.
• gotcha Authentication requires an API key, which must be obtained from your Mixmax settings page. Improper handling or exposure of this key can lead to unauthorized access to your Mixmax data.
  Fix: Always store your Mixmax API key securely, preferably using environment variables or a secret management service, especially in production environments. Never hardcode API keys directly into your source code. Regenerate the key if you suspect it has been compromised.

Install

• npm install mixmax-api npm
• yarn add mixmax-api yarn
• pnpm add mixmax-api pnpm

Imports

• MixmaxAPI
  wrong:

  import MixmaxAPI from 'mixmax-api';

  correct:

  const MixmaxAPI = require('mixmax-api');

  The library primarily uses CommonJS `require` syntax as demonstrated in its documentation. While Node.js supports ESM, this package is not explicitly set up for it, and a direct `import` might not work as expected without transpilation or specific Node.js configuration for CJS interoperability.
• MixmaxAPI (ESM approximation)
  wrong:

  import { MixmaxAPI } from 'mixmax-api';

  correct:

  import MixmaxAPI from 'mixmax-api'; // May require Node.js `--experimental-json-modules` or build step

  Although the package is not explicitly designed for ESM, if your project is pure ESM, you might be able to import it as a default export, potentially requiring `--experimental-json-modules` in Node.js or a build step to handle CJS modules. Named imports are generally incorrect for modules exporting a single constructor/class via CommonJS `module.exports = ...`.

Quickstart

This quickstart demonstrates how to initialize the Mixmax API client with an API key and then add a new recipient to a specified email sequence. It highlights the basic authentication and sequence management functionality.

const MixmaxAPI = require('mixmax-api');

// IMPORTANT: Replace with your actual Mixmax API key from settings.
// You can retrieve this key from your Mixmax settings page (Settings -> Integrations -> API).
// Do NOT hardcode in production; use environment variables.
const apiKey = process.env.MIXMAX_API_KEY ?? 'YOUR_SUPER_SECRET_MIXMAX_API_KEY'; 

if (!apiKey || apiKey === 'YOUR_SUPER_SECRET_MIXMAX_API_KEY') {
  console.error('Mixmax API Key is missing. Please set the MIXMAX_API_KEY environment variable or replace the placeholder.');
  process.exit(1);
}

const api = new MixmaxAPI(apiKey);

async function addRecipientToSequence() {
  // Replace with an actual sequence ID from your Mixmax account
  const sequenceID = 'your-mixmax-sequence-id'; 
  const recipientEmail = 'test-recipient@example.com';

  try {
    const sequence = api.sequences.sequence(sequenceID);
    const results = await sequence.addRecipients([
      {
        email: recipientEmail,
        variables: {
          firstName: 'Test',
          lastName: 'User'
        }
      }
    ]);
    console.log('Successfully added recipient to sequence:', results);
  } catch (error) {
    console.error('Error adding recipient to sequence:', error.message);
    if (error.response && error.response.data) {
      console.error('API Error Details:', error.response.data);
    }
  }
}

addRecipientToSequence();