Skip to content

Mail target

Jump to bottom Edit New page
Rolf Kristensen edited this page Oct 16, 2023 · 60 revisions

Sends log messages by email using SMTP protocol.

Platforms Supported: Limited (Not available for NetStandard1.3+1.5 must use MailKit)

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

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"
          priority="Layout">
     <mailheader name="header-name" layout="header-value" /> <!-- repeatable -->
 </target>
</targets>

Read more about using the Configuration File.

Parameters

General Options

  • name - Name of the target.

Layout Options

  • header - Header for the message-body. Layout

  • footer - Footer for the message-body. Layout

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

  • 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}

  • priority - The mail message priority.

    • When using NLog without NLog.MailKit package, use System.Net.Mail.MailPriority.Low, Normal, High.
    • When using Nlog + NLog.MailKit versions up to v3.1, the valid values are MimeKit.MessagePriority.NonUrgent, Normal, Urgent
    • NLog.MailKit v3.2 and above accepts NonUrgent / Low , Normal , Urgent / High for backward compatibility

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 only works with SSL if NLog.MailKit is used. 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 using network credentials of user currently logged on (Same as SmtpClient.UseDefaultCredentials = true)

  • 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).

  • deliveryMethod - 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

  • mailheader - Specify one or more email-message-headers (Ex. Message-Id)

    Introduced with NLog v5.1.3 and NLog.MailKit v5.1

Remarks

.NET Standard 1.x / MailKit package

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:

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

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

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;

MailKit Target using Amazon AWS SMTP:

<target name="MailAWS" xsi:type="Mail"
            smtpServer="email-smtp.us-east-1.amazonaws.com"
            smtpPort="587"
            smtpAuthentication="Basic"
            smtpUserName="xxxxxxxx"
            smtpPassword="xxxxxxxxxx"
            secureSocketOption="StartTls"
            from="logger@xxxx.xxx" to="xxx@gmail.com" />

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>

Mail Target send LogEvent history on error

Example configuration that buffers LogEvents and sends entire batch on error LogEvent:

  <target xsi:type="AutoFlushWrapper" name="MailErrorFlush"
    condition="level >= LogLevel.Error"
    flushOnConditionOnly="true">
     <target xsi:type="BufferingWrapper" name="MailBuffer"
       bufferSize="50"
       overflowAction="Discard">
        <target xsi:type="Mail" name="MailTarget" />
     </target>
  </target>

Using Mail-Target with GMail

<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <targets>
    <target name="gmail" xsi:type="Mail"
            smtpServer="smtp.gmail.com"
            smtpPort="587"
            smtpAuthentication="Basic"
            smtpUserName="user@gmail.com"
            smtpPassword="password"
            enableSsl="true"
            from="emailaddress@gmail.com"
            to="recipient@example.com"
            cc="alice@example.com;bob@example.com;charlie@example.com"
          />
  </targets>

  <rules>
    <logger name="*" minlevel="Debug" writeTo="gmail" />
  </rules>
</nlog>

- Troubleshooting Guide - See available NLog Targets and Layouts: https://nlog-project.org/config

Home

Configuration

Programmatic Configuration

Advanced

Extending NLog

Clone this wiki locally