Mail target

Julian Verdurmen edited this page Aug 28, 2018 · 35 revisions

Sends log messages by email using SMTP protocol.

Combines well with FallbackGroup Target in order to create a fallback with multiple SMTP Hosts, example see here.

Supported in .NET, .NET Standard 2.x and Mono

MailKit

The SmtpClient is not part of .NET Standard 1.x. Also notice that the original SmtpClient of .NET is obsolete in favor of MailKit:

image

The NLog.MailKit is the Mail target implementation which uses MailKit. Including the NLog.MailKit package will replace the original mail target and has the same options as the original mail target

  • Install-Package NLog.MailKit

or use

<PackageReference Include="NLog.MailKit" Version="3.0.0" />

And add to your nlog.config:

<extensions>
    <add assembly="NLog.MailKit"/>
</extensions>

Bug/feature requests for NLog.MailKit please on the NLog.MailKit repo

Configuration Syntax

<targets>
  <target xsi:type="Mail"
          name="String"
          header="Layout"
          footer="Layout"
          layout="Layout"
          html="Boolean"
          addNewLines="Boolean"
          replaceNewlineWithBrTagInHtml="Boolean"
          encoding="Encoding"
          subject="Layout"
          to="Layout"
          bcc="Layout"
          cc="Layout"
          from="Layout"
          body="Layout"
          smtpUserName="Layout"
          enableSsl="Boolean"
          secureSocketOption="None|Auto|SslOnConnect|StartTls|StartTlsWhenAvailable"*
          smtpPassword="Layout"
          smtpAuthentication="Enum"
          smtpServer="Layout"
          smtpPort="Integer"
          useSystemNetMailSettings="Boolean"
          deliveryMethod="Enum"
          pickupDirectoryLocation="String"
          timeout="Integer"
          skipCertificateValidation="Boolean"
 />
</targets>

Read more about using the Configuration File.

Parameters

General Options

  • name - Name of the target.

Layout Options

  • header - Header. Layout

  • footer - Footer. Layout

  • layout - Text to be rendered. Layout Required. Default: ${message}${newline}. Same as body property

  • html - Indicates whether to send message as HTML instead of plain text. Boolean Default: false

  • addNewLines - Indicates whether to add new lines between log entries. Boolean

  • replaceNewlineWithBrTagInHtml - Indicates whether NewLine characters in the body should be replaced with <br/> tags. Boolean Default: false

  • encoding - Encoding to be used for sending e-mail. Encoding Default: UTF-8

Message Options

  • subject - Mail subject. Layout Required. Default: Message from NLog on ${machinename}

  • to - Recipients' email addresses separated by semicolons (e.g. john@domain.com;jane@domain.com). Layout. Starting in NLog 4.0 this field is no longer required, but To, BCC or CC should be defined otherwise an exception is thrown.

  • bcc - BCC email addresses separated by semicolons (e.g. john@domain.com;jane@domain.com). Layout

  • cc - CC email addresses separated by semicolons (e.g. john@domain.com;jane@domain.com). Layout

  • from - Sender's email address (e.g. joe@domain.com). Layout Required.

  • body - Same as Layout property. Mail message body (repeated for each log message send in one mail). Layout Default: ${message}${newline}

SMTP Options

  • smtpUserName - Username used to connect to SMTP server (used when SmtpAuthentication is set to "basic"). Layout

  • enableSsl - Indicates whether SSL (secure sockets layer) should be used when communicating with SMTP server. Boolean Default: False. Note: port 465 isn't working with SSL. See issue 1226

  • secureSocketOption - Only in NLog.Mailkit 2.1+. Provides a way of specifying the SSL and/or TLS encryption. Default StartTlsWhenAvailable. Options: None, Auto, SslOnConnect, StartTls & StartTlsWhenAvailable. If enableSsl is set to true, SslOnConnect will be used

  • smtpPassword - Password used to authenticate against SMTP server (used when SmtpAuthentication is set to "basic"). Layout

  • smtpAuthentication - SMTP Authentication mode. Default: None
    Possible values:

    • Basic - Basic - username and password.
    • None - No authentication.
    • Ntlm - NTLM Authentication.
  • smtpServer - SMTP Server to be used for sending. Layout Required.

  • smtpPort - Port number that SMTP Server is listening on. Integer Default: 25. Note: port 465 isn't working with SSL. See issue 1226

  • useSystemNetMailSettings - Force using smtp configuration from system.net/mailSettings. Boolean Default: False

  • timeout - Indicates the SMTP client timeout in milliseconds. Integer Default: 10000 (10 seconds)

  • pickupDirectoryLocation - Gets or sets the folder where applications save mail messages to be processed by the local SMTP server (introduced in NLog 4.2).

  • smtpDeliveryMethod - Specifies how outgoing email messages will be handled (introduced in NLog 4.2). Default: Network Possible values:

    • Network - Email is sent through the network to an SMTP server.
    • PickupDirectoryFromIis - Email is copied to the pickup directory used by a local Internet Information Services (IIS) for delivery.
    • SpecifiedPickupDirectory - Email is copied to the directory specified by the PickupDirectoryLocation property for delivery by an external application.
  • skipCertificateValidation - Only for NLog.MailKit. Introduced in NLog.MailKit 1.1 - skip SSL certification check

Remarks

Application Configuration File

If the application config file contains mail settings, fx.:

<system.net>
  <mailSettings>
    <smtp from="mail@domain.com" deliveryMethod="SpecifiedPickupDirectory">
      <network host="localhost" port="25"/>
      <specifiedPickupDirectory pickupDirectoryLocation="C:/Temp/Email"/>
    </smtp>
  </mailSettings>
</system.net>

These values will be used, if target doesn't override them (see useSystemNetMailSettings attribute).

  • NetStandard2.X does not support mail settings in the application config file.

Email Address Format

It is possible to use an address in format "John Doe <john.doe@example.com>" but the special characters < and > must be escaped. The result would be John Doe &lt;john.doe@example.com&gt;

Mail Target wrapped by FallbackGroup Target

Example configuration for a Mailserver Fallback with multiple hosts.

<target xsi:type="FallbackGroup" 
        name="mail"
        returnToFirstOnSuccess="true">
    <target xsi:type="Mail"
            name="mailserver1"
            subject="Layout"
            to="Layout"
            from="Layout"
            smtpServer="mx1.example.com" 
            smtpPort="Integer"
            layout="Layout" />
    <target xsi:type="Mail"
            name="mailserver2" 
            subject="Layout"
            to="Layout"
            from="Layout"
            smtpServer="mx2.example.com" 
            smtpPort="Integer"
            layout="Layout" />
</target>
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.