Standard library · Network

net/email

Sending email over SMTP and reading it over IMAP and POP3.

import net.email

On this page

Types
Functions

To send one email, Send is the simplest way. For more control, several recipients for instance, drive the SMTP client step by step. To read a mailbox, IMAP leaves the messages on the server and POP3 takes them away.

Most servers accept nothing but an encrypted connection; use the Dial...TLS functions or StartTLS. The client example only compiles, because it needs a real server.

Types

`IMAPClient`

struct IMAPClient

An IMAP client for reading a mailbox.

Name	Type	Description
`conn`	`tcp.Conn`	The connection.
`secure`	`bool = false`	It is encrypted.
`tls_idx`	`int = -1`	The internal TLS index.
`ok`	`bool = false`	The connection is up.
`rxbuf`	`str = ""`	The data not yet read.
`tag_counter`	`int = 0`	The command tag counter.

net-email-Clients.salam

import net.email

func main:
    mut smtp := email.DialSMTPTLS("smtp.example.com", 465)
    if smtp.ok and email.Hello(smtp, "example.com") and email.AuthLogin(smtp, "ali", "secret"):
        _ := email.MailFrom(smtp, "ali@example.com")
        _ := email.RcptTo(smtp, "sara@example.com")
        _ := email.Data(smtp, email.BuildMessage("ali@example.com", "sara@example.com", "hello", "some text", ""))
    end
    email.Quit(smtp)
    mut smtp2 := email.DialSMTP("smtp.example.com", 587)
    _ := email.StartTLS(smtp2, "smtp.example.com")
    _ := email.AuthPlain(smtp2, "ali", "secret")
    _ := email.AuthXOAuth2(smtp2, "ali", "token")
    println smtp2.last_reply
    _ := email.Send("smtp.example.com", 465, true, "ali", "secret", "ali@example.com", "sara@example.com", "hello", "some text", "")
    mut imap := email.DialIMAPTLS("imap.example.com", 993)
    _ := email.Login(imap, "ali", "secret")
    _ := email.LoginXOAuth2(imap, "ali", "token")
    println email.List(imap, "", "*")
    _ := email.Select(imap, "INBOX")
    println email.Fetch(imap, "1:5", "(FLAGS BODY[HEADER.FIELDS (SUBJECT)])")
    reply := email.Command(imap, "NOOP")
    println reply.ok, reply.status, reply.lines.len()
    email.Logout(imap)
    _ := email.DialIMAP("imap.example.com", 143)
    mut pop := email.DialPOP3TLS("pop.example.com", 995)
    _ := email.User(pop, "ali")
    _ := email.Pass(pop, "secret")
    println email.Stat(pop), email.POP3List(pop)
    println email.Retr(pop, 1)
    _ := email.Dele(pop, 1)
    email.POP3Quit(pop)
    _ := email.DialPOP3("pop.example.com", 110)
end

`IMAPReply`

struct IMAPReply

The reply to one IMAP command.

Name	Type	Description
`ok`	`bool = false`	The reply was OK.
`status`	`str = ""`	The closing status line.
`lines`	`Vector`	The lines of the reply.

The example for this item is shown with the ones above: net-email-Clients.salam

`SMTPClient`

struct SMTPClient

An SMTP client for sending email.

Name	Type	Description
`conn`	`tcp.Conn`	The connection.
`secure`	`bool = false`	It is encrypted.
`tls_idx`	`int = -1`	The internal TLS index.
`ok`	`bool = false`	The connection is up.
`rxbuf`	`str = ""`	The data not yet read.
`last_reply`	`str = ""`	The last reply of the server; for debugging.

The example for this item is shown with the ones above: net-email-Clients.salam

`POP3Client`

struct POP3Client

A POP3 client for taking email away.

Name	Type	Description
`conn`	`tcp.Conn`	The connection.
`secure`	`bool = false`	It is encrypted.
`tls_idx`	`int = -1`	The internal TLS index.
`ok`	`bool = false`	The connection is up.
`rxbuf`	`str = ""`	The data not yet read.

The example for this item is shown with the ones above: net-email-Clients.salam

Functions

`DialIMAP`

func DialIMAP(host: str, port: int): IMAPClient

Connects to an IMAP server, usually port 143.

The example for this item is shown with the ones above: net-email-Clients.salam

`DialIMAPTLS`

func DialIMAPTLS(host: str, port: int): IMAPClient

Connects encrypted, usually port 993.

The example for this item is shown with the ones above: net-email-Clients.salam

`Command`

func Command(c &: IMAPClient, cmd: str): IMAPReply

Sends any IMAP command.

The example for this item is shown with the ones above: net-email-Clients.salam

`Login`

func Login(c &: IMAPClient, username: str, password: str): bool

Logs in with a user name and password.

The example for this item is shown with the ones above: net-email-Clients.salam

`LoginXOAuth2`

func LoginXOAuth2(c &: IMAPClient, username: str, access_token: str): bool

Logs in with an OAuth token.

The example for this item is shown with the ones above: net-email-Clients.salam

`Select`

func Select(c &: IMAPClient, mailbox: str): bool

Picks a mailbox, INBOX for instance, to work in.

The example for this item is shown with the ones above: net-email-Clients.salam

`List`

func List(c &: IMAPClient, reference: str, pattern: str): Vector<str>

Lists the names of the mailboxes.

The example for this item is shown with the ones above: net-email-Clients.salam

`Fetch`

func Fetch(c &: IMAPClient, seq: str, items: str): Vector<str>

Fetches messages or parts of them.

The example for this item is shown with the ones above: net-email-Clients.salam

`Logout`

func Logout(c &: IMAPClient)

Logs out and closes the connection.

The example for this item is shown with the ones above: net-email-Clients.salam

`BuildXOAuth2`

func BuildXOAuth2(username: str, access_token: str): str

Builds the XOAUTH2 login string as base64, for logging in with an OAuth token, as Gmail wants.

net-email-Message.salam

import net.email
import str

func main:
    message := email.BuildMessage("ali@example.com", "sara@example.com", "hello", "plain text", "<p>some <b>nice</b> text</p>")
    each line in str.Split(message, "\r\n"):
        if str.StartsWith(line, "From:") or str.StartsWith(line, "To:") or str.StartsWith(line, "MIME-Version:") or str.StartsWith(line, "Subject:"):
            println line
        end
    end
    println str.Contains(message, "multipart/alternative")
    println email.BuildXOAuth2("ali@example.com", "ya29.token")
end

OutputFrom: ali@example.com To: sara@example.com Subject: hello MIME-Version: 1.0 true dXNlcj1hbGlAZXhhbXBsZS5jb20BYXV0aD1CZWFyZXIgeWEyOS50b2tlbgEB

`DialSMTP`

func DialSMTP(host: str, port: int): SMTPClient

Connects to an SMTP server, usually port 587 or 25.

The example for this item is shown with the ones above: net-email-Clients.salam

`DialSMTPTLS`

func DialSMTPTLS(host: str, port: int): SMTPClient

Connects encrypted from the start, usually port 465.

The example for this item is shown with the ones above: net-email-Clients.salam

`Hello`

func Hello(c &: SMTPClient, domain: str): bool

Sends the EHLO greeting with the domain name of the sender.

The example for this item is shown with the ones above: net-email-Clients.salam

`StartTLS`

func StartTLS(c &: SMTPClient, host: str): bool

Encrypts a plain connection with STARTTLS.

The example for this item is shown with the ones above: net-email-Clients.salam

`AuthLogin`

func AuthLogin(c &: SMTPClient, username: str, password: str): bool

Logs in with the LOGIN method.

The example for this item is shown with the ones above: net-email-Clients.salam

`AuthPlain`

func AuthPlain(c &: SMTPClient, username: str, password: str): bool

Logs in with the PLAIN method.

The example for this item is shown with the ones above: net-email-Clients.salam

`AuthXOAuth2`

func AuthXOAuth2(c &: SMTPClient, username: str, access_token: str): bool

Logs in with an OAuth token.

The example for this item is shown with the ones above: net-email-Clients.salam

`MailFrom`

func MailFrom(c &: SMTPClient, addr: str): bool

Declares the sender address.

The example for this item is shown with the ones above: net-email-Clients.salam

`RcptTo`

func RcptTo(c &: SMTPClient, addr: str): bool

Adds one recipient; call it again for each further one.

The example for this item is shown with the ones above: net-email-Clients.salam

`Data`

func Data(c &: SMTPClient, raw_message: str): bool

Sends the complete text of the message.

The example for this item is shown with the ones above: net-email-Clients.salam

`Quit`

func Quit(c &: SMTPClient)

Ends the session and closes the connection.

The example for this item is shown with the ones above: net-email-Clients.salam

`BuildMessage`

func BuildMessage(from: str, to_addr: str, subject: str, text_body: str, html_body: str): str

Builds a complete email message with From, To and Subject headers. When you give both plain text and HTML, the message becomes multipart/alternative so every mail program can show the version that suits it.

The example for this item is shown with the ones above: net-email-Message.salam

`Send`

func Send(host: str, port: int, use_tls: bool, username: str, password: str, from: str, to_addr: str, subject: str, text_body: str, html_body: str): bool

Sends an email in one step: it connects, logs in and sends the message. When use_tls is true it connects encrypted from the start.

The example for this item is shown with the ones above: net-email-Clients.salam

`DialPOP3`

func DialPOP3(host: str, port: int): POP3Client

Connects to a POP3 server, usually port 110.

The example for this item is shown with the ones above: net-email-Clients.salam

`DialPOP3TLS`

func DialPOP3TLS(host: str, port: int): POP3Client

Connects encrypted, usually port 995.

The example for this item is shown with the ones above: net-email-Clients.salam

`User`

func User(c &: POP3Client, username: str): bool

Sends the user name.

The example for this item is shown with the ones above: net-email-Clients.salam

`Pass`

func Pass(c &: POP3Client, password: str): bool

Sends the password.

The example for this item is shown with the ones above: net-email-Clients.salam

`Stat`

func Stat(c &: POP3Client): str

The number of messages and their total size.

The example for this item is shown with the ones above: net-email-Clients.salam

`POP3List`

func POP3List(c &: POP3Client): Vector<str>

The list of messages with their size.

The example for this item is shown with the ones above: net-email-Clients.salam

`Retr`

func Retr(c &: POP3Client, msgnum: int): str

The complete text of one message.

The example for this item is shown with the ones above: net-email-Clients.salam

`Dele`

func Dele(c &: POP3Client, msgnum: int): bool

Marks the message for deletion; it goes when you log out.

The example for this item is shown with the ones above: net-email-Clients.salam

`POP3Quit`

func POP3Quit(c &: POP3Client)

Logs out and makes the deletions final.

The example for this item is shown with the ones above: net-email-Clients.salam