نود Gmail در N8N
نود Gmail در N8N
نود Gmail در n8n راهی ساده و قدرتمند برای اتصال مستقیم ورکفلوها به صندوق ایمیل گوگل است؛ از خواندن و فیلتر کردن ایمیلهای ورودی گرفته تا ارسال ایمیلهای خودکار، پاسخ دادن، مدیریت لیبلها و پردازش پیوستها. اگر در پروژهها با اعلانها، پشتیبانی مشتری، گزارشگیری یا اتوماسیونهای اداری سروکار دارید، این نود یکی از کاربردیترین ابزارهای شما خواهد بود.
معرفی نود در N8N
نود Gmail برای انجام عملیات روی سرویس Gmail و پیامهای ایمیلی استفاده میشود. این نود معمولاً با احراز هویت OAuth2 به حساب گوگل متصل میشود و امکان اجرای عملیات رایج ایمیلی را در قالب یک ورکفلو فراهم میکند.
- کارکرد اصلی: ارسال ایمیل، جستجو/خواندن پیامها، دریافت جزئیات پیام، کار با لیبلها، مدیریت پیوستها، و انجام برخی عملیات مدیریتی روی پیامها.
- دستهبندی نود: Integration (یکپارچهسازی با سرویس Gmail). بسته به تنظیمات، میتواند نقش Action داشته باشد. برای تریگر ایمیلهای جدید معمولاً از Gmail Trigger یا IMAP Email Trigger استفاده میشود.
- اهمیت در ورکفلوها: ایمیل یکی از رایجترین کانالهای ورودی/خروجی در کسبوکار است. Gmail در n8n امکان میدهد فرآیندهایی مثل پاسخگویی خودکار، ثبت تیکت، آرشیو هوشمند، و ارسال گزارشهای زمانبندیشده بدون دخالت انسانی انجام شوند.
موارد استفاده
سناریوهای واقعی و متداول
- ثبت خودکار تیکت پشتیبانی: ایمیلهای ورودی به آدرس support@ را خوانده، اطلاعات فرستنده و موضوع را استخراج کرده و در ابزارهایی مثل Notion/Trello/Jira ثبت کنید.
- ارسال ایمیلهای اعلان (Notification): وقتی در سیستم شما رخدادی اتفاق میافتد (مثلاً پرداخت موفق یا خطای سرور)، یک ایمیل قالببندیشده برای تیم ارسال شود.
- پردازش فاکتورهای دریافتی: ایمیلهای دارای PDF را پیدا کنید، پیوست را دانلود کرده و به Google Drive/S3 آپلود کنید و سپس دادهها را به دیتابیس منتقل کنید.
- آرشیو و برچسبگذاری هوشمند: ایمیلهای شامل کلمات کلیدی خاص را لیبلگذاری و آرشیو کنید تا Inbox مرتب بماند.
- گزارش روزانه/هفتگی: خروجی یک Query یا گزارش از Google Sheets را گرفته و بهصورت ایمیل زمانبندیشده برای مدیر ارسال کنید.
ترکیب با نودهای دیگر برای ورکفلوهای عملی
- Schedule Trigger + Gmail: هر روز ساعت ۹ صبح گزارش را ایمیل کن.
- Webhook + Gmail: با دریافت رویداد از سایت/اپلیکیشن، ایمیل اطلاعرسانی ارسال کن.
- Gmail + IF + Slack: اگر ایمیل از دامنه مشتریان VIP بود، همزمان در Slack اطلاع بده.
- Gmail + Switch/Regex + Google Sheets: بسته به موضوع ایمیل، در شیت مربوطه ثبت و دستهبندی کن.
- Gmail + HTTP Request: محتوای ایمیل را به یک API (مثلاً سرویس تحلیل متن/هوش مصنوعی) بفرست و نتیجه را ذخیره کن.
پارامترها و تنظیمات
نام دقیق بعضی گزینهها ممکن است بسته به نسخه n8n کمی متفاوت باشد، اما منطق کلی و فیلدهای اصلی در نود Gmail ثابت است. در ادامه، مهمترین تنظیمات را به شکل کاربردی توضیح میدهد.
اعتبارسنجی (Credentials)
- Credential: Google (Gmail) OAuth2
نوع داده: تنظیمات اتصال
کاربرد: اتصال امن به حساب Gmail با OAuth2
مثال عملی: ساخت Credential با Client ID/Secret و دادن دسترسی Gmail به n8n، سپس انتخاب آن در نود Gmail
- Scopes (محدوده دسترسی):
نوع داده: لیست سطح دسترسی
کاربرد: تعیین میکند n8n چه کاری روی Gmail بتواند انجام دهد (خواندن، ارسال، مدیریت و …)
نکته: حداقل دسترسی لازم را انتخاب کنید. برای ارسال ایمیل معمولاً دسترسی ارسال/compose و برای خواندن ایمیل دسترسی readonly لازم است.
تنظیمات عمومی نود
- Resource (منبع):
نوع داده: انتخابی (Select)
کاربرد: تعیین میکند عملیات روی «Message» (پیام) انجام شود یا «Label» (لیبل) یا سایر منابع مرتبط
مثال: Resource = Message
- Operation (عملیات):
نوع داده: انتخابی (Select)
کاربرد: نوع کاری که باید انجام شود مثل Send, Get, Get Many/Search, Delete/Trash, Modify (Label/Read) و …
مثال: Operation = Send
پارامترهای رایج برای عملیات ارسال ایمیل (Message: Send)
- To:
نوع داده: رشته (String) یا لیست با جداکننده
کاربرد: گیرندگان اصلی ایمیل
مثال: user@example.com یا user1@example.com, user2@example.com
نکته: اگر از دادههای نودهای قبل استفاده میکنید، از Expression استفاده کنید؛ مثل {{ $json.email }}
- Subject:
نوع داده: رشته
کاربرد: موضوع ایمیل
مثال: گزارش روزانه فروش
- Message / Body:
نوع داده: رشته
کاربرد: متن ایمیل (متنی یا HTML بسته به گزینهها)
مثال: سلام، فایل گزارش پیوست شده است.
- HTML:
نوع داده: بولی (Boolean)
کاربرد: اگر فعال باشد، بدنه ایمیل به عنوان HTML ارسال میشود
مثال: فعال + Body = <h1>گزارش</h1><p>جزئیات…</p>
- Cc / Bcc:
نوع داده: رشته
کاربرد: گیرندههای رونوشت/رونوشت مخفی
مثال: cc-team@example.com
- Reply-To:
نوع داده: رشته
کاربرد: تعیین آدرس پاسخدهی
مثال: support@example.com
- Attachments:
نوع داده: باینری (Binary) یا مسیر/نام Property باینری
کاربرد: ارسال فایل پیوست
مثال عملی: ابتدا با نود HTTP Request فایل را دانلود کنید و خروجی را به صورت Binary نگه دارید، سپس در Gmail آن Binary Property (مثلاً data) را به عنوان پیوست ارسال کنید.
نکته: محدودیت اندازه پیوستهای Gmail را در نظر بگیرید (در عمل حدود 25MB برای هر ایمیل، با در نظر گرفتن overhead).
پارامترهای رایج برای عملیات خواندن/جستجو (Message: Get / Get Many / Search)
- Message ID:
نوع داده: رشته
کاربرد: دریافت جزئیات یک پیام مشخص
مثال: 185f1c2a1b0c3d1e
- Query (جستجوی Gmail):
نوع داده: رشته
کاربرد: فیلتر پیامها با سینتکس جستجوی Gmail
مثالهای عملی:
- from:billing@service.com has:attachment newer_than:7d
- subject:(invoice OR فاکتور) is:unread
- label:INBOX -category:social -category:promotions
- Include Spam and Trash:
نوع داده: بولی
کاربرد: اگر فعال باشد، پیامهای Spam/Trash هم در نتایج میآیند
نکته: معمولاً برای اتوماسیونهای عملی خاموش نگه داشته میشود مگر سناریوهای خاص.
- Return All / Limit:
نوع داده: بولی + عدد
کاربرد: تعیین تعداد نتایج
مثال: Return All = false و Limit = 20 برای جلوگیری از اجرای سنگین
- Format (فرمت دریافت پیام):
نوع داده: انتخابی
کاربرد: تعیین سطح جزئیات پیام (metadata/minimal/full/raw)
نکته: برای سرعت بالاتر از metadata استفاده کنید؛ برای استخراج متن و پیوستها معمولاً full یا raw لازم میشود.
پارامترهای رایج برای مدیریت پیام (Modify / Trash / Delete / Mark as Read)
- Add Label IDs / Remove Label IDs:
نوع داده: لیست رشته
کاربرد: لیبلگذاری یا حذف لیبل از پیامها
مثال عملی: Add = [“Label_123”] برای افزودن لیبل “Processed”
- Mark as Read:
نوع داده: بولی یا در قالب Modify با حذف UNREAD
کاربرد: جلوگیری از پردازش تکراری ایمیلها
نکته: بعد از پردازش موفق، پیام را Read یا به لیبل “Done” منتقل کنید.
نکات مهم هنگام پیکربندی
- استفاده از Query صحیح: جستجوی Gmail بسیار قدرتمند است؛ با طراحی Query مناسب، حجم پردازش کاهش مییابد.
- کنترل تکرار (Idempotency): اگر ایمیلها را میخوانید، پس از پردازش برچسب بزنید یا خواندهشده کنید تا دوباره پردازش نشوند.
- مدیریت پیوستها: پیوستها اغلب به صورت Binary در n8n مدیریت میشوند؛ مطمئن شوید گزینههای دانلود/استخراج پیوست فعال و Property باینری درست انتخاب شده است.
- محدودیتهای API و نرخ درخواست: در پردازش انبوه از Limit، زمانبندی و Split in Batches استفاده کنید.
ورودیها و خروجیها
ورودی (Input)
بسته به Operation، نود Gmail میتواند از آیتمهای ورودی برای مقداردهی فیلدها استفاده کند. مثلاً در ارسال ایمیل، To/Subject/Body میتوانند از دادههای ورودی با Expression خوانده شوند. برای پیوست، ورودی معمولاً شامل داده باینری (Binary) است.
خروجی (Output)
خروجی معمولاً یک یا چند آیتم JSON است که اطلاعات پیام/عملیات انجامشده را برمیگرداند. در عملیات خواندن پیامها ممکن است فیلدهای header، snippet، تاریخ، فرستنده/گیرنده و در صورت انتخاب فرمت کامل، payload و parts نیز بازگردانده شود. در عملیات ارسال، معمولاً شناسه پیام ارسالی و threadId برمیگردد.
نمونه ساختار خروجی JSON (ارسال ایمیل)
{ “id”: “185f1c2a1b0c3d1e”, “threadId”: “185f1c2a1b0c3d1e”, “labelIds”: [“SENT”] }
نمونه ساختار خروجی JSON (خواندن/جستجوی پیام با متادیتا)
{ “id”: “185f1c2a1b0c3d1e”, “threadId”: “185f1c2a1b0c3d1e”, “snippet”: “Hello, here is your invoice…”, “internalDate”: “1700000000000”, “payload”: { “headers”: [ { “name”: “From”, “value”: “Billing <billing@service.com>” }, { “name”: “To”, “value”: “you@gmail.com” }, { “name”: “Subject”, “value”: “Invoice #1234” } ] }, “labelIds”: [“INBOX”,”UNREAD”] }
نکته درباره باینری و پیوستها
اگر پیوستها دانلود شوند، n8n آنها را در بخش Binary هر آیتم نگه میدارد (مثلاً در propertyای مانند attachment_0 یا data). سپس میتوانید همان property را به نودهای دیگر مثل Google Drive، S3 یا Gmail (برای ارسال مجدد) متصل کنید.
نکات پیشرفته و ترفندها
- استفاده از Gmail Query برای فیلتر دقیق: بهجای دریافت همه پیامها و فیلتر کردن در n8n، Query را دقیق بنویسید. مثال: from:specific@domain.com is:unread has:attachment newer_than:2d
- پردازش انبوه با Split in Batches: اگر Get Many تعداد زیادی پیام برگرداند، با نود Split in Batches آنها را دستهای پردازش کنید تا هم پایدارتر باشد هم احتمال خطای Rate Limit کمتر شود.
- پیشگیری از پردازش تکراری: بعد از موفقیت، ایمیل را Read کنید یا لیبل “Processed” اضافه کنید. سپس در Query شرط -label:Processed یا is:unread بگذارید.
- استخراج فیلدهای Header با Function/Code: در خروجی Gmail، هدرها آرایهای از name/value هستند. با یک نود Code میتوانید به شکل Map تبدیل کنید تا دسترسی سادهتر شود (مثلاً subject، from).
- قالببندی ایمیل HTML: برای ایمیلهای حرفهای، HTML را فعال کنید و متن را با قالبهای ساده بسازید. برای دادههای دینامیک از Expression استفاده کنید، مثل {{ $json.total }}.
محدودیتها و خطاها
محدودیتها
- محدودیت حجم ایمیل و پیوست: ارسال پیوستهای بزرگتر از سقف Gmail ممکن نیست یا با خطا مواجه میشود.
- محدودیت نرخ درخواست (Rate Limits): اجرای سنگین (خصوصاً خواندن/دانلود پیوستهای زیاد) ممکن است باعث خطاهای 429 یا خطاهای سهمیه شود.
- پیچیدگی فرمت پیام: بدنه ایمیلها گاهی multipart هستند و استخراج متن HTML/Plain ممکن است نیاز به پردازش parts داشته باشد.
- وابستگی به OAuth و تنظیمات گوگل: اگر اپ در Google Cloud درست تنظیم نشود یا دسترسیها محدود باشد، اتصال برقرار نمیشود.
خطاهای رایج و راهحلها
- 401/403 Unauthorized/Forbidden:
- Credential را دوباره authorize کنید (توکن منقضی یا دسترسی لغو شده است).
- Scopes را بررسی کنید؛ ممکن است برای عملیات موردنظر کافی نباشند.
- اگر حساب سازمانی (Google Workspace) است، محدودیتهای Admin را بررسی کنید.
- 429 Too Many Requests:
- Limit را کاهش دهید و پردازش را Batch کنید.
- بین درخواستها Delay اضافه کنید یا اجرای زمانبندیشده انجام دهید.
- Bad Request در ارسال ایمیل:
- آدرسهای To/Cc/Bcc را از نظر فرمت بررسی کنید.
- اگر HTML فعال است، بدنه HTML را از نظر تگهای ناقص بررسی کنید.
- برای پیوستها مطمئن شوید Binary property درست انتخاب شده و داده واقعاً باینری است.
- عدم دریافت متن ایمیل (Body خالی):
- Format را روی full/raw بگذارید.
- ایمیل multipart است؛ باید از payload.parts متن مناسب (text/plain یا text/html) را استخراج کنید.
ایده ها
- دستیار ایمیل برای مدیر: هر ایمیل مهم را خلاصهسازی کنید و خلاصه را با برچسب Priority به Inbox برگردانید یا به Slack ارسال کنید.
- اتوماسیون فاکتور: ایمیلهای دارای PDF فاکتور را پیدا کنید، پیوست را ذخیره کنید، شماره فاکتور را استخراج کنید و در Google Sheets ثبت کنید.
- سیستم درخواست مرخصی: ایمیل با موضوع “Leave Request” را بخوانید، تاریخها را استخراج کنید و برای HR ایمیل تایید/رد بفرستید.
- فیلتر ضد هرزنامه سفارشی: ایمیلهای دارای الگوهای خاص را بهصورت خودکار Trash کنید و یک لیبل برای گزارشدهی نگه دارید.
- گزارش خطای سرویسها: اگر مانیتورینگ شما Webhook بزند، یک ایمیل با جزئیات خطا و لاگ پیوستشده برای تیم فنی ارسال شود.