drip-nodejs
v3.1.3
Published
A complete NodeJS wrapper for connecting to the Drip v2 REST API
Downloads
10,354
Readme
Drip Rest API Wrapper for Node.js
A complete Nodejs wrapper for the Drip REST API.
How to install
npm install drip-nodejs --save
NOTE: Potential Breaking Changes for Version 3.0.0
Drip's documentation doesn't explicitly describe the required schema for each endpoint. In versions prior to 3 you would need to explicitly pass payloads with the required schema, which aren't obvious. In version 3 and later, I've attempted to make this a bit simpler. For example, batch endpoints will now only need you to pass an array of objects as:
payload = [
{
email: '[email protected]',
action: 'Purchased'
},
{
email: '[email protected]',
action: 'Purchased'
}
]
// client.recordBatchEvents(payload, ...)
Prior to v3 changes you would need to do something like the following where the entire payload structure is defined:
payload = {
batches: [
{
events: [
{
email: '[email protected]',
action: 'Purchased'
},
{
email: '[email protected]',
action: 'Purchased'
}
]
}
]
}
// client.recordBatchEvents(payload, ...)
This should help to get up and running simpler without much knowledge of the required schema. However, existing users will need to take special note of these changes.
Authentication
For private use and integrations, use your API Token found here. Create a new instance of the client library with:
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
For public integrations with an OAuth2 application registered with Drip, you'll need to specify the type of token you're passing (e.g. "Bearer"):
const client = require('drip-nodejs')({ token: YOUR_ACCESS_TOKEN, tokenType: TOKEN_TYPE, accountId: YOUR_ACCOUNT_ID });
You'll need your Drip Account ID when requiring the client which can be found here in your Drip account.
Usage
The following methods are currently available on the client instance. You can find a detailed explanation of all methods and their effect on resources in your Drip account here.
Note: All methods except updateBatchSubscribers
return promises and support an optional asynchronous callback. The batch subscribers method only supports callbacks for now.
Accounts
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List all accounts | client.listAccounts(callback)
|
| Fetch an account | client.fetchAccount(accountId, callback)
|
Broadcasts
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List broadcasts | client.listBroadcasts(options = {}, callback)
|
| Fetch a broadcast | client.fetchBroadcast(broadcastId, callback)
|
Campaigns
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List all campaigns | client.listCampaigns(options = {}, callback)
|
| Fetch a campaign | client.fetchCampaign(campaignId, callback)
|
| Activate a campaign | client.activateCampaign(campaignId, callback)
|
| Pause a campaign | client.pauseCampaign(campaignId, callback)
|
| List specific campaign's subscribers | client.listAllSubscribesToCampaign(campaignId, options = {}, callback)
|
| Subscribe to a campaign | client.subscribeToCampaign(campaignId, payload, callback)
|
Campaign subscriptions
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List campaign subscriptions | client.subscriberCampaignSubscriptions(subscriberId, callback)
|
Conversions
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List all conversions | client.listConversions(options = {}, callback)
|
| Fetch a conversion | client.fetchConversion(conversionId, callback)
|
Custom fields
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List all custom fields | client.listAllCustomFields(callback)
|
Events
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| Record an event | client.recordEvent(payload, callback)
|
| Record a batch of events | client.recordBatchEvents(payload, callback)
|
| List all events in account | client.listEventActions(options = {}, callback)
|
Forms
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List all forms | client.listForms(callback)
|
| Fetch a form | client.fetchForm(formId, callback)
|
Note: The beta purchases endpoint has been deprecated and its methods have been removed from the package except createPurchase
, which now sends requests to the Order creation endpoint here.
Orders
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| Record an order for a subscriber | client.createUpdateOrder(payload, callback)
|
| Record a batch of orders | client.createUpdateBatchOrders(payload, callback)
|
| Record a refund for an order | client.createUpdateRefund(payload, callback)
|
Shopper Activity
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| Create or update a cart for a customer | client.createUpdateCartActivity(payload, callback)
|
| Create or update an order for a customer | client.createUpdateOrderActivity(payload, callback)
|
| Create or update a product | client.createUpdateProductActivity(payload, callback)
|
Subscribers
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List all subscribers | client.listSubscribers(options = {}, callback)
|
| Update a subscriber | client.createUpdateSubscriber(payload, callback)
|
| Fetch a subscriber | client.fetchSubscriber(idOrEmail, callback)
|
| Unsubscribe from a campaign | client.unsubscribeFromCampaign(idOrEmail, campaignId, callback)
|
| Unsubscribe from all mailings | client.unsubscribeFromAllMailings(idOrEmail, callback)
|
| Delete a subscriber | client.deleteSubscriber(idOrEmail, callback)
|
| Update a batch of subscribers | client.updateBatchSubscribers(payload, callback)
|
| Unsubscribe a batch of subscribers | client.unsubscribeBatchSubscribers(payload, callback)
|
Tags
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List all tags | client.listAllTags(callback)
|
| Tag a subscriber | client.tagSubscriber(payload, callback)
|
| Remove tag from subscriber | client.removeSubscriberTag(email, tag, callback)
|
User
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| Fetch authenticated user | client.fetchUser(callback)
|
Webhooks
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List all webhooks | client.listWebhooks(callback)
|
| Fetch a webhook | client.fetchWebhook(webhookId, callback)
|
| Create a webhook | client.createWebhook(payload, callback)
|
| Destroy a webhook | client.destroyWebhook(webhookId, callback)
|
Workflows
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List all workflows | client.listAllWorkflows(options = {}, callback)
|
| Fetch a workflow | client.fetchWorkflow(workflowId, callback)
|
| Activate a workflow | client.activateWorkflow(workflowId, callback)
|
| Pause a workflow | client.pauseWorkflow(workflowId, callback)
|
| Start a subscriber on a workflow | client.startOnWorkflow(workflowId, payload, callback)
|
| Remove a subscriber from a workflow | client.removeFromWorkflow(workflowId, idOrEmail, callback)
|
Workflow triggers
| Action | Method |
|--------------------------------------|------------------------------------------------------------------------------|
| List all workflow triggers | client.listTriggers(workflowId, callback)
|
| Create a workflow trigger | client.createTrigger(workflowId, payload, callback)
|
| Update a trigger | client.updateTrigger(workflowId, triggerId, payload, callback)
|
See the official REST API docs for a complete API reference.
Examples
Listing subscribers
The listSubscribers
accepts an optional object of filter arguments. Refer to Drip's API docs for all the available filters.
/**
* Using a promise
*/
const options = {
status: "unsubscribed",
page: 2
// or with more options
};
client.listSubscribers(options)
.then((response) => {
// do something with the raw response object or with `response.data`
})
.catch((error) => {
// do something with the error
});
/**
* Using a callback
*/
client.listSubscribers(options, (error, response, data) => {
// do someting with the response or handle errors
});
Updating a batch of subscribers
The updateBatchSubscribers
method takes a batch object for the payload and is most suitable for sending thousands of subscriber updates.
Because Drip's batch APIs support a maximum of 1000 records, this method breaks the payload into N "batches" and calls the API N times. The callback is invoked only after all batches' API calls have returned, and receives N-sized arrays for values (i.e. errors
, responses
, and bodies
).
It is the responsibility of the caller to interpret these values and handle any errors.
var batch = {
"batches": [{
"subscribers": [
{
"email": "[email protected]",
"tags": "Dog Person"
},
{
"email": "[email protected]",
"tags": "Cat Person"
}
// Lots more subscribers...
]
}]
}
client.updateBatchSubscribers(batch, (errors, responses, bodies) => {
if (errors) {
console.error('Some requests failed:', errors);
} else {
console.log('All requests succeeded');
}
console.log('Responses:', responses);
console.log('Bodies:', bodies);
});
Sending a batch of events
The recordBatchEvents
methods takes a batch object for the payload and is most suitable for sending thousands of events. Note that the batch events method will not break up the payload into nice chunks like the subscribers batch method. This will be handled in a future update.
var batch = {
"batches": [{
"events": [
{
"email": "[email protected]",
"action": "Opened a door"
},
{
"email": "[email protected]",
"action": "Closed a door"
}
// Lots more events...
]
}]
}
client.recordBatchEvents(batch, function (error, response, data) {
// Do stuff
}
)
Changelog
[3.1.3] - 2024-11-05
- Bug fix in
updateBatchSubscribers
[3.1.2] - 2024-09-12
Breaking Changes:
Updated HTTP Client: We have switched to a Axios client to improve performance and reliability.
Property Name Change: The
body
property in responses has been renamed todata
to ensure compatibility with the new client and align with modern conventions.- Old:
response.body
- New:
response.data
- Old:
Please update your code accordingly. Example update:
// Old usage
const result = response.body;
// New usage
const result = response.data;
// EXAMPLE
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const payload = {
email: "[email protected]",
time_zone: "America/Los_Angeles",
custom_fields: {
shirt_size: "Medium"
}
};
client.createUpdateSubscriber(payload)
.then((response) => {
console.log(response.data)
})
.catch((error) => {
// Handle errors
});
Contributing
- Fork it ( https://github.com/samudary/drip-nodejs/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Note: Jasmine is used for testing