Mail در Laravel چیست؟ آموزش کامل ارسال ایمیل در لاراول

ارسال ایمیل یکی از قابلیت‌های مهم تقریباً هر نرم‌افزار وب است.

در یک پروژه واقعی ممکن است لازم باشد بعد از ثبت‌نام کاربر، ثبت سفارش، تغییر وضعیت سفارش، بازیابی رمز عبور، ارسال فاکتور یا انجام یک عملیات مهم، ایمیلی برای کاربر ارسال شود.

اگرچه در PHP خام می‌توان با روش‌های مختلف ایمیل ارسال کرد، Laravel یک سیستم کامل و ساختاریافته برای مدیریت ایمیل در اختیار توسعه‌دهنده قرار می‌دهد.

در Laravel می‌توان ایمیل‌ها را با استفاده از Mailableها ایجاد کرد، قالب HTML یا Markdown برای آن‌ها ساخت، فایل پیوست اضافه کرد و حتی ارسال ایمیل‌های سنگین را به Queue سپرد.

در این مقاله از مفاهیم پایه شروع می‌کنیم و مرحله‌به‌مرحله با Mail در Laravel آشنا می‌شویم.

---

# Mail در Laravel چیست؟

Mail در Laravel مجموعه امکاناتی است که برای ساخت و ارسال ایمیل در اختیار برنامه قرار دارد.

به جای اینکه در قسمت‌های مختلف برنامه کدهای مربوط به SMTP و ارسال ایمیل را تکرار کنیم، می‌توانیم یک ساختار مشخص برای ایمیل‌های برنامه ایجاد کنیم.

برای مثال ممکن است برنامه ما ایمیل‌هایی مانند موارد زیر داشته باشد:

• ایمیل خوش‌آمدگویی
• تأیید ثبت‌نام
• بازیابی رمز عبور
• تأیید سفارش
• فاکتور خرید
• تغییر وضعیت سفارش
• اطلاع‌رسانی پرداخت
• ارسال گزارش
• ارسال فایل

Laravel برای ساخت این ایمیل‌ها از مفهوم Mailable استفاده می‌کند.

---

# Mailable در Laravel چیست؟

Mailable یک کلاس Laravel است که ساختار و محتوای یک ایمیل را تعریف می‌کند.

برای ساخت یک Mailable می‌توان از Artisan استفاده کرد:

php artisan make:mail OrderCreated

بعد از اجرای این دستور، Laravel یک کلاس برای ایمیل ایجاد می‌کند.

ساختار آن به صورت کلی چیزی شبیه این خواهد بود:

<?php



namespace App\Mail;



use Illuminate\Bus\Queueable;

use Illuminate\Mail\Mailable;

use Illuminate\Mail\Mailables\Content;

use Illuminate\Mail\Mailables\Envelope;

use Illuminate\Queue\SerializesModels;



class OrderCreated extends Mailable

{

    use Queueable, SerializesModels;



    public function envelope(): Envelope

    {

        return new Envelope(

            subject: 'سفارش جدید',

        );

    }



    public function content(): Content

    {

        return new Content(

            view: 'emails.order-created',

        );

    }

}

البته ساختار دقیق کلاس Mailable می‌تواند بسته به نسخه Laravel و نوع پیاده‌سازی متفاوت باشد.

---

# تنظیم Mail در Laravel

قبل از ارسال ایمیل باید Mailer برنامه را تنظیم کنیم.

تنظیمات Mail معمولاً در فایل زیر قرار دارند:

config/mail.php

اما اطلاعات حساس مانند اطلاعات حساب SMTP معمولاً از فایل .env خوانده می‌شوند.

برای مثال:

MAIL_MAILER=smtp

MAIL_HOST=smtp.example.com

MAIL_PORT=587

MAIL_USERNAME=your_username

MAIL_PASSWORD=your_password

MAIL_ENCRYPTION=tls

MAIL_FROM_ADDRESS="noreply@example.com"

MAIL_FROM_NAME="${APP_NAME}"

مقادیر دقیق این تنظیمات به سرویس ایمیلی که استفاده می‌کنید بستگی دارد.

---

# SMTP چیست؟

SMTP مخفف:

Simple Mail Transfer Protocol

است.

این پروتکل برای ارسال ایمیل در اینترنت استفاده می‌شود.

در Laravel می‌توانیم برنامه را به یک SMTP Server متصل کنیم تا ایمیل‌های برنامه از طریق آن سرویس ارسال شوند.

به صورت ساده:

Laravel

   ↓

SMTP Server

   ↓

Internet

   ↓

Recipient

---

# تنظیم SMTP در Laravel

فرض کنیم سرویس ایمیل شما اطلاعات زیر را ارائه کرده است:

Host: smtp.example.com

Port: 587

Username: user@example.com

Password: ********

Encryption: TLS

می‌توانیم آن‌ها را در .env قرار دهیم:

MAIL_MAILER=smtp

MAIL_HOST=smtp.example.com

MAIL_PORT=587

MAIL_USERNAME=user@example.com

MAIL_PASSWORD=your-password

MAIL_ENCRYPTION=tls



MAIL_FROM_ADDRESS="user@example.com"

MAIL_FROM_NAME="${APP_NAME}"

بعد از تغییر تنظیمات محیطی، اگر Laravel هنوز تنظیمات Cache شده را استفاده می‌کند، می‌توان Cache تنظیمات را پاک کرد:

php artisan config:clear

در محیط Production نیز باید دقت کنید که تنظیمات Cache شده با مقادیر جدید هماهنگ باشند.

---

# MAIL_FROM چیست؟

در .env معمولاً با این تنظیمات روبه‌رو می‌شویم:

MAIL_FROM_ADDRESS="noreply@example.com"

MAIL_FROM_NAME="${APP_NAME}"

این موارد مشخص می‌کنند ایمیل‌های ارسال‌شده از طرف چه آدرس و نامی نمایش داده شوند.

مثلاً:

CMSNevis

noreply@cmsnevis.ir

البته اینکه چه آدرسی اجازه ارسال دارد، به سرویس ایمیل و تنظیمات دامنه نیز بستگی دارد.

---

# ساخت اولین Mailable

برای شروع:

php artisan make:mail WelcomeUser

سپس می‌توانیم ایمیل را در Controller یا Service ارسال کنیم.

یک نمونه ساده:

use App\Mail\WelcomeUser;

use Illuminate\Support\Facades\Mail;



Mail::to($user->email)

    ->send(new WelcomeUser());

در این مثال:

Mail::to(...)

گیرنده ایمیل را مشخص می‌کند.

و:

send(...)

Mailable را ارسال می‌کند.

---

# ارسال ایمیل به یک کاربر

فرض کنیم Model کاربر دارای فیلد email است.

می‌توانیم بنویسیم:

Mail::to($user->email)

    ->send(new WelcomeUser());

یا:

Mail::to($user)

    ->send(new WelcomeUser());

اگر Model مربوطه اطلاعات لازم برای ارسال را فراهم کند، Laravel می‌تواند از آن برای مشخص کردن گیرنده استفاده کند.

---

# ارسال ایمیل با یک View

یکی از روش‌های رایج این است که محتوای ایمیل را در یک Blade View قرار دهیم.

برای مثال:

resources/views/emails/welcome.blade.php

محتوای ساده:

<h1>سلام {{ $user->name }}</h1>



<p>

    به سایت ما خوش آمدید.

</p>

سپس Mailable را طوری تنظیم می‌کنیم که از این View استفاده کند.

---

# ارسال اطلاعات به View ایمیل

فرض کنیم می‌خواهیم نام کاربر را به ایمیل ارسال کنیم.

در Mailable:

public function __construct(

    public $user

) {

}

سپس در Content:

public function content(): Content

{

    return new Content(

        view: 'emails.welcome',

    );

}

حالا در View:

<h1>

    سلام {{ $user->name }}

</h1>

به این ترتیب داده‌های موردنیاز ایمیل در اختیار Template قرار می‌گیرند.

---

# ساخت یک ایمیل سفارش

فرض کنید در فروشگاه اینترنتی می‌خواهیم بعد از ثبت سفارش، ایمیلی برای مشتری ارسال کنیم.

Mailable:

php artisan make:mail OrderConfirmation

می‌توانیم Order را به آن ارسال کنیم:

public function __construct(

    public $order

) {

}

و در Blade:

<h1>سفارش شما ثبت شد</h1>



<p>

    شماره سفارش:

    {{ $order->order_number }}

</p>



<p>

    مبلغ سفارش:

    {{ number_format($order->total) }}

</p>

این روش برای سیستم‌های فروشگاهی بسیار کاربردی است.

---

# ارسال ایمیل HTML

ایمیل‌های حرفه‌ای معمولاً فقط متن ساده نیستند و از HTML استفاده می‌کنند.

برای مثال:

<h1>سفارش شما ثبت شد</h1>



<p>

    از خرید شما متشکریم.

</p>



<a href="{{ $url }}">

    مشاهده سفارش

</a>

البته طراحی ایمیل HTML با طراحی صفحات معمول وب تفاوت‌هایی دارد و باید سازگاری با Email Clientهای مختلف نیز در نظر گرفته شود.

---

# Markdown Mail در Laravel

Laravel امکان ساخت ایمیل با Markdown را نیز فراهم می‌کند.

برای ایجاد یک Mailable با Markdown می‌توان از:

php artisan make:mail OrderConfirmation --markdown=emails.orders.confirmation

استفاده کرد.

سپس یک Template Markdown در مسیر مربوطه ایجاد می‌شود.

مثلاً:

resources/views/emails/orders/confirmation.blade.php

یا ساختار مرتبط با Markdown Mail.

---

# نمونه Markdown Mail

یک نمونه ساده:

<x-mail::message>

# سفارش شما ثبت شد



سلام {{ $order->user->name }}



سفارش شما با موفقیت ثبت شده است.



<x-mail::button :url="$url">

مشاهده سفارش

</x-mail::button>



با تشکر،

{{ config('app.name') }}

</x-mail::message>

Laravel اجزای آماده‌ای برای ساخت ایمیل‌های Markdown در اختیار ما قرار می‌دهد.

این روش می‌تواند برای ایجاد ایمیل‌های استاندارد و قابل استفاده مجدد بسیار مناسب باشد.

---

# ارسال فایل پیوست در Laravel

گاهی لازم است همراه ایمیل یک فایل نیز ارسال شود.

مثلاً:

• فاکتور PDF
• گزارش
• فایل قرارداد
• فایل آموزشی
• رسید پرداخت

در Mailable می‌توان Attachment تعریف کرد.

برای مثال:

use Illuminate\Mail\Mailables\Attachment;



public function attachments(): array

{

    return [

        Attachment::fromPath(

            storage_path('app/invoices/invoice.pdf')

        ),

    ];

}

سپس هنگام ارسال ایمیل، فایل به آن پیوست می‌شود.

---

# پیوست فایل از Storage

اگر فایل داخل Storage قرار دارد، بهتر است ساختار پروژه را طوری طراحی کنیم که Mailable بتواند فایل را از محل مناسب دریافت کند.

مثلاً:

Attachment::fromStorage(

    'invoices/invoice.pdf'

)

یا با Disk مشخص:

Attachment::fromStorageDisk(

    'public',

    'invoices/invoice.pdf'

)

استفاده از Storage باعث می‌شود مدیریت فایل‌ها از منطق ایمیل جدا بماند.

---

# CC و BCC در Laravel Mail

گاهی لازم است علاوه بر گیرنده اصلی، یک نسخه از ایمیل برای افراد دیگری نیز ارسال شود.

مثلاً:

Mail::to($user->email)

    ->cc('support@example.com')

    ->send(new OrderConfirmation($order));

همچنین می‌توان از BCC استفاده کرد:

Mail::to($user->email)

    ->bcc('archive@example.com')

    ->send(new OrderConfirmation($order));

تفاوت اصلی این است که گیرندگان BCC برای سایر گیرندگان قابل مشاهده نیستند.

---

# ارسال ایمیل به چند گیرنده

می‌توان چند گیرنده را نیز مشخص کرد:

Mail::to([

    'user1@example.com',

    'user2@example.com',

])->send(new ReportMail());

البته در پروژه‌های واقعی بهتر است نحوه ارسال گروهی ایمیل را با توجه به تعداد گیرندگان و محدودیت سرویس ایمیل طراحی کنیم.

---

# ارسال ایمیل با Reply-To

گاهی لازم است ایمیل از یک آدرس ارسال شود اما پاسخ کاربر به آدرس دیگری برود.

در Mailable می‌توان Reply-To تعریف کرد.

مثلاً:

public function envelope(): Envelope

{

    return new Envelope(

        subject: 'پیام جدید',

        replyTo: [

            new Address(

                'support@example.com',

                'Support'

            ),

        ],

    );

}

این قابلیت برای سیستم‌های پشتیبانی و ارتباط با مشتری کاربرد زیادی دارد.

---

# ارسال ایمیل با Queue

یکی از نکات بسیار مهم در پروژه‌های واقعی، استفاده از Queue برای ارسال ایمیل است.

فرض کنید یک عملیات مهم در سایت انجام شده و برنامه باید ایمیلی برای کاربر ارسال کند.

اگر ارسال SMTP چند ثانیه طول بکشد و این عملیات مستقیماً داخل Request انجام شود، کاربر ممکن است مجبور شود منتظر بماند.

ساختار نامناسب:

User Request

    ↓

Business Logic

    ↓

Send Email

    ↓

SMTP

    ↓

Response

ساختار بهتر:

User Request

    ↓

Business Logic

    ↓

Queue Job

    ↓

Response سریع



Queue Worker

    ↓

Send Email

این موضوع برای سایت‌های پرترافیک اهمیت زیادی دارد.

---

# Queue کردن Mailable

برای Queue کردن یک Mailable می‌توان آن را به شکل مناسب با Queue استفاده کرد.

یکی از روش‌های رایج این است که Mailable از قابلیت Queue استفاده کند.

برای مثال:

use Illuminate\Contracts\Queue\ShouldQueue;



class OrderConfirmation extends Mailable implements ShouldQueue

{

    //

}

سپس هنگام ارسال:

Mail::to($user->email)

    ->queue(new OrderConfirmation($order));

در این حالت ارسال ایمیل به Queue سپرده می‌شود.

البته برای استفاده واقعی از Queue باید Queue Worker پروژه نیز فعال باشد.

---

# تفاوت send و queue

به صورت ساده:

Mail::to($email)

    ->send($mail);

یعنی ارسال ایمیل در همان فرآیند.

اما:

Mail::to($email)

    ->queue($mail);

یعنی درخواست ارسال ایمیل به Queue سپرده می‌شود.

برای عملیات‌هایی که احتمالاً زمان‌بر هستند، Queue معمولاً انتخاب مناسب‌تری است.

---

# تست ایمیل در محیط Development

هنگام توسعه پروژه بهتر است ایمیل واقعی برای کاربران ارسال نکنیم.

می‌توان محیط Development را به شکلی تنظیم کرد که ایمیل‌ها فقط برای تست دریافت شوند.

یکی از روش‌ها استفاده از سرویس‌های مخصوص تست ایمیل است.

این کار کمک می‌کند:

• ایمیل‌های واقعی اشتباهی ارسال نشوند.
• Templateها را بررسی کنیم.
• Headerها را تست کنیم.
• Attachmentها را بررسی کنیم.
• قبل از Production خطاها را پیدا کنیم.

---

# ایمیل در Production

در محیط Production باید از یک سرویس ایمیل مناسب استفاده شود.

بسته به نیاز پروژه ممکن است از:

• SMTP Provider
• سرویس ایمیل تراکنشی
• Mail Server اختصاصی
• سرویس‌های Cloud Email

استفاده شود.

برای پروژه‌های واقعی بهتر است علاوه بر تنظیم SMTP، مواردی مانند اعتبارسنجی دامنه، SPF، DKIM و DMARC نیز در نظر گرفته شوند.

این موارد مستقیماً به اعتبار ارسال ایمیل و احتمال قرار گرفتن پیام در Spam مربوط هستند.

---

# مشکل ارسال نشدن ایمیل در Laravel

اگر ایمیل ارسال نمی‌شود، موارد زیر را بررسی کنید.

۱. تنظیمات .env

مقادیر زیر را بررسی کنید:

MAIL_MAILER=

MAIL_HOST=

MAIL_PORT=

MAIL_USERNAME=

MAIL_PASSWORD=

MAIL_ENCRYPTION=

MAIL_FROM_ADDRESS=

۲. Cache تنظیمات

بعد از تغییر .env:

php artisan config:clear

و در صورت نیاز:

php artisan cache:clear

۳. SMTP Server

بررسی کنید Host و Port درست باشند.

۴. Username و Password

اطلاعات احراز هویت SMTP را بررسی کنید.

۵. Queue Worker

اگر از Queue استفاده می‌کنید، Worker باید فعال باشد.

۶. Log Laravel

در صورت بروز Exception، Logهای Laravel را بررسی کنید.

---

# Mail و Notification چه تفاوتی دارند؟

Mail بیشتر روی ساخت و ارسال ایمیل تمرکز دارد.

اما Notification یک لایه بالاتر برای اطلاع‌رسانی است.

برای مثال یک Notification می‌تواند از کانال‌های مختلف استفاده کند:

Notification

    ├── Mail

    ├── Database

    ├── Broadcast

    └── سایر کانال‌ها

بنابراین اگر هدف شما ساخت یک سیستم اطلاع‌رسانی چندکاناله است، Notification می‌تواند انتخاب مناسب‌تری باشد.

مقاله بعدی این کلاستر دقیقاً به Notification در Laravel اختصاص دارد.

---

# ساختار پیشنهادی ایمیل‌ها در یک پروژه Laravel

در یک پروژه واقعی بهتر است ایمیل‌ها ساختار مشخصی داشته باشند.

مثلاً:

app/

└── Mail/

    ├── WelcomeUser.php

    ├── OrderConfirmation.php

    ├── InvoiceMail.php

    └── PasswordChanged.php



resources/

└── views/

    └── emails/

        ├── welcome.blade.php

        ├── orders/

        │   └── confirmation.blade.php

        └── invoices/

            └── invoice.blade.php

این ساختار با افزایش تعداد ایمیل‌ها، مدیریت پروژه را ساده‌تر می‌کند.

---

# نمونه کامل ارسال ایمیل ثبت سفارش

فرض کنیم کاربر سفارشی ثبت کرده است.

ابتدا Mailable:

php artisan make:mail OrderConfirmation

سپس:

<?php



namespace App\Mail;



use App\Models\Order;

use Illuminate\Bus\Queueable;

use Illuminate\Mail\Mailable;

use Illuminate\Queue\SerializesModels;



class OrderConfirmation extends Mailable

{

    use Queueable, SerializesModels;



    public function __construct(

        public Order $order

    ) {

    }



    public function build()

    {

        return $this

            ->subject('تأیید سفارش')

            ->view('emails.orders.confirmation');

    }

}

سپس View:

<h1>سفارش شما ثبت شد</h1>



<p>

    شماره سفارش:

    {{ $order->order_number }}

</p>



<p>

    مبلغ:

    {{ number_format($order->total) }}

</p>

و در نهایت ارسال:

use App\Mail\OrderConfirmation;

use Illuminate\Support\Facades\Mail;



Mail::to($order->user->email)

    ->send(new OrderConfirmation($order));

به این ترتیب یک جریان ساده ارسال ایمیل برای سفارش ایجاد کرده‌ایم.

---

# بهترین روش برای مدیریت ایمیل در پروژه‌های بزرگ

اگر پروژه کوچک باشد، ممکن است ارسال مستقیم ایمیل از Service یا Controller کافی باشد.

اما در پروژه‌های بزرگ‌تر بهتر است معماری مشخصی داشته باشیم:

Business Logic

      ↓

Event / Service

      ↓

Notification / Mailable

      ↓

Queue

      ↓

Mail Provider

این معماری باعث می‌شود ارسال ایمیل از منطق اصلی برنامه جدا شود.

برای مثال ثبت سفارش نباید صرفاً به این دلیل که SMTP برای چند ثانیه پاسخ نمی‌دهد، با شکست مواجه شود.

در چنین سناریوهایی Queue می‌تواند عملیات ارسال را مستقل کند.

---

# نکات مهم برای ایمیل‌های حرفه‌ای Laravel

برای ساخت سیستم ایمیل حرفه‌ای این موارد را در نظر بگیرید:

---

# جمع‌بندی

Mail در Laravel یک سیستم ساختاریافته برای ایجاد و ارسال ایمیل در پروژه‌های Laravel است.

مهم‌ترین مفاهیمی که در این مقاله یاد گرفتیم عبارت‌اند از:

Mail

Mailable

SMTP

Mail Configuration

Blade Email

Markdown Mail

Attachment

CC

BCC

Reply-To

Queue

Mail Provider

برای ارسال یک ایمیل ساده، ابتدا یک Mailable ایجاد می‌کنیم:

php artisan make:mail WelcomeUser

سپس محتوای آن را مشخص کرده و در نهایت:

Mail::to($user->email)

    ->send(new WelcomeUser());

آن را ارسال می‌کنیم.

در پروژه‌های حرفه‌ای‌تر بهتر است ایمیل‌های زمان‌بر را به Queue بسپاریم و برای فایل‌های پیوست نیز از Storage استفاده کنیم.

همچنین باید توجه داشته باشیم که Mail و Notification یک مفهوم یکسان نیستند. Mail بیشتر روی ارسال ایمیل تمرکز دارد، در حالی که Notification امکان طراحی سیستم اطلاع‌رسانی چندکاناله را فراهم می‌کند.

---

# سوالات متداول

Mail در Laravel چیست؟

Mail سیستم Laravel برای ایجاد و ارسال ایمیل از طریق Mailerها و سرویس‌هایی مانند SMTP است.

Mailable چیست؟

Mailable یک کلاس Laravel برای تعریف ساختار، عنوان، محتوا و سایر مشخصات یک ایمیل است.

چگونه در Laravel ایمیل ارسال کنیم؟

ابتدا یک Mailable بسازید:

php artisan make:mail WelcomeUser

سپس:

Mail::to($email)

    ->send(new WelcomeUser());

SMTP در Laravel چگونه تنظیم می‌شود؟

اطلاعات SMTP معمولاً در فایل .env قرار می‌گیرند:

MAIL_MAILER=smtp

MAIL_HOST=smtp.example.com

MAIL_PORT=587

MAIL_USERNAME=your_username

MAIL_PASSWORD=your_password

MAIL_ENCRYPTION=tls

چگونه فایل را همراه ایمیل ارسال کنیم؟

می‌توان در Mailable از Attachment استفاده کرد:

public function attachments(): array

{

    return [

        Attachment::fromPath(

            storage_path('app/invoice.pdf')

        ),

    ];

}

send و queue در Mail چه تفاوتی دارند؟

send() ایمیل را در همان فرآیند ارسال می‌کند، در حالی که queue() ارسال آن را به سیستم Queue می‌سپارد.

آیا برای ارسال ایمیل در Laravel به SMTP نیاز داریم؟

Laravel باید از یک Mail Transport یا سرویس ارسال ایمیل استفاده کند. SMTP یکی از رایج‌ترین روش‌هاست، اما بسته به تنظیمات پروژه روش‌های دیگری نیز می‌توانند استفاده شوند.

چرا ایمیل Laravel ارسال نمی‌شود؟

تنظیمات .env، اطلاعات SMTP، Mailer، دسترسی شبکه، Logهای Laravel و در صورت استفاده از Queue، وضعیت Queue Worker را بررسی کنید.