اوتلوک
Microsoft Outlook
ارسال و دریافت ایمیل، مدیریت تقویم و مخاطبین Microsoft Outlook
نمای کلی
نود Microsoft Outlook یکی از جامعترین نودهای n8n برای کار با اکوسیستم Microsoft 365 است. این نود از Microsoft Graph API استفاده میکند و دسترسی یکپارچه به ایمیل، تقویم و مخاطبین Outlook فراهم میآورد.
قابلیتهای کلیدی:
- ارسال ایمیل با پیوست، CC و BCC
- دریافت و خواندن ایمیلها با فیلترهای پیشرفته OData
- مدیریت پوشههای ایمیل (ایجاد، حذف، انتقال)
- ایجاد و ارسال Draft (پیشنویس)
- پاسخ (Reply) و Forward کردن ایمیلها
- مدیریت پیوستها (دانلود و آپلود)
- ایجاد و مدیریت رویدادهای تقویم
- مدیریت مخاطبین (Contacts)
- حذف و انتقال ایمیل بین پوشهها
- پشتیبانی از HTML و Plain Text
مزایای استفاده:
- یکپارچگی کامل با Microsoft 365 و Azure AD
- استفاده از Microsoft Graph API (مدرن و قدرتمند)
- پشتیبانی از احراز هویت OAuth2 با Azure AD
- دسترسی به ایمیل، تقویم و مخاطبین در یک نود
- فیلترهای قدرتمند OData برای جستجوی پیشرفته
- مناسب برای سازمانهایی که از Microsoft 365 استفاده میکنند
- پشتیبانی از Shared Mailbox و Delegate Access
کاربردها:
- اتوماسیون ایمیلهای سازمانی
- پردازش خودکار ایمیلهای دریافتی
- همگامسازی تقویم بین پلتفرمها
- مدیریت مخاطبین و CRM
- سیستم Helpdesk و پشتیبانی ایمیلی
- ارسال خبرنامه و اعلانها
- آرشیو و بکآپ ایمیلها
احراز هویت
احراز هویت Microsoft Outlook
Microsoft Outlook از OAuth2 با Azure Active Directory (Azure AD / Entra ID) استفاده میکند.
روش 1: OAuth2 با Azure AD (توصیه میشود)
#### مرحله 1: ثبت اپلیکیشن در Azure Portal
- 1به [Azure Portal](https://portal.azure.com/) بروید
- 2به Azure Active Directory > App registrations بروید
- 3روی New registration کلیک کنید
- 4اطلاعات را پر کنید:
- Name: نام اپلیکیشن (مثل "n8n Outlook Integration")
- Supported account types: یکی از گزینهها را انتخاب کنید:
- Single tenant: فقط سازمان خودتان
- Multitenant: همه سازمانها
- Multitenant + Personal: سازمانی و شخصی
- Redirect URI: نوع Web و آدرس:
https://your-n8n.com/rest/oauth2-credential/callback
- 1Register کنید
- 2Application (client) ID و Directory (tenant) ID را یادداشت کنید
#### مرحله 2: ایجاد Client Secret
- 1در اپلیکیشن ثبت شده، به Certificates & secrets بروید
- 2New client secret کلیک کنید
- 3توضیحات و مدت اعتبار تعیین کنید (توصیه: 24 ماه)
- 4Add کنید
- 5Value (مقدار Secret) را فوراً کپی کنید (بعداً نمایش داده نمیشود)
#### مرحله 3: تنظیم API Permissions
- 1به API permissions بروید
- 2Add a permission > Microsoft Graph کلیک کنید
- 3Delegated permissions انتخاب کنید
- 4Permissionهای مورد نیاز:
Mail.Read- خواندن ایمیلMail.ReadWrite- خواندن و نوشتن ایمیلMail.Send- ارسال ایمیلCalendars.Read- خواندن تقویمCalendars.ReadWrite- خواندن و نوشتن تقویمContacts.Read- خواندن مخاطبینContacts.ReadWrite- خواندن و نوشتن مخاطبینUser.Read- خواندن پروفایل کاربرoffline_access- برای Refresh Token
- 1Grant admin consent کلیک کنید (اگر ادمین هستید)
#### مرحله 4: تنظیم در n8n
- 1در n8n به Credentials بروید
- 2Microsoft Outlook OAuth2 API را انتخاب کنید
- 3اطلاعات را وارد کنید:
- Client ID: از مرحله 1
- Client Secret: از مرحله 2
- **Tenant ID**: از مرحله 1 (یا
commonبرای Multi-tenant)
- 1Connect my account کلیک کنید
- 2با اکانت Microsoft خود وارد شوید
- 3Permissionها را تایید کنید
روش 2: Application Permissions (بدون تعامل کاربر)
برای سناریوهای سرور به سرور (Server-to-Server) بدون نیاز به ورود کاربر:
- 1مراحل 1 و 2 بالا را انجام دهید
- 2در API permissions، Application permissions انتخاب کنید (به جای Delegated)
- 3Permissionها:
Mail.Read(Application)Mail.ReadWrite(Application)Mail.Send(Application)Calendars.ReadWrite(Application)Contacts.ReadWrite(Application)
- 1Grant admin consent الزامی است
- 2در n8n از Client Credentials Flow استفاده کنید
Tenant ID Guide:
- Single Tenant: شناسه Tenant سازمان شما (GUID)
- **Multi-tenant**: از
commonیاorganizationsاستفاده کنید - **Personal Accounts**: از
consumersاستفاده کنید - **هر دو**: از
commonاستفاده کنید
نکات امنیتی:
- Client Secret را به اشتراک نگذارید
- حداقل Permission لازم را درخواست کنید
- Client Secret دارای تاریخ انقضاست، قبل از موعد تمدید کنید
- برای Production، Certificate به جای Secret توصیه میشود
- از Conditional Access Policies برای محدود کردن دسترسی استفاده کنید
- لاگهای Azure AD Sign-in را مانیتور کنید
عملیاتهای موجود
sendEmail
ارسال ایمیل جدید از طریق Microsoft Outlook با پشتیبانی از HTML، پیوست، CC و BCC
getEmail
خواندن یک ایمیل خاص با شناسه آن به همراه تمام جزئیات
listEmails
دریافت لیست ایمیلها از پوشه مشخص با فیلترهای OData
moveEmail
انتقال ایمیل از یک پوشه به پوشه دیگر
deleteEmail
حذف دائمی یا انتقال ایمیل به سطل زباله
replyToEmail
ارسال پاسخ (Reply یا Reply All) به یک ایمیل
forwardEmail
ارسال ایمیل به شخص دیگر (Forward)
createDraft
ایجاد ایمیل پیشنویس (Draft) بدون ارسال
sendDraft
ارسال ایمیل پیشنویسی که قبلاً ایجاد شده
listFolders
دریافت لیست پوشههای ایمیل (Mail Folders)
createFolder
ایجاد پوشه ایمیل جدید یا زیرپوشه
getAttachment
دانلود پیوست ایمیل به صورت Binary Data
createCalendarEvent
ایجاد رویداد جدید در تقویم Outlook با شرکتکنندگان و یادآوری
listContacts
دریافت لیست مخاطبین Outlook با فیلتر و جستجو
createContact
ایجاد مخاطب جدید در Outlook Contacts
markAsRead
علامتگذاری ایمیل به عنوان خوانده شده یا خوانده نشده
addFileAttachment
افزودن فایل پیوست به ایمیل یا Draft موجود
listCalendarEvents
دریافت لیست رویدادهای تقویم در بازه زمانی مشخص
کاربردهای متداول
1. ارسال ایمیل اعلان خودکار سازمانی
ارسال ایمیل خوشآمدگویی به کارمندان جدید:
Webhook (ثبت کارمند جدید)
→ Microsoft Outlook (sendEmail)
To: \${$json.email}
Subject: "به تیم ما خوش آمدید!"
Body: قالب HTML خوشآمدگویی با اطلاعات سازمان
Importance: Normal
CC: hr@company.com
→ Microsoft Outlook (createContact)
GivenName: \${$json.firstName}
Surname: \${$json.lastName}
EmailAddresses: [\${$json.email}]
CompanyName: "شرکت شما"
JobTitle: \${$json.position}2. پردازش خودکار ایمیلهای Helpdesk
خواندن ایمیلهای پشتیبانی و ایجاد تیکت:
Schedule (هر 5 دقیقه)
→ Microsoft Outlook (listEmails)
FolderId: inbox
Filter: "isRead eq false"
Top: 20
→ Loop (هر ایمیل)
→ IF (subject شامل "پشتیبانی" یا "Support")
→ MySQL (ایجاد تیکت)
Subject: \${$json.subject}
Body: \${$json.body.content}
From: \${$json.from.emailAddress.address}
→ Microsoft Outlook (replyToEmail)
Comment: "تیکت شما ثبت شد. شماره پیگیری: \${$json.ticketId}"
→ Microsoft Outlook (moveEmail)
DestinationId: "processed-folder-id"
→ Else
→ Microsoft Outlook (markAsRead)
IsRead: true3. همگامسازی تقویم Outlook با Google Calendar
Sync رویدادهای Outlook به Google Calendar:
Schedule (هر 30 دقیقه)
→ Microsoft Outlook (listCalendarEvents)
StartDateTime: \${$now.toISO()}
EndDateTime: \${$now.plus({days: 7}).toISO()}
→ Loop (هر رویداد)
→ Google Calendar (createEvent)
Summary: \${$json.subject}
Start: \${$json.start.dateTime}
End: \${$json.end.dateTime}
Description: \${$json.bodyPreview}
Attendees: \${$json.attendees.map(a => a.emailAddress.address)}4. اعلان جلسات Microsoft Teams
ارسال یادآوری جلسات آنلاین:
Schedule (هر روز ساعت 8 صبح)
→ Microsoft Outlook (listCalendarEvents)
StartDateTime: \${$today}
EndDateTime: \${$today.plus({days: 1})}
Filter: "isOnlineMeeting eq true"
→ Loop
→ Telegram (sendMessage)
Chat: گروه تیم
Text: "جلسه امروز: \${$json.subject} ساعت \${$json.start.dateTime}"
→ IF (30 دقیقه مانده به جلسه)
→ Slack (sendMessage)
Text: "یادآوری: جلسه \${$json.subject} تا 30 دقیقه دیگر شروع میشود"5. آرشیو خودکار ایمیلهای قدیمی
انتقال ایمیلهای قدیمی به پوشه آرشیو:
Schedule (هر هفته شنبه)
→ Microsoft Outlook (listEmails)
FolderId: inbox
Filter: "receivedDateTime lt \${$now.minus({days: 30}).toISO()}"
Top: 100
→ Loop
→ Microsoft Outlook (moveEmail)
DestinationId: "archive"
→ Gmail (sendEmail)
To: admin@company.com
Subject: "گزارش آرشیو هفتگی"
Body: "\${$json.length} ایمیل آرشیو شد"6. مدیریت مخاطبین و CRM
همگامسازی مخاطبین با دیتابیس:
Webhook (مخاطب جدید در CRM)
→ Microsoft Outlook (createContact)
GivenName: \${$json.firstName}
Surname: \${$json.lastName}
EmailAddresses: [{address: \${$json.email}, name: \${$json.fullName}}]
BusinessPhones: [\${$json.phone}]
CompanyName: \${$json.company}
JobTitle: \${$json.title}
PersonalNotes: "وارد شده از CRM - \${$json.source}"7. ارسال گزارش روزانه به مدیریت
تولید و ارسال خودکار گزارش:
Schedule (هر روز ساعت 18)
→ MySQL (آمار روزانه فروش)
→ Code (تولید جدول HTML)
→ Microsoft Outlook (sendEmail)
To: manager@company.com
Subject: "گزارش فروش - \${$today.toFormat('yyyy-MM-dd')}"
Body: \${$json.htmlReport}
BodyContentType: HTML
Importance: High
Attachments: فایل Excel8. Forward خودکار ایمیلهای مهم
ایمیلهای با اهمیت بالا را به مدیر Forward کنید:
Schedule (هر 10 دقیقه)
→ Microsoft Outlook (listEmails)
Filter: "importance eq 'high' and isRead eq false"
→ Loop
→ Microsoft Outlook (forwardEmail)
To: ceo@company.com
Comment: "ایمیل مهم از \${$json.from.emailAddress.address}"
→ Microsoft Outlook (markAsRead)
IsRead: true9. سیستم نوبتدهی با تقویم Outlook
رزرو وقت ملاقات:
Webhook (درخواست رزرو)
→ Microsoft Outlook (listCalendarEvents)
StartDateTime: \${$json.requestedDate}T08:00:00
EndDateTime: \${$json.requestedDate}T18:00:00
→ Code (یافتن اولین وقت آزاد)
→ IF (وقت آزاد موجود)
→ Microsoft Outlook (createCalendarEvent)
Subject: "نوبت: \${$json.clientName}"
Start: \${$json.availableSlot}
End: \${$json.availableSlotEnd}
Attendees: [\${$json.clientEmail}]
IsOnlineMeeting: true
ReminderMinutesBeforeStart: 30
→ Microsoft Outlook (sendEmail)
To: \${$json.clientEmail}
Subject: "تایید نوبت"
Body: "نوبت شما برای \${$json.date} ثبت شد"
→ Else
→ Respond (وقت خالی موجود نیست)10. پردازش فاکتور از ایمیلها
استخراج فاکتور از پیوستهای ایمیل:
Schedule (هر روز)
→ Microsoft Outlook (listEmails)
Filter: "hasAttachments eq true and subject contains 'فاکتور'"
→ Loop
→ Microsoft Outlook (getAttachment)
MessageId: \${$json.id}
AttachmentId: \${$json.attachments[0].id}
→ IF (فایل PDF)
→ Google Drive (آپلود فایل)
Folder: "فاکتورها"
→ MySQL (ثبت فاکتور)
→ Microsoft Outlook (moveEmail)
DestinationId: "invoices-folder-id"11. ارسال خبرنامه سازمانی
ارسال ایمیل انبوه به کارمندان:
Schedule (اول هر ماه)
→ MySQL (لیست کارمندان فعال)
→ Loop
→ Microsoft Outlook (sendEmail)
To: \${$json.email}
Subject: "خبرنامه ماهانه - \${$now.toFormat('MMMM yyyy')}"
Body: قالب HTML خبرنامه
Attachments: PDF خبرنامه
→ Wait (2 ثانیه - Rate Limiting)12. بکآپ مخاطبین به دیتابیس
همگامسازی دورهای مخاطبین:
Schedule (هر هفته)
→ Microsoft Outlook (listContacts)
Top: 500
→ Loop
→ MySQL (Upsert)
Table: contacts
Email: \${$json.emailAddresses[0].address}
Name: \${$json.displayName}
Phone: \${$json.mobilePhone}
Company: \${$json.companyName}
→ Telegram (گزارش بکآپ)نکات حرفهای
نکات حرفهای
- 1OData Filter Operators (اپراتورهای فیلتر):
eq → برابر isRead eq false
ne → نا برابر importance ne 'low'
gt → بزرگتر از receivedDateTime gt 2024-01-01
ge → بزرگتر یا مساوی
lt → کوچکتر از
le → کوچکتر یا مساوی
and → و isRead eq false and hasAttachments eq true
or → یا importance eq 'high' or importance eq 'urgent'
not → نقیض not isRead
contains() → شامل contains(subject, 'invoice')
startsWith() → شروع با startsWith(subject, 'Re:')- 1$select برای بهینهسازی: فقط فیلدهای مورد نیاز را دریافت کنید:
$select=id,subject,from,receivedDateTime,isRead,importanceاین کار سرعت را افزایش و مصرف bandwidth را کاهش میدهد.
- 1$orderBy برای مرتبسازی: ترتیب نتایج:
$orderBy=receivedDateTime desc → جدیدترین اول
$orderBy=from/emailAddress/name → بر اساس فرستنده
$orderBy=importance desc → مهمترین اول- 1ارسال HTML حرفهای با RTL:
<html dir="rtl">
<body style="font-family: 'Segoe UI', Tahoma, sans-serif; direction: rtl;">
<div style="max-width: 600px; margin: 0 auto; padding: 20px;">
<h1 style="color: #0078D4;">عنوان ایمیل</h1>
<p style="font-size: 14px; line-height: 1.8;">متن پیام</p>
<a href="https://example.com" style="background: #0078D4; color: white; padding: 10px 20px; text-decoration: none; border-radius: 4px;">دکمه</a>
</div>
</body>
</html>- 1Shared Mailbox: برای ارسال از Shared Mailbox:
POST /users/{shared-mailbox-email}/sendMail
یا
From: shared@company.com (با دسترسی Send As)- 1پوشههای پیشفرض Outlook:
inbox → صندوق ورودی
drafts → پیشنویسها
sentitems → ارسال شده
deleteditems → حذف شده
junkemail → هرزنامه (Spam)
archive → آرشیو
outbox → صندوق خروجی
clutter → ایمیلهای کماهمیت- 1Categories (دستهبندی رنگی): رنگهای پیشفرض Outlook:
Red Category → قرمز (مهم/فوری)
Orange Category → نارنجی
Yellow Category → زرد
Green Category → سبز (انجام شده)
Blue Category → آبی
Purple Category → بنفش- 1Importance Levels: سطوح اهمیت ایمیل:
Low → اهمیت پایین (فلش آبی رو به پایین)
Normal → عادی (پیشفرض)
High → اهمیت بالا (علامت تعجب قرمز)- 1Recurrence Pattern برای تقویم: الگوهای تکرار رویداد:
{
"pattern": {
"type": "weekly",
"interval": 1,
"daysOfWeek": ["saturday", "monday", "wednesday"]
},
"range": {
"type": "endDate",
"startDate": "2024-01-01",
"endDate": "2024-06-30"
}
}انواع type: daily, weekly, absoluteMonthly, relativeMonthly, absoluteYearly, relativeYearly
- 1جلسه آنلاین Teams: ایجاد خودکار لینک Teams:
{
"isOnlineMeeting": true,
"onlineMeetingProvider": "teamsForBusiness"
}لینک Teams در خروجی onlineMeeting.joinUrl قرار میگیرد.
- 1Batch Request برای عملیات انبوه: چند عملیات در یک درخواست:
POST https://graph.microsoft.com/v1.0/$batch
{
"requests": [
{"id": "1", "method": "GET", "url": "/me/messages?$top=5"},
{"id": "2", "method": "GET", "url": "/me/contacts?$top=5"}
]
}حداکثر 20 درخواست در هر Batch.
- 1Delta Query برای همگامسازی تدریجی: فقط تغییرات جدید:
1. GET /me/messages/delta → deltaLink دریافت کنید
2. GET {deltaLink} → فقط تغییرات جدید
3. تکرار مرحله 2- 1محدودیتهای ارسال ایمیل Microsoft 365:
Exchange Online:
- 10,000 گیرنده در روز
- 30 ایمیل در دقیقه
- حجم ایمیل: 150 مگابایت
- پیوست API: 3 مگابایت (معمولی) / 150 مگابایت (Upload Session)
- 500 گیرنده در یک ایمیل- 1$search vs $filter: تفاوت جستجو و فیلتر:
$search: جستجوی متنی آزاد (مثل Google)
- سریعتر برای جستجوی کلمه
- نمیتواند با $filter ترکیب شود
- مثال: $search="invoice payment"
$filter: فیلتر ساختاریافته
- دقیقتر
- قابل ترکیب با $orderBy
- مثال: $filter=isRead eq false and importance eq 'high'- 1Error Handling حرفهای: همیشه خطاها را مدیریت کنید:
Microsoft Outlook Node
→ On Error: Continue
→ IF (خطا رخ داده)
→ Telegram (اعلان خطا به ادمین)
→ MySQL (ثبت خطا در لاگ)رفع مشکلات
خطاهای رایج و راهحلها
1. خطای 401 - Unauthorized / InvalidAuthenticationToken
علت: توکن OAuth2 منقضی شده یا نامعتبر است
راهحل
- Credential را در n8n Disconnect و مجدداً Connect کنید
- بررسی کنید Client Secret منقضی نشده باشد (Azure Portal > Certificates & secrets)
- مطمئن شوید Client ID و Tenant ID صحیح هستند
- اگر Client Secret تمدید شده، مقدار جدید را در n8n وارد کنید
2. خطای 403 - Forbidden / Insufficient Privileges
علت: Permissionهای کافی در Azure AD ندارید
راهحل
- Azure Portal > App registrations > API permissions بروید
- Permissionهای لازم اضافه کنید:
Mail.ReadWriteبرای خواندن و نوشتن ایمیلMail.Sendبرای ارسال ایمیلCalendars.ReadWriteبرای تقویمContacts.ReadWriteبرای مخاطبین- Grant admin consent کلیک کنید
- Credential را Disconnect و دوباره Connect کنید
3. خطای 404 - Resource Not Found
علت: شناسه ایمیل، پوشه یا رویداد نامعتبر است
راهحل
- از خروجی listEmails یا listFolders شناسه معتبر بگیرید
- بررسی کنید ایمیل یا رویداد قبلاً حذف نشده باشد
- برای پوشههای پیشفرض از نامهای استاندارد استفاده کنید:
inbox,drafts,sentitems,deleteditems,junkemail,archive- توجه: شناسهها در Microsoft Graph معمولاً رشتههای طولانی Base64 هستند
4. خطای 429 - Too Many Requests (Throttling)
علت: تعداد درخواستها از حد مجاز Microsoft Graph بیشتر شده
راهحل
- محدودیتها:
- 10,000 درخواست در 10 دقیقه (هر اپلیکیشن)
- ارسال ایمیل: 10,000 در روز / 30 در دقیقه
- بین درخواستها Wait (حداقل 1 ثانیه) اضافه کنید
- از
$topاستفاده کنید تا تعداد نتایج محدود شود - از
$selectاستفاده کنید تا فقط فیلدهای لازم برگردد - Header
Retry-Afterرا بررسی کنید - از Batch Request برای چند عملیات همزمان استفاده کنید
5. خطای "Token refresh failed"
علت: Refresh Token منقضی شده
راهحل
- مطمئن شوید
offline_accessدر Scopeها وجود دارد - Credential را Disconnect و مجدداً Connect کنید
- اگر از Conditional Access استفاده میکنید، Policyها را بررسی کنید
- در Azure AD بررسی کنید Token lifetime policy تغییر نکرده باشد
6. مشکل ارسال ایمیل با پیوست بزرگ
علت: محدودیت حجم پیوست
راهحل
- حداکثر حجم پیوست معمولی: 3 مگابایت (API)
- برای فایلهای بزرگتر از 3 مگابایت: از Upload Session استفاده کنید
- حداکثر حجم کل ایمیل: 150 مگابایت (شامل encoding)
- فایلهای بزرگ را ابتدا در OneDrive آپلود و لینک ارسال کنید
- فایل را قبل از پیوست فشرده کنید
7. فیلتر OData کار نمیکند
علت: Syntax اشتباه در OData query
راهحل
- فرمت صحیح فیلترها:
isRead eq false(خوانده نشده)importance eq 'high'(مهم)receivedDateTime ge 2024-01-01T00:00:00Z(بعد از تاریخ)from/emailAddress/address eq 'user@example.com'(فرستنده خاص)hasAttachments eq true(دارای پیوست)subject eq 'test'(موضوع دقیق)contains(subject, 'invoice')(موضوع شامل)- از
$searchبرای جستجوی متنی استفاده کنید (سادهتر از$filter) $searchو$filterرا نمیتوان همزمان استفاده کرد
8. مشکل Timezone در رویدادهای تقویم
علت: عدم تطابق منطقه زمانی
راهحل
- همیشه
timeZoneرا صریحاً مشخص کنید - فرمت Timezone ویندوز:
Iran Standard Time - فرمت IANA:
Asia/Tehran - Microsoft Graph هر دو فرمت را پشتیبانی میکند
- برای رویدادهای تمامروز (All-Day) فقط
dateبفرستید (بدون time) - زمان شروع و پایان باید در یک Timezone باشند
9. خطای AADSTS (Azure AD Errors)
علت: مشکلات Azure Active Directory
راهحلها بر اساس کد
AADSTS700016: Application ID اشتباه - Client ID را بررسی کنیدAADSTS7000218: Client Secret اشتباه - مقدار Value (نه ID) را کپی کنیدAADSTS50011: Redirect URI اشتباه - URI دقیق n8n را وارد کنیدAADSTS65001: کاربر consent نداده - Admin Consent بدهیدAADSTS50076: MFA لازم است - Multi-Factor Authentication تکمیل کنید
