Note: In order to use this module, run nimble install smtp.

This module implements the SMTP client protocol as specified by RFC 5321, this can be used to send mail to any SMTP Server.

This module also implements the protocol used to format messages, as specified by RFC 2822.

Example gmail use:

  1. var msg = createMessage("Hello from Nim's SMTP",
  2.                         "Hello!.\n Is this awesome or what?",
  3.                         @["[email protected]"])
  4. let smtpConn = newSmtp(useSsl = true, debug=true)
  5. smtpConn.connect("smtp.gmail.com", Port 465)
  6. smtpConn.auth("username", "password")
  7. smtpConn.sendmail("[email protected]", @["[email protected]"], $msg)

Example for startTls use:

  1. var msg = createMessage("Hello from Nim's SMTP",
  2.                         "Hello!.\n Is this awesome or what?",
  3.                         @["[email protected]"])
  4. let smtpConn = newSmtp(debug=true)
  5. smtpConn.connect("smtp.mailtrap.io", Port 2525)
  6. smtpConn.startTls()
  7. smtpConn.auth("username", "password")
  8. smtpConn.sendmail("[email protected]", @["[email protected]"], $msg)

For SSL support this module relies on OpenSSL. If you want to enable SSL, compile with -d:ssl.

Types

  1. AsyncSmtp = SmtpBase[AsyncSocket]
  1. Message = object
  1. ReplyError = object of IOError
  1. Smtp = SmtpBase[Socket]

Procs

  1. proc `$`(msg: Message): string {....raises: [], tags: [], forbids: [].}

stringify for Message.

  1. proc auth(smtp: AsyncSmtp; username, password: string): owned(Future[void]) {.
  2.     ...stackTrace: false, raises: [Exception], tags: [RootEffect], forbids: [].}

Sends an AUTH command to the server to login as the username using password. May fail with ReplyError.

  1. proc auth(smtp: Smtp; username, password: string) {.
  2.     ...raises: [SslError, OSError, TimeoutError, ReplyError],
  3.     tags: [WriteIOEffect, ReadIOEffect, TimeEffect], forbids: [].}
  1. proc checkReply(smtp: AsyncSmtp; reply: string): owned(Future[void]) {.
  2.     ...stackTrace: false, raises: [Exception], tags: [RootEffect], forbids: [].}

Calls debugRecv and checks that the received data starts with reply. If the received data does not start with reply, then a QUIT command will be sent to the SMTP server and a ReplyError exception will be raised.

This is a lower level proc and not something that you typically would need to call when using this module. One exception to this is if you are implementing any SMTP extensions.

  1. proc checkReply(smtp: Smtp; reply: string) {.
  2.     ...raises: [TimeoutError, OSError, SslError, ReplyError],
  3.     tags: [ReadIOEffect, TimeEffect, WriteIOEffect], forbids: [].}
  1. proc close(smtp: AsyncSmtp): owned(Future[void]) {....stackTrace: false,
  2.     raises: [Exception], tags: [RootEffect], forbids: [].}

Disconnects from the SMTP server and closes the socket.

  1. proc close(smtp: Smtp) {....raises: [SslError, OSError, LibraryError, Exception],
  2.                          tags: [WriteIOEffect, RootEffect], forbids: [].}
  1. proc connect(smtp: AsyncSmtp; address: string; port: Port; helo: bool = true): owned(
  2.     Future[void]) {....stackTrace: false, raises: [Exception], tags: [RootEffect],
  3.                     forbids: [].}

Establishes a connection with a SMTP server. May fail with ReplyError or with a socket error.

  1. proc connect(smtp: Smtp; address: string; port: Port; helo: bool = true) {.
  2.     ...raises: [OSError, IOError, SslError, TimeoutError, ReplyError],
  3.     tags: [ReadIOEffect, WriteIOEffect, TimeEffect], forbids: [].}
  1. proc createMessage(mSubject, mBody: string; mTo, mCc: seq[string] = @[]): Message {.
  2.     ...raises: [], tags: [], forbids: [].}

Alternate version of the above.

You need to make sure that mSubject, mTo and mCc don’t contain any newline characters. Failing to do so will raise AssertionDefect.

  1. proc createMessage(mSubject, mBody: string; mTo, mCc: seq[string];
  2.                    otherHeaders: openArray[tuple[name, value: string]]): Message {.
  3.     ...raises: [], tags: [], forbids: [].}

Creates a new MIME compliant message.

You need to make sure that mSubject, mTo and mCc don’t contain any newline characters. Failing to do so will raise AssertionDefect.

  1. proc debugRecv(smtp: AsyncSmtp): Future[string] {....stackTrace: false,
  2.     raises: [Exception, ValueError], tags: [RootEffect], forbids: [].}

Receives a line of data from the socket connected to the SMTP server.

If the smtp object was created with debug enabled, debugRecv will invoke echo(“S:” & result.string) after the data is received.

This is a lower level proc and not something that you typically would need to call when using this module. One exception to this is if you are implementing any SMTP extensions.

See checkReply(reply).

  1. proc debugRecv(smtp: Smtp): string {....raises: [TimeoutError, OSError, SslError],
  2.                                      tags: [ReadIOEffect, TimeEffect],
  3.                                      forbids: [].}
  1. proc debugSend(smtp: AsyncSmtp; cmd: string): owned(Future[void]) {.
  2.     ...stackTrace: false, raises: [Exception], tags: [RootEffect], forbids: [].}

Sends cmd on the socket connected to the SMTP server.

If the smtp object was created with debug enabled, debugSend will invoke echo(“C:” & cmd) before sending.

This is a lower level proc and not something that you typically would need to call when using this module. One exception to this is if you are implementing any SMTP extensions.

  1. proc debugSend(smtp: Smtp; cmd: string) {....raises: [SslError, OSError],
  2.     tags: [WriteIOEffect], forbids: [].}
  1. proc dial(address: string; port: Port; useSsl = false; debug = false;
  2.           sslContext: SslContext = nil; helo: bool = true): Smtp {....raises: [
  3.     LibraryError, SslError, Exception, IOError, OSError, TimeoutError,
  4.     ReplyError], tags: [RootEffect, ReadDirEffect, ReadEnvEffect, ReadIOEffect,
  5.                         WriteIOEffect, TimeEffect], forbids: [].}
  1. proc dialAsync(address: string; port: Port; useSsl = false; debug = false;
  2.                sslContext: SslContext = nil; helo: bool = true): Future[
  3.     AsyncSmtp] {....stackTrace: false, raises: [Exception, ValueError], tags: [
  4.     RootEffect, ReadDirEffect, ReadEnvEffect, ReadIOEffect], forbids: [].}
  1. proc ehlo(smtp: AsyncSmtp): Future[bool] {....stackTrace: false,
  2.     raises: [Exception, ValueError], tags: [RootEffect], forbids: [].}

Sends EHLO request.

  1. proc ehlo(smtp: Smtp): bool {....raises: [SslError, OSError, TimeoutError],
  2.                               tags: [WriteIOEffect, ReadIOEffect, TimeEffect],
  3.                               forbids: [].}
  1. proc helo(smtp: AsyncSmtp; helo: string = "HELO"): owned(Future[void]) {.
  2.     ...stackTrace: false, raises: [Exception], tags: [RootEffect], forbids: [].}
  1. proc helo(smtp: Smtp; helo: string = "HELO") {.
  2.     ...raises: [SslError, OSError, TimeoutError, ReplyError],
  3.     tags: [WriteIOEffect, ReadIOEffect, TimeEffect], forbids: [].}
  1. proc lhlo(smtp: AsyncSmtp): owned(Future[void]) {....stackTrace: false,
  2.     raises: [Exception], tags: [RootEffect], forbids: [].}
  1. proc lhlo(smtp: Smtp) {....raises: [SslError, OSError, TimeoutError, ReplyError],
  2.                         tags: [WriteIOEffect, ReadIOEffect, TimeEffect],
  3.                         forbids: [].}
  1. proc newAsyncSmtp(useSsl = false; debug = false; sslContext: SslContext = nil): AsyncSmtp {.
  2.     ...raises: [LibraryError, SslError, Exception, IOError, OSError],
  3.     tags: [RootEffect, ReadDirEffect, ReadEnvEffect, ReadIOEffect], forbids: [].}

Creates a new AsyncSmtp instance.

  1. proc newSmtp(useSsl = false; debug = false; sslContext: SslContext = nil): Smtp {.
  2.     ...raises: [LibraryError, SslError, Exception, IOError, OSError],
  3.     tags: [RootEffect, ReadDirEffect, ReadEnvEffect, ReadIOEffect], forbids: [].}

Creates a new Smtp instance.

  1. proc sendMail(smtp: AsyncSmtp; fromAddr: string; toAddrs: seq[string];
  2.               msg: string): owned(Future[void]) {....stackTrace: false,
  3.     raises: [Exception], tags: [RootEffect], forbids: [].}

Sends msg from fromAddr to the addresses specified in toAddrs. Messages may be formed using createMessage by converting the Message into a string.

You need to make sure that fromAddr and toAddrs don’t contain any newline characters. Failing to do so will raise AssertionDefect.

  1. proc sendMail(smtp: Smtp; fromAddr: string; toAddrs: seq[string]; msg: string) {.
  2.     ...raises: [SslError, OSError, TimeoutError, ReplyError],
  3.     tags: [WriteIOEffect, ReadIOEffect, TimeEffect], forbids: [].}
  1. proc startTls(smtp: AsyncSmtp; sslContext: SslContext = nil): owned(
  2.     Future[void]) {....stackTrace: false, raises: [Exception], tags: [RootEffect,
  3.     ReadDirEffect, ReadEnvEffect, ReadIOEffect], forbids: [].}

Put the SMTP connection in TLS (Transport Layer Security) mode. May fail with ReplyError

  1. proc startTls(smtp: Smtp; sslContext: SslContext = nil) {....raises: [SslError,
  2.     OSError, TimeoutError, ReplyError, Exception, LibraryError, IOError], tags: [
  3.     WriteIOEffect, ReadIOEffect, TimeEffect, RootEffect, ReadDirEffect,
  4.     ReadEnvEffect], forbids: [].}