search

gomfunkel / node-mailchimp

A node.js wrapper for the MailChimp API.
MIT License
359 stars 63 forks source link

readme

node-mailchimp

A node.js wrapper for the MailChimp API.

node-mailchimp exposes the following features of the MailChimp API to your node.js application:

Further information on the MailChimp API and its features is available at http://apidocs.mailchimp.com. If you want to know more about the Mandrill API and its features have a look at https://mandrillapp.com/api/docs/.

Table of Contents

Installation

Installing using npm (node package manager):

npm install mailchimp

If you don't have npm installed or don't want to use it:

cd ~/.node_libraries
git clone git://github.com/gomfunkel/node-mailchimp.git mailchimp

Please note that parts of node-mailchimp depend on request by Mikeal Rogers. This library needs to be installed for the API and Export API to work. Additionally node-querystring is needed for the Webhooks to work. If you are using npm all dependencies should be automagically resolved for you.

Usage

Information on how to use the MailChimp APIs can be found below. Further information on the API methods available can be found at http://apidocs.mailchimp.com. You can also find further information on how to obtain an API key, how to set up Webhooks and/or OAuth2 in your MailChimp account and much more on the MailChimp API pages.

Some methods of the MailChimp API take associative arrays as a parameter, for example the parameter merge_vars of the listSubscribe method. As there are no associative arrays in JavaScript you simply use an object with its properties being the keys, like in the following example:

var merge_vars = {
    EMAIL: '/* E-MAIL ADDRESS */',
    FNAME: '/* FIRST NAME */',
    LNAME: '/* LAST NAME */'
};

MailChimp API (when using MailChimp API version 2.0)

Attention: Support for v2.0 of the MailChimp API is not yet well tested. Please use with caution. When in doubt, stick to older versions of the API (v1.x) and skip to the next chapter for documentation.

MailChimpAPI takes two arguments. The first argument is your API key, which you can find in your MailChimp Account. The second argument is an options object which can contain the following options:

All of the API categories and methods described in the MailChimp API v2.0 Documentation (http://apidocs.mailchimp.com/api/2.0 are available in this wrapper. To use them the method call is used which takes four parameters:

Example:

var MailChimpAPI = require('mailchimp').MailChimpAPI;

var apiKey = 'Your MailChimpAPI API Key';

try {
    var api = new MailChimpAPI(apiKey, { version : '2.0' });
} catch (error) {
    console.log(error.message);
}

api.call('campaigns', 'list', { start: 0, limit: 25 }, function (error, data) {
    if (error)
        console.log(error.message);
    else
        console.log(JSON.stringify(data)); // Do something with your data!
});

api.call('campaigns', 'template-content', { cid: '/* CAMPAIGN ID */' }, function (error, data) {
    if (error)
        console.log(error.message);
    else
        console.log(JSON.stringify(data)); // Do something with your data!
});

MailChimp API (when using MailChimp API version 1.x)

MailChimpAPI takes two arguments. The first argument is your API key, which you can find in your MailChimp Account. The second argument is an options object which can contain the following options:

The callback function for each API method gets two arguments. The first one is an error object which is null when no error occured, the second one an object with all information retrieved as long as no error occured.

Example:

var MailChimpAPI = require('mailchimp').MailChimpAPI;

var apiKey = 'Your MailChimp API Key';

try {
    var api = new MailChimpAPI(apiKey, { version : '1.3', secure : false });
} catch (error) {
    console.log(error.message);
}

api.campaigns({ start: 0, limit: 25 }, function (error, data) {
    if (error)
        console.log(error.message);
    else
        console.log(JSON.stringify(data)); // Do something with your data!
});

api.campaignStats({ cid : '/* CAMPAIGN ID */' }, function (error, data) {
    if (error)
        console.log(error.message);
    else
        console.log(JSON.stringify(data)); // Do something with your data!
});

MailChimp Export API

MailChimpExportAPI takes two arguments. The first argument is your API key, which you can find in your MailChimp Account. The second argument is an options object which can contain the following options:

The callback function for each API method gets two arguments. The first one is an error object which is null when no error occured, the second one an object with all information retrieved as long as no error occured.

Example:

var MailChimpExportAPI = require('mailchimp').MailChimpExportAPI;

var apiKey = 'Your MailChimp API Key';

try {
    var exportApi = new MailChimpExportAPI(apiKey, { version : '1.0', secure: false });
} catch (error) {
    console.log(error.message);
}

exportApi.list({ id : '/* LIST ID */'  }, function (error, data) {
    if (error)
        console.log(error.message);
    else
        console.log(JSON.stringify(data)); // Do something with your data!
});

MailChimp Webhooks

MailChimpWebhook takes one argument, an options object which can contain the following options:

You can register the following events. The callback function for each of these events receive two arguments. The first argument is an object with the information retrieved, the second argument contains metadata like when the event occurred.

Example:

var MailChimpWebhook = require('mailchimp').MailChimpWebhook;

var webhook = new MailChimpWebhook();

webhook.on('error', function (error) {
    console.log(error.message);
});

webhook.on('subscribe', function (data, meta) {
    console.log(data.email+' subscribed to your newsletter!'); // Do something with your data!
});

webhook.on('unsubscribe', function (data, meta) {
    console.log(data.email+' unsubscribed from your newsletter!'); // Do something with your data!
});

MailChimp OAuth2

MailChimpOAuth takes one argument, an options object which can contain the following options:

You can register the following events:

Example:

var MailChimpOAuth = require('mailchimp').MailChimpOAuth;
var MailChimpAPI = require('mailchimp').MailChimpAPI;

var options = {
    clientId: 'Your MailChimp client id',
    clientSecret: 'Your MailChimp client secret',
    redirectUri: 'http://www.example.com',
    ownServer: true,
    addPort: true,
    finalUri: 'http://www.example.com/successfulLogin.html'
};

var oauth = new MailChimpOAuth(options);

console.log(oauth.getAuthorizeUri()); // The MailChimp login URI the user needs to be sent to
<!-- Error contains custom Data when passed around to know the current status-->
oauth.on('error', function (error) {
    console.log(error.err);
});

oauth.on('authed', function (data) {

    try {
        var api = new MailChimpAPI(data.apiKey, { version : '1.3', secure : false });
    } catch (error) {
        console.log(error.message);
    }

    api.campaigns({ start: 0, limit: 25 }, function (error, data) {
        if (error)
            console.log(error.message);
        else
            console.log(JSON.stringify(data)); // Do something with your data!
    });

});

MailChimp Partner API

MailChimpPartnerAPI takes two arguments. The first argument is your app key, which you can generate and find in your MailChimp Account, if you are eligible to use the Partner API. The second argument is an options object which can contain the following options:

The callback function for each API method gets two arguments. The first one is an error object which is null when no error occured, the second one an object with all information retrieved as long as no error occured.

Example:

var MailChimpPartnerAPI = require('mailchimp').MailChimpPartnerAPI;

var appKey = 'Your MailChimp app key';

try {
    var api = new MailChimpPartnerAPI(appKey, { version : '1.3', secure : false });
} catch (error) {
    console.log(error.message);
}

api.checkUsername({ username: '/* USERNAME */' }, function (error, data) {
    if (error)
        console.log(error.message);
    else
        console.log(JSON.stringify(data)); // Do something with your data!
});

Mandrill API

MandrillAPI takes two arguments. The first argument is your API key, which you can find in your Mandrill Account. The second argument is an options object which can contain the following options:

All of the API categories and methods described in the Mandrill API Documentation (https://mandrillapp.com/api/docs/) are available in this wrapper. To use the the method call is used which takes four parameters:

var MandrillAPI = require('mailchimp').MandrillAPI;

var apiKey = 'Your Mandrill API Key';

try {
    var mandrill = new MandrillAPI(apiKey, { version : '1.0', secure: false });
} catch (error) {
    console.log(error.message);
}

mandrill.call('tags', 'time-series', { tag : '/* TAGNAME */'  }, function (error, data) {
    if (error)
        console.log(error.message);
    else
        console.log(JSON.stringify(data)); // Do something with your data!
});

MailChimp STS API

MailChimpSTSAPI is no longer part of this wrapper as of version 1.0.1 because the API was discontinued by MailChimp.

License

node-mailchimp is licensed under the MIT License. (See LICENSE)