imapmail

package
v1.162.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package imapmail reads a dedicated platform mailbox over IMAP for the imap connection kind (#2247): a TLS session, folders opened read-only, searches, header and whole-message fetches, and the reading of a message's MIME parts into plain text the platform can show. Which messages may be shown is internal/mailtrust's.

It only reads. Folders are opened with EXAMINE and bodies fetched with BODY.PEEK, so the server never marks a message seen, and there is no STORE, COPY, MOVE, EXPUNGE, APPEND or send to call.

Index

Constants

View Source
const (
	// TLSImplicit is IMAPS: TLS from the first byte, port 993.
	TLSImplicit = "tls"
	// TLSStartTLS upgrades a port-143 connection before anything is sent.
	TLSStartTLS = "starttls"
)

The two ways a connection reaches the server. Plain IMAP is not one of them: the account's password would cross the network in the clear.

Variables

View Source
var ErrAttachmentNotFound = errors.New("imapmail: the message has no attachment at that index")

ErrAttachmentNotFound is the refusal of an attachment index the message does not have.

View Source
var ErrNoSuchMessage = errors.New("imapmail: no message with that uid in the folder")

ErrNoSuchMessage is the refusal of a UID the folder does not hold.

Functions

func HTMLToText

func HTMLToText(body string) string

HTMLToText reads an HTML body as the text a person reading the message would see, and nothing else: scripts, styles, comments and the document head are dropped, and so is every element a sender hid from the reader (the hidden attribute, aria-hidden, display:none, visibility:hidden, zero font size, zero opacity, zero width or height), which is where an instruction meant only for a model would be put. Images become their alt text; a link keeps its text and, when the address differs from it, the address in brackets. Nothing is fetched.

Types

type Account

type Account struct {
	Host     string
	Port     int
	TLS      string
	Username string
	Password string
	// TLSConfig carries the CA bundle and server name; nil uses the system
	// roots and Host.
	TLSConfig *tls.Config
	// DialTimeout bounds connecting and logging in.
	DialTimeout time.Duration
}

Account is how one mailbox is reached.

func (Account) Address

func (a Account) Address() string

Address is host:port.

type Attachment

type Attachment struct {
	// Index addresses the attachment within its message, for
	// mail_attachment; it is the attachment's position, from zero.
	Index       int    `json:"index"`
	Name        string `json:"name"`
	ContentType string `json:"content_type"`
	Size        int64  `json:"size"`
}

Attachment is a part a message carries as a file.

func ReadAttachment

func ReadAttachment(raw []byte, index int) (Attachment, []byte, error)

ReadAttachment returns the bytes of attachment index.

type Body

type Body struct {
	Text string
	// Format is "text" when the message had a plain-text part, "html" when
	// the text was read from its HTML, and "none" when it had neither.
	Format      string
	Attachments []Attachment
}

Body is a message's readable text and the files it carries.

func ReadBody

func ReadBody(raw []byte) (Body, error)

ReadBody walks a whole message: the first text/plain part is the body, else the first text/html part read as text; every part with a filename, or an attachment disposition, is listed.

type Criteria

type Criteria struct {
	// SinceUID returns only messages with a UID above it: a folder's
	// watermark.
	SinceUID uint32
}

Criteria is what a search narrows by.

type Envelope

type Envelope struct {
	UID  uint32
	Size int64
	// Arrived is when the server received the message (INTERNALDATE).
	Arrived     time.Time
	Header      []byte
	Attachments []Attachment
}

Envelope is what a header fetch returns for one message.

type Headers

type Headers struct {
	From        string
	To          []string
	Cc          []string
	Subject     string
	Date        time.Time
	MessageID   string
	InReplyTo   string
	References  []string
	AuthResults []string
}

Headers is what the platform reads from a message's header block: the fields the trust policy judges by and the fields a tool reports.

func ReadHeaders

func ReadHeaders(raw []byte) (Headers, error)

ReadHeaders parses a message's header block (all of a message, or the header section alone as BODY.PEEK[HEADER] returns it).

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session is one logged-in connection to the account. It is not safe for concurrent use: a tool call opens one, uses it, and closes it.

func Open

func Open(ctx context.Context, a Account) (*Session, error)

Open connects, negotiates TLS, and logs in. ctx bounds the whole session: when it ends, the connection is closed and any command waiting fails.

func (*Session) Close

func (s *Session) Close() error

Close logs out and closes the connection.

func (*Session) Examine

func (s *Session) Examine(folder string) (uidValidity, messages uint32, err error)

Examine opens folder read-only (EXAMINE), so nothing the session does can change it, and returns its UIDVALIDITY and message count. A connection an earlier folder's failure closed is opened again first, so one folder's failure is never another's (#2459).

func (*Session) Headers

func (s *Session) Headers(uids []uint32) ([]Envelope, []Unreadable, error)

Headers fetches the header block, size and attachment list of each UID.

A server may describe a message in a form the client cannot parse (a NIL where the protocol requires a list, emersion/go-imap#678), and that one message then fails the whole batch and closes the connection. When the batch fails, the connection is reopened and each UID is fetched alone; one that still fails is fetched once more without BODYSTRUCTURE, its attachments then read from the raw message by whoever reads it. A message that fails both ways is returned as Unreadable for the caller to skip, so the messages beside it are read. A failure that is not the message's (the server's NO, a reconnect that fails, the session's time running out) is the call's error.

func (*Session) Search

func (s *Session) Search(c Criteria) ([]uint32, error)

Search returns the UIDs in the examined folder that match, ascending.

func (*Session) Whole

func (s *Session) Whole(uid uint32, limit int64) ([]byte, error)

Whole fetches one message, refusing it when it is larger than limit bytes.

type Unreadable added in v1.153.0

type Unreadable struct {
	UID    uint32
	Reason string
}

Unreadable is a message the client could not read the server's answer about, even fetched alone and without its structure (#2459). Reason is the client's account of the answer it could not parse, which names protocol tokens and never the message's content.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL