Mail target

Rolf Kristensen edited this page Jan 14, 2018 · 32 revisions
Clone this wiki locally

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, NetStandard2.X and Mono

.NET Core

The SmtpClient is not part of NetStandard1.X, instead one should install the package NLog.MailKit:

  • Install-Package NLog.MailKit

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>