YOUSEFUL / FILEMAKER

YsflMail — function reference

Function prefix YsflMl_, 19 functions: SMTP sending, POP3 and IMAP retrieval, MIME parsing. TLS through Schannel (system certificate store). Failures return ? message with the server's own reply where there is one (? SMTP AUTH: 535 bad credentials).

Connection options

Space-separated key=value tokens or one per line (cc=, bcc=, replyto=, fromname=, text=, attach=, header= take the rest of their line). The server may be host or host:port.

option	meaning
`port=N`	explicit port
`tls=none\|starttls\|implicit`	default by port: 25/110/143 none, 587 STARTTLS, 465/995/993 implicit
`user=`, `password=`	SMTP authentication (PLAIN or LOGIN, whichever the server offers; `auth=login` forces LOGIN)
`timeout=<sec>`	connect and I/O timeout (default 30)
`verify=0`	ignore certificate errors

Sending

YsflMl_Send ( server ; from ; to ; subject ; body ; {options} ; {attachment} ) → 0

Addresses may be addr, Name <addr> or "Name" <addr>; lists are comma- or line-separated. Non-ASCII subjects and names are RFC 2047 encoded, bodies are UTF-8 quoted-printable, and the message is dot-stuffed on the wire. The optional 7th parameter is a container attached under its file name.

send option	meaning
`cc=`, `bcc=`	more recipients (Bcc never appears in the headers)
`replyto=`, `fromname=`	Reply-To address; display name for the sender
`html`	the body is HTML; add `text=<plain alternative>` for a multipart/alternative message
`attach=<path>`	file attachment, repeatable (one per line)
`priority=high`	`X-Priority: 1` + `Importance: high`
`header=Name: value`	custom header, repeatable

Retrieving

Each call opens its own connection, logs in, does the work, and logs out.

Function	Returns
`YsflMl_Pop3Count ( server ; user ; password ; {options} )`	message count
`YsflMl_Pop3List ( server ; user ; password ; {options} )`	`index\|size\|uid` lines
`YsflMl_Pop3Get ( server ; user ; password ; index ; {options} )`	raw message; option `top=N` for headers plus N body lines
`YsflMl_Pop3Delete ( server ; user ; password ; index ; {options} )`	`0` (committed on QUIT)
`YsflMl_ImapFolders ( server ; user ; password ; {options} )`	folder names
`YsflMl_ImapSearch ( server ; user ; password ; folder ; criteria ; {options} )`	UIDs; criteria in IMAP syntax (`ALL`, `UNSEEN`, `FROM "alice"`, `SINCE 1-Sep-2026`)
`YsflMl_ImapGet ( server ; user ; password ; folder ; uid ; {options} )`	raw message (does not mark it read)
`YsflMl_ImapFlag ( server ; user ; password ; folder ; uid ; flags ; {options} )`	`0`; flags like `+\Seen`, `-\Flagged`, `+\Deleted` (add option `expunge` to purge)
`YsflMl_ImapDelete ( server ; user ; password ; folder ; uid ; {options} )`	`0`; marks deleted and expunges

Parsing raw messages

Function	Returns
`YsflMl_Header ( message ; name )`	decoded header value (folded lines joined, RFC 2047 words decoded)
`YsflMl_Body ( message ; {part} )`	decoded `text` (default; falls back to HTML) or `html` part, converted to UTF-8
`YsflMl_Attachments ( message )`	`index\|filename\|type\|size` lines
`YsflMl_SaveAttachment ( message ; index ; path )`	`0`
`YsflMl_GetAttachment ( message ; index )`	container

Base64 and quoted-printable transfer encodings, nested multipart, RFC 2231 file names and the common charsets (UTF-8, ISO-8859-1/15, windows-1250/1252, US-ASCII, UTF-16) are handled.

Examples

Set Variable [ $r ; YsflMl_Send ( "smtp.example.com:587" ; "Sales <sales@example.com>" ; Contacts::Email ; "Your order " & Orders::ID ; $html ;
    "user=sales@example.com password=" & $pw & "¶html¶text=" & $plain & "¶attach=" & $pdfPath ) ]

Set Variable [ $uids ; YsflMl_ImapSearch ( "imap.example.com" ; $user ; $pw ; "INBOX" ; "UNSEEN" ; "tls=implicit" ) ]
Set Variable [ $raw ; YsflMl_ImapGet ( "imap.example.com" ; $user ; $pw ; "INBOX" ; GetValue ( $uids ; 1 ) ; "tls=implicit" ) ]
Set Field [ Mail::Subject ; YsflMl_Header ( $raw ; "Subject" ) ]
Set Field [ Mail::Body ; YsflMl_Body ( $raw ) ]
Set Field [ Mail::Attachment ; YsflMl_GetAttachment ( $raw ; 1 ) ]