Gmail API یک راه حل قدرتمند و انعطاف پذیر برای ادغام ویژگی های قوی Gmail در برنامه شما ارائه می دهد. با استفاده از آن، می‌توانید به کاربران امکان خواندن، ارسال و سازماندهی ایمیل‌های خود، مدیریت پیش‌نویس‌ها، برچسب‌ها و موارد دیگر را بدهید. این راهنما شما را از طریق مراحل یکپارچه سازی Gmail API راهنمایی می کند و برنامه شما را به یک مرکز متمرکز برای مدیریت ایمیل تبدیل می کند.
چه در حال توسعه یک ابزار بهره‌وری، یک سیستم مدیریت ارتباط با مشتری (CRM) یا هر برنامه‌ای که از تعاملات ایمیلی کارآمد سود میبرد، این راهنما شما را به دانش و ابزارهای لازم مجهز می‌کند. ما همه چیز را از راه‌اندازی دسترسی API و مدیریت احراز هویت گرفته تا اجرای عملکردهای ایمیل اصلی را پوشش خواهیم داد.
پیاده سازی قوی تر از یک سرویس گیرنده Gmail با استفاده از API های Gmail را می توانید در اینجا پیدا کنید github.com/Goodness-Chukwudi/gmail-client.
راه اندازی پروژه Gmail خود در Google Cloud Console
1. یک پروژه ایجاد کنید. برای ایجاد و راه اندازی پروژه خود در کنسول ابری Google، به console.cloud.google.com بروید و با حساب جیمیل خود وارد شوید. از منوی کشویی پروژه در گوشه سمت چپ بالا، یک پروژه جدید ایجاد کنید یا در صورت وجود پروژه موجود را انتخاب کنید.
پس از ایجاد پروژه، انتخاب کنید APIs and services از منوی پیمایش در گوشه بالا سمت چپ.
2. Gmail API ها را فعال کنید. را کلیک کنید + ENABLE APIS AND SERVICES در بالای صفحه. با این کار صفحه کتابخانه API باز می شود. جستجو برای Gmail API آن را انتخاب کرده و روی آن کلیک کنید Enable برای فعال کردن Gmail API.
3. اعتبارنامه برای برنامه خود ایجاد کنید. برای ایجاد اعتباری که برای اتصال از برنامه خود استفاده می کنید، روی آن کلیک کنید Credentials در نوار کناری زیر APIs and services و بر روی کلیک کنید + CREATE CREDENTIALS در بالای صفحه نمایش انتخاب کنید OAuth Client ID، انتخاب کنید Web application به عنوان برنامه نوع و کلیک کنید Create. را کپی کنید Client ID و Client secret; برای اتصال به پروژه Google خود از برنامه Node.js به آن نیاز دارید.
4. تنظیم صفحه OAuth. شما از OAuth برای دسترسی برنامه خود به صندوق پستی کاربر استفاده خواهید کرد. انتخاب کنید OAuth consent screen زیر Credentials و نام برنامه، ایمیل پشتیبانی و سایر جزئیات را پر کنید. برای تنظیم دامنه ها زحمت ندهید، این کار را از طریق برنامه خود انجام خواهید داد. پس از انجام این کار، برای نوشتن کد به سیستم خود می روید
راه اندازی کد و یکپارچه سازی API
این آموزش برای افرادی است که قبلاً از Node.js آگاهی دارند. در نتیجه، راهنمای نصب و راه اندازی یک برنامه Node.js را پوشش نمی دهد.
1. راه اندازی پروژه و نصب وابستگی. پس از راه اندازی پروژه Node.js، در ترمینال خود اجرا کنید npm i googleapis برای نصب googleapis از npm. اعتبارنامه هایی که ایجاد کرده اید را به خود اضافه کنید .env فایل: GOOGLE_CLIENT_ID، GOOGLE_CLIENT_SECRET، GMAIL_REDIRECT_URL(در حین احراز هویت OAuth، گوگل در صورت موفقیت آمیز بودن، این نقطه پایانی را با کد احراز هویت فراخوانی می کند). آدرس ریدایرکت باید یک آدرس اینترنتی زنده در دامنه سرور شما باشد، اما می‌توانید از ngrok برای نمایش لوکال هاست خود در اینترنت استفاده کنید تا ما را قادر به دریافت تغییر مسیر در طی احراز هویت OAuth کنیم. به ngrok.com بروید و دستورالعمل های آنجا را دنبال کنید تا ngrok را به صورت محلی تنظیم کنید. هنگامی که ngrok را راه اندازی کردید، URL تغییر مسیر باید در این قالب باشد
2. احراز هویت OAuth. یک فایل ایجاد کنید، بگویید gmail_service.js برای کد تماس های Gmail API شما. googleapis را وارد کنید و OAuth2 و سرویس گیرنده Gmail را از googleapis مقداردهی کنید. ما از Nodemailer’s MailComposer برای نوشتن یک پیام MIME برای ایمیل های خود استفاده خواهیم کرد. بنابراین پیش بروید و nodemailer را از npm نصب کنید: npm i nodemailer. بعداً به آن نیاز خواهید داشت.
import { google } from "googleapis";
const MailComposer = require("nodemailer/lib/mail-composer");
const oauth2Client = new google.auth.OAuth2(
process.env.GOOGLE_CLIENT_ID,
process.env.GOOGLE_CLIENT_SECRET,
process.env.GMAIL_REDIRECT_URL
);
google.options({auth: oauth2Client})
const gmailClient = google.gmail('v1');
تنظیم تأیید اعتبار در سرویس گیرنده Gmail با مشتری OAuth، درخواست برنامه ما به پروژه Google ما را تأیید می کند.
3. آدرس صفحه رضایت را ایجاد کنید با استفاده از مشتری OAuth2 و آن را در مرورگر باز کنید تا به برنامه دسترسی داشته باشید. در یک سناریوی دنیای واقعی، این آدرس اینترنتی به قسمت جلویی برنامه شما برگردانده می شود. این به کاربر امکان می دهد تا به برنامه شما اجازه دسترسی به ایمیل خود را بدهد.
const scopes = [
"https://www.googleapis.com/auth/gmail.labels",
"https://www.googleapis.com/auth/gmail.modify",
];
const url = oauth2Client.generateAuthUrl({
access_type: "offline",
scope: scopes,
prompt: "consent"
});
console.log(url)
دامنه نوع دسترسی و سطح دسترسی را که برنامه از کاربر درخواست می کند، مشخص می کند. برای اطلاعات بیشتر در مورد دامنه ها به developers.google.com/gmail/api/auth/scopes مراجعه کنید.
4. رمز رفرش را از کد auth استخراج کنید. شما باید مسیری را مشخص کنید که با URL تغییر مسیری که در برنامه خود مشخص کرده اید مطابقت داشته باشد. این مسیر باید یک نقطه پایانی GET باشد. هنگامی که احراز هویت OAuth کامل شد، Google آدرس اینترنتی تغییر مسیر شما را با کد احراز هویت در درخواست درخواست فراخوانی می‌کند. با استفاده از سرویس گیرنده OAuth، اعتبار را از کد برگشتی استخراج کنید. نشانه استخراج شده یک شی است که حاوی نشانه رفرش در میان فیلدهای دیگر است. این نشانه به‌روزرسانی باید در مکانی امن، ترجیحاً در DB شما ذخیره شود. این نشانه به‌روزرسانی در کنار هر درخواست به API برای این کاربر ارسال می‌شود و اعتبار آن را تأیید می‌کند.
import { Router } from "express";
const router = Router();
router.get("[path]", async (req, res) => {
const code = req.query.code as string;
const {tokens} = await oauth2Client.getToken(code)
oauth2Client.setCredentials(tokens);
console.log("refresh_token =========> ", tokens.refresh_token);
})
دسترسی به APIهای Gmail
اکنون که سرویس گیرنده Gmail شما راه اندازی و احراز هویت شده است، اکنون می توانید برای مدیریت صندوق ورودی ایمیل، ارسال ایمیل و موارد دیگر با API Gmail تماس بگیرید. به developers.google.com/gmail/api/guides بروید تا همه APIهای موجود و موارد استفاده آنها را ببینید.
1. بازیابی پیام ها. روش فهرست پیام‌ها را در صندوق پستی ارائه شده بازیابی می‌کند. me به ایمیل کاربر پیوست شده به نشانه رفرش درخواست اشاره دارد. می توانید جایگزین کنید me با آدرس ایمیل واقعی
function retrieveMessages() {
const messagesResponse = await gmailClient.users.messages.list({userId: 'me'});
const messages = messagesResponse.data.messages;
console.log("messages =========> ", messages);
}
await retrieveMessages();
2. یک پیام دریافت کنید.
function getOneMessage(messageId) {
const messageResponse = await gmailClient.users.messages.get({userId: 'me', id: messageId});
const message = messageResponse.data;
let messageBody = "";
const body = message.payload?.parts ? message.payload.parts[1].body : message.payload?.body;
if (body?.data) {
const buffer = Buffer.from(body.data, "base64");
messageBody = buffer.toString("utf-8");
}
//For messages with attachments
if (body?.attachmentId) {
const textPart = message.payload?.parts[0]?.parts[1]?.body?.data;
if (textPart) {
const buffer = Buffer.from(textPart, "base64");
messageBody = buffer.toString("utf-8");
}
}
console.log("message =========> ", messageBody);
}
await getOneMessage(messageId);
3. فهرست پیش نویس ها. روش لیست پیش نویس ها را در صندوق پستی ارائه شده فهرست می کند.
function listDrafts() {
const draftsResponse = await gmailClient.users.drafts.list({userId: 'me'});
const drafts = draftsResponse.data.drafts;
console.log("drafts =========> ", drafts);
}
await listDrafts();
4. یک پیش نویس دریافت کنید
function getOneDraft(draftId) {
const draftResponse = await gmailClient.users.drafts.get({userId: 'me', id: draftId});
const draft = draftResponse.data;
const payload = draft.message?.payload;
let messageBody = "";
const body = payload?.parts ? payload.parts[1].body : payload?.body;
if (body?.data) {
const buffer = Buffer.from(body.data, "base64");
messageBody = buffer.toString("utf-8");
}
//For drafts with attachments
if (body?.attachmentId) {
//@ts-ignore
const textPart = payload?.parts[0]?.parts[1]?.body?.data;
if (textPart) {
const buffer = Buffer.from(textPart, "base64");
messageBody = buffer.toString("utf-8");
}
}
console.log("draft =========> ", messageBody);
}
await getOneDraft(draftId);
5. برچسب ها را فهرست کنید.
function listLabels() {
const labelsResponse = await gmailClient.users.labels.list({userId: 'me'});
const labels = labelsResponse.data.labels;
console.log("labels =========> ", labels);
}
await listLabels();
6. یک پیام را حذف کنید. یک پیام با اضافه کردن یک حذف می شود TRASH به آن برچسب بزنید برای اطلاعات بیشتر در مورد برچسب های پیام به developers.google.com/gmail/api/guides/labels بروید.
function deleteMessage(messageId) {
await gmailClient.users.messages.trash({userId: 'me', id: messageId});
}
await deleteMessage(messageId);
7. پیام ها را به صورت دسته ای حذف کنید. برای حذف چند پیام در یک حرکت، اضافه کنید TRASH به برچسب هر پیام
function deleteMessages(messageIds) {
const requestBody = {ids: messageIds, addLabelIds: ["TRASH"]};
await gmailClient.users.messages.batchModify({userId: 'me', requestBody});
}
await deleteMessages(messageIds);
8. یک پیام حذف شده را بازیابی کنید.
function restoreMessage(messageId) {
await gmailClient.users.messages.untrash({userId: 'me', id: messageId});
}
await restoreMessage(messageId);
9. ارسال نامه. API ایمیل فقط پیام‌های ایمیل MIME را می‌پذیرد که با RFC 2822 مطابقت داشته و به‌عنوان رشته base64 کدگذاری شده‌اند.
function encodeEmail(email) {
const mail = new MailComposer({
from: "me",
to: email.recipient,
cc: email.cc,
html: email.body,
subject: email.subject,
textEncoding: "base64"
});
mail.compile().build((err, message) => {
if (err) console.log(err);
const encodedEmail = Buffer
.from(message)
.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
return encodedEmail;
});
}
function sendMessage(emailObject) {
const requestBody = {
raw: await encodeEmail(emailObject)
}
await gmailClient.users.messages.send({userId: "me", requestBody});
}
await sendMessage(emailObject);
10. پیش نویس ایجاد کنید. پیش نویس ها نشان دهنده یک پیام ارسال نشده با DRAFT برچسب اعمال شد ورودی با ورودی های ارسال ایمیل API یکسان خواهد بود.
function createDraft(emailObject) {
const requestBody = {
raw: await encodeEmail()
}
await gmailClient.users.drafts.create({userId: 'me', requestBody});
}
await createDraft(emailObject);
11. پیش نویس ها را به روز کنید. پیام ها در واقع به روز نمی شوند. در عوض، درخواست به‌روزرسانی، پیام پیوست شده به پیش‌نویسی را که می‌خواهید به‌روزرسانی کنید، از بین میبرد و آن را با پیام جدیدی که حاوی پیام MIME جدیدی است که ارسال کرده‌اید، جایگزین می‌کند.
function updateDraft(emailObject, draftId) {
const requestBody = {
raw: await encodeEmail()
}
await gmailClient.users.drafts.update({userId: 'me', id: draftId, requestBody});
}
await updateDraft(emailObject, draftId);
12. پیش نویس ها را حذف کنید.
function deleteDraft(draftId) {
await gmailClient.users.drafts.delete({userId: 'me', id: draftId});
}
await deleteDraft(draftId);
13. پیش نویس ها را ارسال کنید.
function sendDraft(draftId) {
const requestBody = {
id: draftId
}
await gmailClient.users.drafts.send({userId: 'me', requestBody});
}
await sendDraft(draftId);
14. لغو دسترسی. اگرچه کاربران می توانند دسترسی داده شده به برنامه شما را از برنامه جیمیل خود لغو کنند، شما همچنین می توانید راهی برای لغو دسترسی از داخل برنامه خود با استفاده از revokeToken API.
function revokeAppAccess(refreshToken) {
await oauth2Client.revokeToken(refreshToken);
}
await revokeAppAccess(refreshToken);
نتیجه
فهرست کامل و راهنمای پیاده سازی برای همه ویژگی های موجود در Gmail API در developers.google.com/gmail/api/guides موجود است.
بعد چه می شود؟
اجرای قوی تر یک برنامه مشتری Gmail با مدیریت احراز هویت کاربر با استفاده از Node.js و Express.js و MongoDB در github.com/Goodness-Chukwudi/gmail-client در دسترس است. اگر آن را مفید می دانید، لطفاً یک ستاره در مخزن بگذارید. همچنین اگر می‌خواهید ویژگی‌های بیشتری را به اشتراک بگذارید یا ویژگی‌های موجود را بهبود ببخشید، می‌توانید یک روابط عمومی را مطرح کنید. از پیشنهادات نیز استقبال می شود. با من در ibechechukwudi@gmail.com تماس بگیرید
