This module provides functions client side of the SMTP protocol.

A basic usage example:

{-# LANGUAGE OverloadedStrings #-}
import Network.HaskellNet.SMTP
import Network.HaskellNet.Auth
import Network.Mail.Mime
import System.Exit (die)

main :: IO ()
main = doSMTP "your.smtp.server.com" $ \conn -> do -- (1)
   authSucceed <- authenticate PLAIN "username" "password" conn -- (2)
   if authSucceed
   then do
     let mail = simpleMail'
           "receiver@server.com"
           "sender@server.com"
           "subject"
           "Hello! This is the mail body!"
     sendMail mail conn -- (3)
   else die "Authentication failed."

Notes for the above example:

• (1) The connection (conn::SMTPConnection) is opened using the doSMTP function. We can use this connection to communicate with SMTP server.
• (2) The authenticate function authenticates to the server with the specified AuthType. It returns a Bool indicating either the authentication succeed or not.
• (3) The sendMail is used to send a email a plain text email.

N.B. For SSL/TLS support you may establish the connection using the functions (such as connectSMTPSSL) provided by the Network.HaskellNet.SMTP.SSL module of the HaskellNet-SSL package.

The common workflow while working with the library is:

1. Establish a new connection
2. Authenticate to the server
3. Perform message sending
4. Close connections

Steps 1 and 4 are combined together using bracket-like API. Other than that the documentation sections are structured according to this workflow.

The library encourages creation of SMTPConnection using the doSMTP-family functions. These functions provide bracket-like pattern that manages connection state: creates a connection, passes it to the user defined IO action and frees connection when the action exits. This approach is simple and exception safe.

N.B. It should be noted that none of these functions implements keep alive of any kind, so the server is free to close the connection by timeout even the end of before the users action exits.

NOTE: For SSL/TLS support you may establish the connection using the functions (such as connectSMTPSSL) provided by the Network.HaskellNet.SMTP.SSL module of the HaskellNet-SSL package.

bracket- style is not the only possible style for resource management, it's possible to use resourcet or resource-pool as well. In both of the approaches you need to use low-level 'connectSTM*' and closeSMTP functions.

Basic example using resourcet.

{-# LANGUAGE OverloadedStrings #-}
import Network.HaskellNet.SMTP
import Network.HaskellNet.Auth
import Control.Monad.Trans.Resource
import System.Exit (die)

main :: IO ()
main = runResourceT $ do
   (key, conn)
       <- allocate
              (connectSMTP "your.smtp.server.com")
              (closeSMTP)
   ... conn

This approach allows resource management even if the code does not form a stack, so is more general.

NOTE. SMTP protocol advices to use QUIT command for graceful connection close. Before version 0.6 the library never sent it, so does closeSMTP call.

Starting from 0.6 doSMTP-family uses graceful exit and sends QUIT before terminating a connection. This way of termination is exposed as gracefullyCloseSTMP function, however it's not a default method because it requires a connection to be in a valid state. So it's not possible to guarantee backwards compatibility.

Since version 0.6 there is only one function sendMail that sends a email rendered using mime-mail package. Historically there is a family of send*Mail functions that provide simpler interface but they basically mimic the functions from the mime-mail package, and it's encouraged to use those functions directly.