Network.HaskellNet.SMTP.Internal

Internal functions that are used in the SMTP protocol, you may need these module in case if you want to implement additional functionality that does not exist in the Network.HaskellNet.SMTP.

Example.

One example could be sending multiple emails over the same stream in order to use that you may want to use RSET command, so you can implement:

import Network.HaskellNet.SMTP.Internal

resetConnection :: SMTPConnection -> IO ()
resetConnection conn = do
   (code, _) <- sendCommand conn RSET
   unless (code == 250) $ throwIO $ UnexpectedReply RSET [250] code ""

Documentation

data SMTPConnection

All communication with server is done using SMTPConnection value.

Constructors

SMTPC

Fields

• bsstream :: !BSStream

  Connection communication channel.

• _response :: ![ByteString]

  Server properties as per reply to the EHLO request.

data Command

SMTP commands.

Supports basic and extended SMTP protocol without TLS support.

For each command we provide list of the expected reply codes that happens in success and failure cases respectively.

Constructors

HELO Text

The HELO command initiates the SMTP session conversation. The client greets the server and introduces itself. As a rule, HELO is attributed with an argument that specifies the domain name or IP address of the SMTP client.

Success: 250 Failure: 504, 550

EHLO Text

EHLO is an alternative to HELO for servers that support the SMTP service extensions (ESMTP)

Success: 250 Failure: 502, 504, 550

MAIL Text

MAIL FROM command initiates a mail transfer. As an argument, MAIL FROM includes a sender mailbox (reverse-path) can accept optional parameters.

Success: 250

Failure: 451, 452, 455, 503, 550, 552, 553, 555

RCPT Text

The RCPT TO command specifies exactly one recipient.

Success: 250 251

Failure: 450 451 452 455 503 550 551 552 553 555

DATA ByteString

With the DATA command, the client asks the server for permission to transfer the mail data.

Success: 250, 354

Failure: 450 451 452 503 550 552 554

Client just sends data and after receiving 354 starts streaming email, terminating transfer by sending rn.rn.

EXPN Text

EXPN is used to verify whether a mailing list in the argument exists on the local host. The positive response will specify the membership of the recipients.

Success: 250 252

Failure: 502 504 550

VRFY Text

VRFY is used to verify whether a mailbox in the argument exists on the local host. The server response includes the user’s mailbox and may include the user’s full name.

Success: 250 251 252

Failure: 502 504 550 551 553

HELP Text

With the HELP command, the client requests a list of commands the server supports, may request help for specific command

Success: 211 214

Failure: 502 504

AUTH AuthType UserName Password

Authorization support

NOOP

NOOP can be used to verify if the connection is alive

Success: 250

RSET

RSET Resets the state

Success: 250

QUIT

QUIT asks server to close connection. Client should terminate the connection when receives status.

Success: 221

Instances

Eq Command

Defined in Network.HaskellNet.SMTP.Internal

Methods

(==) :: Command -> Command -> Bool

(/=) :: Command -> Command -> Bool

Show Command

Defined in Network.HaskellNet.SMTP.Internal

Methods

showsPrec :: Int -> Command -> ShowS

show :: Command -> String

showList :: [Command] -> ShowS

data SMTPException

Exceptions that can happen during communication.

Constructors

UnexpectedReply Command [ReplyCode] ReplyCode ByteString

Reply code was not in the list of expected.

• Command - command that was sent.
• [ReplyCode] -- list of expected codes
• ReplyCode -- the code that we have received
• ByteString -- additional data returned by the server.

NotConfirmed ReplyCode ByteString

The server didn't accept the start of the message delivery

AuthNegotiationFailed ReplyCode ByteString

The server does not support current authentication method

NoRecipients Mail

Can't send email because no recipients were specified.

UnexpectedGreeting ReplyCode

Received an unexpected greeting from the server.

Instances

Show SMTPException

Defined in Network.HaskellNet.SMTP.Internal

Methods

showsPrec :: Int -> SMTPException -> ShowS

show :: SMTPException -> String

showList :: [SMTPException] -> ShowS

Exception SMTPException

Defined in Network.HaskellNet.SMTP.Internal

Methods

toException :: SMTPException -> SomeException

fromException :: SomeException -> Maybe SMTPException

displayException :: SMTPException -> String

type ReplyCode = Int

Code reply from the server. It's always 3 digit integer.

tryCommand

Arguments

:: SMTPConnection

Connection

-> Command

Supported command

-> Int

Number of allowed retries

-> [ReplyCode]

List of accepted codes

-> IO ByteString

Resulting data

Safe wrapper for running a client command over the SMTP connection.

Note on current behavior

We allow the command to fail several times, retry happens in case if we have received unexpected status code. In this case message will be sent again. However in case of other synchronous or asynchronous exceptions there will be no retries.

It case if number of retries were exceeded connection will be closed automatically.

The behaviors in notes will likely be changed in the future and should not be relied upon, see issues 76, 77.

parseResponse :: BSStream -> IO (ReplyCode, ByteString)

Read response from the stream. Response consists of the code and one or more lines of data.

In case if it's not the last line of reply the code is followed by the - sign. We return the code and all the data with the code stripped.

Eg.:

"250-8BITMIME\r"
"250-PIPELINING\r"
"250-SIZE 42991616\r"
"250-AUTH LOGIN PLAIN XOAUTH2\r"
"250-DSN\r"
"250 ENHANCEDSTATUSCODES\r"

Returns:

(250, "8BITMIME\nPIPELININGnSIZE 42991616\nAUTH LOGIN PLAIN XOAUTH2\nDSN\nENHANCEDSTATUSCODES")

Throws SMTPException.

sendCommand :: SMTPConnection -> Command -> IO (ReplyCode, ByteString)

Sends a Command to the server. Function that performs all the logic for sending messages. Throws an exception if something goes wrong.

Throws SMTPException.

sendMailData

Arguments

:: Address

sender mail

-> [Address]

receivers

-> ByteString

data

-> SMTPConnection

-> IO ()

Sends a mail to the server.

Throws SMTPException.

closeSMTP :: SMTPConnection -> IO ()

Terminates the connection. Quit command is not send in this case. It's safe to issue this command at any time if the connection is still open.

gracefullyCloseSMTP :: SMTPConnection -> IO ()

Gracefully closes SMTP connection. Connection should be in available state. First it sends quit command and then closes connection itself. Connection should not be used after this command exits (even if it exits with an exception). This command may throw an exception in case of network failure or protocol failure when sending QUIT command. If it happens connection nevertheless is closed.

Since: 0.6

quitSMTP :: SMTPConnection -> IO ()

Sends quit to the server. Connection must be terminated afterwards, i.e. it's not allowed to issue any command on this connection.

Reexports

data Address

Constructors

Address

Fields

• addressName :: Maybe Text
• addressEmail :: Text

Instances

Eq Address

Defined in Network.Mail.Mime

Methods

(==) :: Address -> Address -> Bool

(/=) :: Address -> Address -> Bool

Show Address

Defined in Network.Mail.Mime

Methods

showsPrec :: Int -> Address -> ShowS

show :: Address -> String

showList :: [Address] -> ShowS

IsString Address

Defined in Network.Mail.Mime

Methods

fromString :: String -> Address