diff --git a/docs/en/Emailing.md b/docs/en/Emailing.md index 022f5c9e72..aa341a3898 100644 --- a/docs/en/Emailing.md +++ b/docs/en/Emailing.md @@ -60,6 +60,8 @@ namespace MyProject * **from**: You can set this as the first argument to set a sender email address. If not provided, the default sender address is used (see the email settings below). * **isBodyHtml**: Indicates whether the email body may contain HTML tags. **Default: true**. +> `IEmailSender` is the suggested way to send emails, since it makes your code provider independent. + #### MailMessage In addition to primitive parameters, you can pass a **standard `MailMessage` object** ([see](https://docs.microsoft.com/en-us/dotnet/api/system.net.mail.mailmessage)) to the `SendAsync` method to set more options, like adding attachments. @@ -68,7 +70,7 @@ In addition to primitive parameters, you can pass a **standard `MailMessage` obj Sending emails is implemented by the standard `SmtpClient` class ([see](https://docs.microsoft.com/en-us/dotnet/api/system.net.mail.smtpclient)) by default. The implementation class is the `SmtpEmailSender`. This class also expose the `ISmtpEmailSender` service (in addition to the `IEmailSender`). -Most of the time you want to directly use the `ISmtpEmailSender` to make your code provider independent. However, if you want to create an `SmtpClient` easily with the same email settings, you can inject the `ISmtpEmailSender` and use its `BuildClientAsync` method to obtain a `SmtpClient` object and send the email yourself. +Most of the time you want to directly use the `IEmailSender` to make your code provider independent. However, if you want to create an `SmtpClient` object with the same email settings, you can inject the `ISmtpEmailSender` and use its `BuildClientAsync` method to obtain a `SmtpClient` object and send the email yourself. ## Queueing Emails / Background Jobs @@ -87,7 +89,7 @@ Email sending uses the [setting system](Settings.md) to define settings and get * **Abp.Mailing.Smtp.Host**: The IP/Domain of the SMTP server (default: 127.0.0.1). * **Abp.Mailing.Smtp.Port**: The Port of the SMTP server (default: 25). * **Abp.Mailing.Smtp.UserName**: Username, if the SMTP server requires authentication. -* **Abp.Mailing.Smtp.Password**: Password, if the SMTP server requires authentication. +* **Abp.Mailing.Smtp.Password**: Password, if the SMTP server requires authentication. **This value is encrypted **(see the section below). * **Abp.Mailing.Smtp.Domain**: Domain for the username, if the SMTP server requires authentication. * **Abp.Mailing.Smtp.EnableSsl**: A value that indicates if the SMTP server uses SSL or not ("true" or "false". Default: "false"). * **Abp.Mailing.Smtp.UseDefaultCredentials**: If true, uses default credentials instead of the provided username and password ("true" or "false". Default: "true"). @@ -108,7 +110,17 @@ The easiest way to define these settings it to add them to the `appsettings.json } ```` -See the [setting system document](Settings.md) to understand the setting system better. +You can set/change these settings using the `ISettingManager` and store values in a database. See the [setting system document](Settings.md) to understand the setting system better. + +### Encrypt the SMTP Password + +*Abp.Mailing.Smtp.Password* must be an **encrypted** value. If you use the `ISettingManager` to set the password, you don't have to worry. It internally encrypts the values on set and decrypts on get. + +If you use the `appsettings.json` to store the password, you should manually inject the `ISettingEncryptionService` and use its `Encrypt` method to obtain an encrypted value. This can be done by creating a simple code in your application. Then you can delete the code. As better, you can create a UI in your application to configure the email settings. In this case, you can directly use the `ISettingManager` without worrying the encryption. + +### ISmtpEmailSenderConfiguration + +If you don't want to use the setting system to store the email sending configuration, you can replace the `ISmtpEmailSenderConfiguration` service with your own implementation to get the configuration from any other source. `ISmtpEmailSenderConfiguration` is implemented by the `SmtpEmailSenderConfiguration` by default, which gets the configuration from the setting system as explained above. ## Text Template Integration diff --git a/docs/en/MailKit.md b/docs/en/MailKit.md index e98a81454f..de4b653f4d 100644 --- a/docs/en/MailKit.md +++ b/docs/en/MailKit.md @@ -1,3 +1,48 @@ # MailKit Integration -TODO! \ No newline at end of file +[MailKit](http://www.mimekit.net/) is a cross-platform, popular open source mail client library for .net. ABP Framework provides an integration package to use the MailKit as the [email sender](Emailing.md). + +## Installation + +It is suggested to use the [ABP CLI](CLI.md) to install this package. Open a command line window in the folder of the project (.csproj file) and type the following command: + +````bash +abp add-package Volo.Abp.MailKit +```` + +If you haven't done it yet, you first need to install the ABP CLI. For other installation options, see [the package description page](https://abp.io/package-detail/Volo.Abp.MailKit). + +## Sending Emails + +### IEmailSender + +[Inject](Dependency-Injection.md) the standard `IEmailSender` into any service and use the `SendAsync` method to send emails. See the [email sending document](Emailing.md) for details. + +> `IEmailSender` is the suggested way to send emails even if you use MailKit, since it makes your code provider independent. + +### IMailKitSmtpEmailSender + +MailKit package also exposes the `IMailKitSmtpEmailSender` service that extends the `IEmailSender` by adding the `BuildClientAsync()` method. This method can be used to obtain a `MailKit.Net.Smtp.SmtpClient` object that can be used to perform MailKit specific operations. + +## Configuration + +MailKit integration package uses the same settings defined by the email sending system. So, refer to the [email sending document](Emailing.md) for the settings. + +In addition to the standard settings, this package defines `AbpMailKitOptions` as a simple [options](Options.md) class. This class defines only one options: + +* **SecureSocketOption**: Used to set one of the `SecureSocketOptions`. Default: `null` (uses the defaults). + +**Example: Use *SecureSocketOptions.SslOnConnect*** + +````csharp +Configure(options => +{ + options.SecureSocketOption = SecureSocketOptions.SslOnConnect; +}); +```` + +Refer to the [MailKit documentation](http://www.mimekit.net/) to learn more about this option. + +## See Also + +* [Email sending](Emailing.md) \ No newline at end of file