Автор оригинала: Matt Goldspink.
MailChimp Является известным по электронной почте Marketing SaaS Product. С его щедрым вариантом свободного уровня, он рассматривается как идеальное решение для многих стартапов и малых предприятий, которые хотят настроить и создать их списки рассылки.
Но то, что многие не могут заметить, так это насколько богат API.
Вот почему в этом руководстве я хотел бы пройти вас через несколько случаев использования о том, как вы можете интегрировать MailChimp в свое собственное приложение Node.js, фокусируясь на:
- Добавление новых пользователей в свой собственный список рассылки в MailChimp.
- Позволяя пользователям импортировать существующий список контактов из своей учетной записи MailChimp в ваше приложение и синхронизируйте их обратно.
Мы будем использовать следующие библиотеки Node.js:
- Экспресс для нашей бэкера
- SuperaGent Чтобы отдохнуть запросы на MailChimp
- Несколько других небольших библиотек для выполнения ОАУТ
1. Добавление новых пользователей в MailChimp
Сначала начнем с настройки очень простого проекта в командной строке:
$ npm init // feel free to enter whatever for these $ npm install --save express body-parser superagent $ touch index.js
Это установит наши основные зависимости и создают наш файл запуска. Открыть index.js В вашем текстовом редакторе выбора и вставьте следующее:
var express = require('express');
var bodyParser = require('body-parser');
var app = express();
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({extended: true}));
app.get('/', function (req, res) {
res.send('Hello World!');
});
app.listen(3000, function () {
console.log('Example app listening on port 3000!');
});
Затем в типе командной строки:
$ node index.js Example app listening on port 3000!
Если вы пойдете в свой браузер к http://localhost: 3000/ , вы должны увидеть простую страницу, которая говорит «Hello World!». С помощью этого настроены, теперь мы можем начать интегрировать немного глубже.
Добавление формы регистрации
Мы создадим очень простую HTML-страницу в Просмотров/регистрация .html который принимает имя, фамилию и адрес электронной почты:
Sign Up
В нашем index.js Нам нужно обслуживать статические файлы, поэтому, пожалуйста, добавьте следующую строку:
app.use(express.static('views'));
Мы также хотим обрабатывать представление формы; Так что на данный момент добавьте следующее в index.js.
app.post('/signup', function (req, res) {
// save user details to your database.
res.send('Signed Up!');
});
Теперь, когда вы повторно запустите приложение и регистрацию, вы должны увидеть следующее:
Сохранение нашего нового пользователя в MailChimp
Я собираюсь полагать, что у вас есть база данных где-то, чтобы сохранить этот пользователь, поэтому давайте пропустим прямо, чтобы сохранить этот пользователь в новый список в MailChimp.
Нам понадобится следующая информация из MailChimp, чтобы сделать звонки:
Ваш токен API – Войдите в свою учетную запись MailChimp и перейдите в
Профильв правом верхнем углу. Тогда наПрофильСтраница Перейти кДополнительно->API КлючОтказ Прокрутите вниз, и если у вас нет возможности, то нажмитеСоздать ключ:- Экземпляр вашего сервера – Это также встроен в ваш токен API. Это взято из последних символов после
-Отказ Например, мой токен API это637274B5AB272AFFBF7DF7D3723EA2A1-US6Поэтому мой экземпляр сервера –US6Отказ Уникальный список ID – Это для списка, который вы хотите добавить людей. Для этого нажмите на
Списки, найдите свой список, затем в правой части руки щелкните стрелку выпадания, затем выберитеНастройкии прокрутите вниз на этой странице книзу, где вы должны увидетьУникальный идентификатор для списка <Ваше название списка>:
Со всеми из них мы готовы сделать некоторые отдохнуть звонки! Я лично предпочитаю использовать библиотеку под названием SuperaGent Чтобы отдохнуть вызовы (мы установили его с нашими начальными NPM модули).
В верхней части нашего index.js Load SuperaGent:
var request = require('superagent');
Тогда мы обновим наше Регистрация Метод:
var mailchimpInstance = 'us6',
listUniqueId = 'b6a82d89f0',
mailchimpApiKey = '637274b5ab272affbf7df7d3723ea2a1-us6';
app.post('/signup', function (req, res) {
request
.post('https://' + mailchimpInstance + '.api.mailchimp.com/3.0/lists/' + listUniqueId + '/members/')
.set('Content-Type', 'application/json;charset=utf-8')
.set('Authorization', 'Basic ' + new Buffer('any:' + mailchimpApiKey ).toString('base64'))
.send({
'email_address': req.body.email,
'status': 'subscribed',
'merge_fields': {
'FNAME': req.body.firstName,
'LNAME': req.body.lastName
}
})
.end(function(err, response) {
if (response.status < 300 || (response.status === 400 && response.body.title === "Member Exists")) {
res.send('Signed Up!');
} else {
res.send('Sign Up Failed :(');
}
});
});
Здесь мы добавили переменные для наших трех важных деталей информации: экземпляра MailChimp, уникальный идентификатор списка и наш ключ API. Тогда в нашем пост Обработчик, мы делаем Пост Запрос на API MailChimp List Management API. Мы устанавливаем следующие заголовки HTTP:
Content-Type– быть персонажами JSON и UTF-8Авторизация– Мы Base64 кодируют нашу клавишу API MailChimp и передайте его как основной токен авторизации.
Затем мы отправляем данные для нового контакта, который мы хотим добавить, в том числе:
- Их адрес электронной почты;
- Что мы хотим, чтобы их статус был в списке рассылки. Это может быть разовым:
Подписан,отписывается,В ожиданиииочищенный; а также - Значения, которые мы хотим установить для
Merge_fieldsв этом списке. Поля Merge позволяют добавлять дополнительные данные в контакт в списке рассылки. Например, вы можете хранить номера телефонов, даты рождений, имен компаний и т. Д. В этом примере мы просто добавим имя и фамилия
Наконец-то мы слушаем ответ, зарегистрировав конец обработчик. Здесь мы проверяем на два состояния изначально. Если состояние составляет менее 300, это означает, что пользователь был успешно добавлен, или если мы вернемся на HTTP-статус 400, но название в ответе говорится, что Участник существует Затем адрес электронной почты уже находится в этом списке. В обоих случаях мы можем сообщить пользователю, что они успешно подписались. Если мы получим какой-либо другой код состояния, то что-то пошло не так. В этой ситуации вы, вероятно, захотите позволить пользователю попробовать еще раз или поднять оповещение для себя и вручную исправить его.
И если мы пойдем проверить наш список mailChimp, мы должны увидеть один новый участник:
2. Позволяя своим пользователям интегрироваться со своей учетной записью MailChimp
Теперь мы добавляем наших пользователей, не так ли это удивительно позволить нашим пользователям интегрировать наше приложение с их учетной записью MailChimp? Некоторые распространенные случаи использования:
- Возможно, вы хотите предложить функциональность списка рассылки, не написав ее самостоятельно, например, если вы пишете CRM, торговую платформу или услугу блогов;
- Импортируйте контакты для предварительной заправки списка контактов ваших пользователей; или к
- Создайте и отправьте электронные письма по электронной почте от своего имени в вашем приложении.
В нашем примере мы видим быстрый взгляд на то, как мы могли бы импортировать все контакты из существующего списка рассылки в MailChimp в наш собственный магазин данных. Мы сделаем это на 3 этапа:
- Мы будем использовать OAuth и позволить пользователю предоставить нам доступ к их учетной записи MailChimp
- С этой аутентификацией предоставим, мы возьмем доступные списки и выбираете, какой из них они хотят синхронизировать членам
- Мы будем схватить все члены и хранить их!
Так что давайте будем растрескиваться!
Использование OAuth для получения доступа к учетной записи пользователей
Чтобы получить доступ к учетной записи другого пользователя на MailChimp, нам нужно зарегистрировать себя как приложение на платформе:
- Войдите в свою учетную запись MailChimp и перейдите в
Профильна правом верхнем углу. Тогда наПрофильСтраница, перейдите вДополнительно->Зарегистрированные приложенияОтказ НажмитеЗарегистрируйте приложениеОтказ Затем вы будете представлены с формой, чтобы заполнить детали вашего приложения:
По большей части вы можете установить эти значения на все, что имеет смысл. Действительно важно, хотя это Перенаправить URI Отказ Это URL в нашем применении, где MailChimp будет перенаправлять пользователей, как только они будут аутентифицированы. Поскольку мы собираемся запустить это на нашей местной машине, нам нужно установить это:
http://127.0.0.1:3000/mailchimp/auth/callback
После нажатия Создать приложение Вам будет сообщено, ваше приложение создано. На этой странице прокрутите вниз, и вы найдете два очень важных предмета информации:
ID клиентаСекрет клиента
Теперь давайте создадим простую страницу в нашем Виды каталог, который будет вызвать наш поток под названием Integrated-mailChimp.html :
Integrate MailChimp
Connect with MailChimp
Далее нам нужно подключить Экспресс обработчик для обработки звонка к /MailChimp/Auth/Authorize :
var querystring = require('querystring');
var mailchimpClientId = 'xxxxxxxxxxxxxxxx';
app.get('/mailchimp/auth/authorize', function(req, res) {
res.redirect('https://login.mailchimp.com/oauth2/authorize?' +
querystring.stringify({
'response_type': 'code',
'client_id': mailchimpClientId,
'redirect_uri': 'http://127.0.0.1:3000/mailchimp/auth/callback'
}));
});
Вставьте свой идентификатор клиента MailChimp от ранее, а затем перезапустите свой сервер и нажмите нашу новую страницу: http://localhost: 3000/Интеграция-mailChimp.html :
Если вы попробуете его, вы должны увидеть, что при нажатии кнопки вы просите войти в MailChimp. Затем впоследствии вы вернулись на страницу на вашей местной машине, – это идеально. Теперь нам нужно обрабатывать обратный вызов OAuth от MailChimp.
Обратный вызов OAuth должен сделать следующее:
- Запросить
Access_Tokenдля пользователя. Это необходимо для того, чтобы сделать все будущие запросы для этого пользователя - Запрос на ОАУТ
Метаданныедля использования. Это содержит информацию о том, какую конечную точку API нам нужно поговорить с этим пользователем - Сохранить вышеуказанную информацию для пользователя для будущих взаимодействий с MailChimp
Давайте посмотрим код для этого:
var mailchimpSecretKey = 'xxxxxxxxxxxxxxxxxxxx';
var dataStore = require('./dataStore.js');
app.get('/mailchimp/auth/callback', function(req, res) {
request.post('https://login.mailchimp.com/oauth2/token')
.send(querystring.stringify({
'grant_type': 'authorization_code',
'client_id': mailchimpClientId,
'client_secret': mailchimpSecretKey,
'redirect_uri': 'http://127.0.0.1:3000/mailchimp/auth/callback',
'code': req.query.code
}))
.end((err, result) => {
if (err) {
res.send('An unexpected error occured while trying to perform MailChimp oAuth');
} else {
// we need to get the metadata for the user
request.get('https://login.mailchimp.com/oauth2/metadata')
.set('Accept', 'application/json')
.set('Authorization', 'OAuth ' + result.body.access_token)
.end((err, metaResult) => {
if (err) {
res.send('An unexpected error occured while trying to get MailChimp meta oAuth');
} else {
// save the result.body.access_token
// save the metadata in metaResult.body
// against the current user
var mailchimpConf = metaResult;
mailchimpConf.access_token = result.body.access_token;
dataStore.saveMailChimpForUser(mailchimpConf.login.email, metaResult);
res.redirect('/pick-a-list.html?email=' + mailchimpConf.login.email)
}
});
}
});
});
Напомнить себя, вышеупомянутый обработчик призван после того, как пользователь вошел в MailChimp для нас, и нам дают временную Код с которым мы можем запрашивать долгоживущие Access_Token Отказ Как только мы получим Access_Token Мы немедленно сделаем второй призыв для отдыха, чтобы получить наш пользователя Метаданные Отказ Метаданные Вернулся выглядит как:
{
"dc": "us6",
"role": "owner",
"accountname": "mattgoldspink",
"user_id": 15048915,
"login": {
"email": "mattgoldspink1@gmail.com",
"avatar": null,
"login_id": 15048915,
"login_name": "mattgoldspink",
"login_email": "mattgoldspink1@gmail.com"
},
"login_url": "https://login.mailchimp.com",
"api_endpoint": "https://us6.api.mailchimp.com"
}
В приведенном выше ответе JSON самая важная информация является API_ENDPOINT Отказ Все будущие запросы на отдых для этого пользователя на MailChimp должны быть сделаны на этот сервер.
Для простоты я создал очень простой в памяти datastore.js Файл, который выглядит как:
var simpleInMemoryDataStore = {
mailchimpConf: {}
};
module.exports = {
saveMailChimpForUser: function(email, mailchimpConf) {
simpleInMemoryDataStore.mailchimpConf[email] = mailchimpConf;
},
getMailChimpForUser: function(email) {
return simpleInMemoryDataStore.mailchimpConf[email];
}
};
Я оставлю реальное упражнение с сохранением этой информации и Access_Token Как упражнение для читателя, поскольку решение для хранения данных каждого отличается.
Получение списков пользователя
Теперь мы можем начать строить простой пользовательский интерфейс, который позволяет пользователю выбрать свой список, а затем импортировать участников. После подключения к MailChimp мы перенаправляем пользователя к Pick-a-list.html страница.
Давайте напишем эту страницу:
Pick A List From MailChimp
Pick a List
Choose which list to sync your Members from:
Я сохранил логику очень просто здесь. Когда нагрузки страницы мы получаем Email Адрес из URL, используя URLSearchParams Отказ Затем мы просто выполняем запрос AJAX на нашу BackeND, чтобы получить все списки рассылки для текущего пользователя. После этого возвращается, мы добавляем их как <опция> в наше Выберите Отказ
Бэкэндская служба, которая способствует это выглядит:
app.get('/mailchimp/lists', function(req, res) {
var mailchimpConf = dataStore.getMailChimpForUser(req.query.email);
request.get(mailchimpConf.api_endpoint + '/3.0/lists')
.set('Accept', 'application/json')
.set('Authorization', 'OAuth ' + mailchimpConf.access_token)
.end((err, result) => {
if (err) {
res.status(500).json(err);
} else {
res.json(result.body.lists);
}
});
});
Мы просто извлекаем конфигурацию MailChimp для пользователя из наших DataStore и сделать отдых запрос на API списка MailChimp. Обратите внимание, что мы создаем API MailChimp Read, используя API_ENDPOINT Мы хранили для пользователя. Мы также должны передать ОАУТ Access_Token для пользователя, чтобы аутентифицироваться на свой счет.
Если вы перезагрузите свой сервер и повторите аутентификацию с MailChimp, вы должны увидеть Выберите Список на странице, заполненной вашими списками рассылки!
Получение членов списка
Теперь, когда у нас есть все списки рассылки пользователя, когда они выбирают один, мы должны получить все контакты в этом списке, чтобы мы могли:
- отображать их в интерфейсе UI
- Синхронизировать их в нашей базе данных для пользователя.
Во-первых, на нашей стороне клиента мы обновим наше Pick-a-list.html Страница, добавив:
- Простая таблица HTML, чтобы показать участники
- и обработчик jQuery, чтобы послушать изменение выбора:
Members
| First Name | Last Name |
|---|
Итак, здесь мы добавили новую часть на страницу, которая включает в себя простой HTML-таблица для рендеринга наших членов. Тогда мы добавили наши Изменить Обработчик, который делает запрос AJAX на нашу бэкэнду, чтобы получить список списков. Отвечая, мы просто очищаем тело стола и добавим наших новых членов.
Давайте посмотрим на нашу Backeng Service для этого:
app.get('/mailchimp/list/members/:id', function(req, res) {
var mailchimpConf = dataStore.getMailChimpForUser(req.query.email);
request.get(mailchimpConf.api_endpoint + '/3.0/lists/' + req.params.id + '/members')
.set('Accept', 'application/json')
.set('Authorization', 'OAuth ' + mailchimpConf.access_token)
.end((err, result) => {
if (err) {
res.status(500).json(err);
} else {
res.json(result.body.members);
}
});
});
Если вы сравните это с нашим более ранним вызовом, чтобы получить списки, вы увидите, что он почти идентичен. На самом деле все будущие API звонит в MailChimp, теперь становятся очень простыми!
Если вы перезагрузите свой сервер и попробуйте это, вы увидите, что таблица теперь заполнится после выбора списка рассылки:
3. Куда идти отсюда?
Теперь, когда у вас есть список участников, вы можете легко сохранить их в магазин данных. У каждого участника есть идентификатор, который используется, чтобы посмотреть его в MailChimp. Поэтому, если вы хотели синхронизировать изменения в этом пользователю в MailChimp, вы просто сделаете HTTP Патч Позвоните в конечную точку участников. И в тело запроса добавьте эти изменения:
request.patch(mailchimpConf.api_endpoint + '/3.0/lists/' + req.params.id + '/members/' + req.params.memberId)
.set('Accept', 'application/json')
.set('Authorization', 'OAuth ' + mailchimpConf.access_token)
.send({"merge_fields":{"FNAME":"new","LNAME":"name"})
.end(...)
API MailChimp Rest API чрезвычайно богаты и поддерживает просмотр и редактирование всех видов данных, в том числе:
- Добавление заметок в список почтовых списков.
- Создавайте новые кампании.
- Создать и просмотреть шаблоны электронной почты.
- Отображать отчеты.
- Даже управлять магазинами электронной коммерции.
Оформить заказ их документации API для всех доступных конечных точек, с которыми вы можете взаимодействовать с: http://developer.mailchimp.com/documentation/mailchimp/reference/overview/