2017-11-08
Введение.
Gmail API является RESTful API, которое можно использовать для доступа к почтовым сообщениям пользователя и отправлять электронные сообщения. Для большинства веб приложений (включая мобильные приложения), Gmail API является лучшим выбором для авторизованного доступа к пользовательским данным Gmail.
Gmail API дает вам гибкий RESTful доступ к пользовательскому почтовому ящику с естественным интерфейсом к Threads, Messages, Labels, Drafts, History, и Settings. Этот интерфейс реализован на многих современных языках программирования. Ваше приложение может использовать это API, чтобы опеспечить следущие возможности Gmail:
- Читать сообщения с Gmail;
- Передавать email сообщения;
- Поиск соответствующих сообщений;
- Создавать фильтры для автоматической маркировки, пересылки или архивирования сообщений.
Все что вам необходимо чтобы использовать Gmail API - это выбрать клиенскую библиотеку для вашего языка программирования и ваше приложение должно уметь авторизировать пользователя Gmail.
Пример использования Gmail API на GitHub можно посмотреть здесь
Ресурсы
Загрузка/Инициализация клиенской библиотеки Google API
Вначале нужно загрузить и инициализировать клиенскую библиотеку Google API см. пр.1.
пр.1
...
/**
* Google Client load/init
* @param params (Object)
* etc. {
* apiKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
* clientId: 'xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com',
* discoveryDocs: ['https://www.googleapis.com/discovery/v1/apis/gmail/v1/rest'],
* scope: 'https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.send'
* }
* @return {Promise}
*/
loadClient (params) {
return new Promise(function (resolve, reject) {
_loadGoogleApi().then(function () {
if (debug) {
console.log('loadGoogleAPI - OK')
}
return _initClient(params)
}).then(function () {
if (debug) {
console.log('googleClient.init - OK')
}
// Load gmail library
window.gapi.client.load('gmail', 'v1', resolve)
})
})
}
/**
* Load google api
* @return {Promise}
* @private
*/
_loadGoogleApi () {
return new Promise(function (resolve, reject) {
const script = document.createElement('script')
script.src = 'https://apis.google.com/js/platform.js'
script.onreadystatechange = script.onload = function () {
if (!script.readyState || /loaded|complete/.test(script.readyState)) {
setTimeout(function () {
resolve()
}, 500)
}
}
document.getElementsByTagName('head')[0].appendChild(script)
})
}
/**
* Google client load/init
* @param params (Object)
* etc. {
* apiKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
* clientId: 'xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com',
* discoveryDocs: ['https://www.googleapis.com/discovery/v1/apis/gmail/v1/rest'],
* scope: 'https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.send'
* }
* @return {Promise}
* @private
*/
_initClient (params) {
return new Promise(function (resolve, reject) {
// Client Init
const initClient = function () {
window.gapi.client.init(params).then(() => {
resolve()
}, (error) => {
console.error('gapi.client.init - Error', error)
alert(`gapi.client.init - Error: ${error.error}\n Details: ${error.details}`)
})
}
window.gapi.load('client:auth2', initClient)
})
}
...
Передача email сообщений (Users.messages: send)
Отправляет указанное сообщение получателям в To, Cc, Bcc заголовках.
Этот метод поддерживает /upload URI и может передавать медиа со следующими характеристиками:
- Максимальный размер файла: 35MB
- Предполагает Media MIME типы: message/rfc822
Более подробную информацию по передаче email сообщений можно посмотреть здесь
Прежде чем передать сообщение необходимо авторизироваться пользователю на Google сервере. Для этого нужно выполнить функцию авторизации, см. пр.2:
пр.2
...
/**
* Google SignIn
* @param successCallback (Function)
* @param errorCallback (Function)
*/
signIn (successCallback, errorCallback) {
window.gapi.auth2.getAuthInstance().signIn().then(function (googleUser) {
successCallback(googleUser)
if (debug) {
console.log('GoogleAuth.signIn - OK')
}
}, function (error) {
errorCallback(error)
console.log('GoogleAuth.signIn - Error: ', error)
})
}
...
После авторизации пользователя можно передать сообщение см. пр.3:
пр.3
...
/**
* Send email
* @param params
* etc.{
userId: 'me',
to: my@test.com,
subject: Request for my resume from the employer,
message: 'My Message!',
callback: function () {
....
}
* }
*/
send (params) {
try {
const headers = {
'To': params.to,
'Subject': params.subject,
'Content-Type': 'text/html; charset="UTF-8"'
}
let email = ''
_.forEach(headers, function (value, key) {
email += `${key}: ${value}` + '\r\n'
})
email += '\r\n' + params.message
const base64EncodedEmail = _b64UrlEncodeUnicode(email)
const sendRequest = window.gapi.client.gmail.users.messages.send({
'userId': params.userId,
'resource': {
'raw': base64EncodedEmail
}
})
sendRequest.execute(params.callback)
} catch (e) {
throw e
}
}
/**
* To encode the unicode string into Base64-encoded-url value
*
* @param str
* @return {string}
*/
_b64UrlEncodeUnicode (str) {
// first we use encodeURIComponent to get percent-encoded UTF-8,
// then we convert the percent encodings into raw bytes which
// can be fed into btoa.
const b64Encoded = btoa(encodeURIComponent(str).replace(/%([0-9A-F]{2})/g,
function toSolidBytes (match, p1) {
return String.fromCharCode('0x' + p1)
}))
// Replace for URL
return b64Encoded.replace(/\+/g, '-').replace(/\//g, '_')
}
...