email

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793783355/FIN+5.3.1+email 中文整理基于 FIN 5.3.1

导读： 电子邮件模块提供用于处理电子邮件的 API。支持以下功能：

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

目录（导读）

classes
errs
docs
Overview
SMTP
Email
TextPart
MultiPart
FilePart
Slot Details
- bcc
- body
- cc
- encode
- from
- msgId
- recipients
- replyTo
- subject
- to
- validate
- headers
- file
- make
- toAddrSpec
- toEncodedWord
- parts
- authCramMd5
- authLogin
- authPlain
- authenticate
- close
- host
- isClosed
- open
- password
- port
- send
- socketConfig
- ssl
- username
- code
- text

API 正文（英文）

docs

Overview

The email pod provides APIs for working with electronic mail. The following features are supported:

Email is used to model MIME multipart messages
SmtpClient implements the client side of the Simple Mail Transfer Protocol

Note: at the current time there is no support for incoming email such as POP3 or IMAP. If you need this functionality, please let us know.

See examples for sample code.

SMTP

The SmtpClient class lets you relay mail to a SMTP server. An instance of SmtpClient is configured with a host (and port if not using 25). If you wish to use SMTP authentication you will also need to configure the username and password:

mailer := SmtpClient { host = "mail.foo.com"; username = "bob"; password = "pw" }

The following authentication mechanisms are currently supported: CRAM-MD5, LOGIN, and PLAIN. If you need another auth mechanism please let us know.

Once the SmtpClient is configured you can open a session, send emails, and then close the session:

mailer.open
try
{
  emails.each |Email email| { mailer.send(email) }
}
finally
{
  mailer.close
}

If you just have one email to send, the send method will automatically open and close the session for you:

mailer.send(email)

If you run into trouble, you can turn on tracing:

mailer.log.level = LogLevel.trace

Email

The Email class is used to model a MIME message. Typical use is to construct a Email instance using it-blocks:

email := Email
{
  to = ["foo@somewhere.com"]
  from = "bob@foo.com"
  subject = "hi"
  body = TextPart { text = "hello world" }
}

The email recipients are configured in the to, cc, bcc fields which are a list of Str email addresses.

The body can be a simple part such as TextPart or can be a multipart via MultiPart. All email parts have a set of headers which define how they are encoded. The validate method is called before sending an email which checks that headers are correctly configured and performs header normalization.

TextPart

The TextPart is used to represent text via a Str. By default a TextPart defaults to "text/plain":

TextPart { text = "some text" }

Override the "Content-Type" header to specify another MIME type:

TextPart
{
  headers["Content-Type"] = "text/html; charset=utf-8"
  text = "this is <b>bold</b> and <i>italics</i>!"
}

By default a TextPart is encoded using an 8bit transfer encoding and the UTF-8 charset. If a charset is not explicitly defined it defaults to UTF-8 in the validate method. Or you can define an explicit charset yourself in the "Content-Type" header:

TextPart
{
  headers["Content-Type"] = "text/plain; charset=us-ascii"
  text = "hello world"
}

MultiPart

The MultiPart class is used to encode MIME multiparts. By default the "Content-Type" defaults "multipart/mixed". Mixed is typically used with file attachments. The "multipart/alternative" is used when sending HTML email and you wish you provide a plain text fallback. The multipart boundary is automatically generated in the validate method.

FilePart

The FilePart class is used to encode a binary attachment from a File instance. If you don't provide a "Content-Type", it will automatically default to File.mimeType. If you don't specify a name parameter and the file name is ASCII, then a name parameter will be automatically defined:

part := FilePart { file = `image.jpg`.toFile }
part.validate
part.headers["Content-Type"]  =>  "image/jpeg; name="image.jpg"

FileParts are transfered as base64 - you may not override the "Content-Transfer-Encoding" header.

Email

@Serializable class Email : Obj

Email models a top level MIME message.

See pod doc and examples.

Fields


bcc	List of "bcc" email addresses.
body	Body of the email - typically an instance of `TextPart` or `MultiPart`.
cc	List of "cc" email addresses.
from	From email address.
msgId	Unique identifier for message (auto-generated).
replyTo	Reply-To email address.
subject	Subject of the email.
to	List of "to" email addresses.

Methods


encode	Encode as a MIME message according to RFC 822.
recipients	Return the aggregation of `to`, `cc`, and `bcc`.
validate	Validate this email message - throw Err if not configured correctly.

Slot Details

bcc

Str[]? bcc

List of "bcc" email addresses. See MimeUtil.toAddrSpec for address formatting.

body

EmailPart? body

Body of the email - typically an instance of TextPart or MultiPart.

cc

Str[]? cc

List of "cc" email addresses. See MimeUtil.toAddrSpec for address formatting.

encode

virtual Void encode(OutStream out)

Encode as a MIME message according to RFC 822.

from

Str? from

From email address. See MimeUtil.toAddrSpec for address formatting.

msgId

Str msgId := ...

Unique identifier for message (auto-generated).

recipients

Str[] recipients()

Return the aggregation of to, cc, and bcc.

replyTo

Str? replyTo

Reply-To email address.

subject

Str subject := ""

Subject of the email. This string can be any Unicode and is automatically translated into an encoded word.

to

Str[]? to

List of "to" email addresses. See MimeUtil.toAddrSpec for address formatting.

validate

virtual Void validate()

Validate this email message - throw Err if not configured correctly.

EmailPart

@Serializable abstract class EmailPart : Obj

EmailPart is the base class for parts within a multipart MIME document.

See pod doc and examples.

Fields


headers	Map of headers.

Methods


encode	Encode as a MIME message according to RFC 822.
validate	Validate this part - throw Err if not configured correctly.

Slot Details

encode

virtual Void encode(OutStream out)

Encode as a MIME message according to RFC 822. The base class encodes the headers - subclasses should override to call super and then encode the part's content.

headers

Str:Str headers := ...

Map of headers. The header map is case insensitive.

validate

virtual Void validate()

Validate this part - throw Err if not configured correctly.

FilePart

class FilePart : EmailPart

FilePart is used to transfer binary content from a File.

Constructors


make	Construct with default type of "text/plain".

Fields


file	File content

Methods


encode	Encode as a MIME message according to RFC 822.
validate	Validate this part - throw Err if not configured correctly

Slot Details

encode

virtual override Void encode(OutStream out)

Encode as a MIME message according to RFC 822.

file

File? file

File content

make

new make()

Construct with default type of "text/plain".

validate

virtual override Void validate()

Validate this part - throw Err if not configured correctly:

file must be non-null
if Content-Type not set, defaults to file.mimeType
if Content-Type name param not set, defaults to file.name
Content-Transfer-Encoding must be base64

MimeUtil

class MimeUtil : Obj

Utilities to deal with all the idiosyncrasies of MIME.

Methods


toAddrSpec	Return the addr-spec or "local@domain" part of an email address string.
toEncodedWord	Encode the specified text into a "encoded word" according to RFC 2047.

Slot Details

toAddrSpec

static Str toAddrSpec(Str addr)

Return the addr-spec or "local@domain" part of an email address string. The result is always returned as "<addr>". The addresses may be formatted with or without a display name:

bob@acme.com                =>  <bob@acme.com>
Bob Smith <bob@acme.com>    =>  <bob@acme.com>
"Bob Smith" <bob@acme.com>  =>  <bob@acme.com>

toEncodedWord

static Str toEncodedWord(Str text)

Encode the specified text into a "encoded word" according to RFC 2047. If text is pure ASCII, then it is returned as is. Otherwise encode using UTF-8 Base64.

MultiPart

@Serializable class MultiPart : EmailPart

MultiPart is used to model a multipart MIME type. The default is "multipart/mixed".

Constructors


make	Construct with default type of "multipart/mixed".

Fields


parts	The sub-parts of this multipart.

Methods


encode	Encode as a MIME message according to RFC 822.
validate	Validate this part - throw Err if not configured correctly

Slot Details

encode

virtual override Void encode(OutStream out)

Encode as a MIME message according to RFC 822.

make

new make()

Construct with default type of "multipart/mixed".

parts

EmailPart[] parts := EmailPart[,]

The sub-parts of this multipart.

validate

virtual override Void validate()

Validate this part - throw Err if not configured correctly:

must have at least one part
Content-Type must be defined
if Content-Type doesn't define boundary, one is auto-generated

SmtpClient

class SmtpClient : Obj

SmtpClient implements the client side of SMTP (Simple Mail Transport Protocol) as specified by RFC 2821.

See pod doc and examples.

Fields


host	DNS hostname of server.
password	Password to use for authentication, or null to skip authentication.
port	TCP port number of server, defaults to 25.
socketConfig	The `SocketConfig` to use for creating sockets.
ssl	Open connection using SSL/TLS (ensure port is configured properly).
username	Username to use for authentication, or null to skip authentication.

Methods


authCramMd5	Authenticate using CRAM-MD5 mechanism.
authLogin	Authenticate using LOGIN mechanism.
authPlain	Authenticate using PLAIN mechanism.
authenticate	Authenticate using the strongest mechanism which both the server and myself support.
close	Close the session to the SMTP server.
isClosed	Return true if there is no open session.
open	Open a session to the SMTP server.
send	Send the email to the SMTP server.

Slot Details

authCramMd5

Void authCramMd5()

Authenticate using CRAM-MD5 mechanism.

authLogin

Void authLogin()

Authenticate using LOGIN mechanism.

authPlain

Void authPlain()

Authenticate using PLAIN mechanism.

authenticate

Void authenticate()

Authenticate using the strongest mechanism which both the server and myself support.

close

Void close()

Close the session to the SMTP server. Do nothing if session already closed.

host

Str? host

DNS hostname of server.

isClosed

Bool isClosed()

Return true if there is no open session.

open

Void open()

Open a session to the SMTP server. If username and password are configured, then SMTP authentication is attempted. Throw SmtpErr if there is a protocol error. Throw IOErr is there is a network problem.

password

Str? password

Password to use for authentication, or null to skip authentication.

port

Int port := 25

TCP port number of server, defaults to 25.

send

Void send(Email email)

Send the email to the SMTP server. Throw SmtpErr if there is a protocol error. Throw IOErr if there is a networking problem. If the session is closed, then this call automatically opens the session and guarantees a close after it is complete.

socketConfig

SocketConfig socketConfig := SocketConfig.cur

The SocketConfig to use for creating sockets.

ssl

Bool ssl

Open connection using SSL/TLS (ensure port is configured properly). If false then the connection is opened plaintext, but may still be upgraded to TLS if server specifies STARTTLS.

username

Str? username

Username to use for authentication, or null to skip authentication.

SmtpErr

const class SmtpErr : Err

SmtpErr indicates an error during an SMTP transaction.

Constructors


make	Construct with error code, message, and optional cause.

Fields


code	The SMTP error code defined by RFC 2821

Slot Details

code

const Int code

The SMTP error code defined by RFC 2821

make

new make(Int code, Str? msg, Err? cause := null)

Construct with error code, message, and optional cause.

TextPart

@Serializable class TextPart : EmailPart

TextPart is used to model email parts with a text MIME type. The default is "text/plain".

Constructors


make	Construct with default type of "text/plain".

Fields


text	Text body of the email part.

Methods


encode	Encode as a MIME message according to RFC 822.
validate	Validate this part - throw Err if not configured correctly

Slot Details

encode

virtual override Void encode(OutStream out)

Encode as a MIME message according to RFC 822.

make

new make()

Construct with default type of "text/plain".

text

Str text := ""

Text body of the email part.

validate

virtual override Void validate()

Validate this part - throw Err if not configured correctly:

text must be non-null
Content-Type must be defined
if Content-Type charset not defined, defaults to utf-8
Content-Transfer-Encoding must be 8bit unless using us-ascii

email ​

目录（导读） ​

API 正文（英文） ​

docs ​

Overview ​

SMTP ​

Email ​

TextPart ​

MultiPart ​

FilePart ​

Email ​

Slot Details ​

bcc ​

body ​

cc ​

encode ​

from ​

msgId ​

recipients ​

replyTo ​

subject ​

to ​

validate ​

EmailPart ​

Slot Details ​

encode ​

headers ​

validate ​

FilePart ​

Slot Details ​

encode ​

file ​

make ​

validate ​

MimeUtil ​

Slot Details ​

toAddrSpec ​

toEncodedWord ​

MultiPart ​

Slot Details ​

encode ​

make ​

parts ​

validate ​

SmtpClient ​

Slot Details ​

authCramMd5 ​

authLogin ​

authPlain ​

authenticate ​

close ​

host ​

isClosed ​

open ​

password ​

port ​

send ​

socketConfig ​

ssl ​

username ​

SmtpErr ​

Slot Details ​

code ​

make ​

TextPart ​

Slot Details ​

encode ​

make ​

text ​

validate ​

email

目录（导读）

API 正文（英文）

docs

Overview

SMTP

Email

TextPart

MultiPart

FilePart

Email

Slot Details

bcc

body

cc

encode

from

msgId

recipients

replyTo

subject

to

validate

EmailPart

Slot Details

encode

headers

validate

FilePart

Slot Details

encode

file

make

validate

MimeUtil

Slot Details

toAddrSpec

toEncodedWord

MultiPart

Slot Details

encode

make

parts

validate

SmtpClient

Slot Details

authCramMd5

authLogin

authPlain

authenticate

close

host

isClosed

open

password

port

send

socketConfig

ssl

username

SmtpErr

Slot Details

code

make

TextPart

Slot Details

encode

make

text

validate