IMAP & POP3

NEW EMAIL IMAP and NEW EMAIL POP3 connect and authenticate to a mailbox, captured with SET. Every subsequent operation is subject-first — EMAIL ?conn VERB .... This is a separate, dedicated verb family from MAIL, which only sends outbound email — see Mail & Redirection.

Protocol scope. IMAP is a mail-retrieval and folder-management protocol. It supports folders, flags, search, and Gmail-style labels. It does not expose product-only features like Smart Compose, Priority Inbox sorting, Gmail's Category tabs, snoozing, scheduled send, or confidential mode — these are Gmail-the-product features with no IMAP equivalent, regardless of client.

Creating a Mailbox

A mailbox does not have to come from somewhere else. NEW EMAIL ACCOUNT creates one on a subdomain you own, or on a domain already pointed at Ocalt with DOMAIN. Once created, every verb on this page manages it — the account is an ordinary IMAP/POP3 mailbox, reached with the same NEW EMAIL IMAP connection as any other host.

Create an Account on Your Subdomain

NEW EMAIL ACCOUNT "hello" AT "mysite.ocalt.site" WITH PASSWORD "Password" SET ?emailaccountobject
AFTER EMIT ?emailaccountobject("address")

Create an Account on a Pointed Domain

NEW EMAIL ACCOUNT "sales" AT "tld.com" WITH PASSWORD "Password" SET ?acc
AFTER EMIT ?acc("address")
(* tld.com must already be pointed at Ocalt — see DOMAIN on the Site Mode page *)

Two ways it fails. Creation errors if the subdomain does not belong to your namespace, and it errors if the domain is not pointing at Ocalt’s server address. Both are catchable, and ?err("message") says which of the two it was.

Create It, Then Log Into It

NEW EMAIL ACCOUNT "hello" AT "mysite.ocalt.site" WITH PASSWORD "Password" SET ?acc
AFTER NEW EMAIL IMAP ?acc("imap_host") WITH "Password" AS ?acc("address") SET ?conn
AFTER EMAIL ?conn INBOX SET ?inbox
AFTER COUNT ?inbox SET ?n
AFTER EMIT ?n & " messages"

Field	Description
`address`	The full address — `hello@mysite.ocalt.site`
`imap_host`	Host to pass to `NEW EMAIL IMAP`
`pop3_host`	Host to pass to `NEW EMAIL POP3`

IMAP — Connect

NEW EMAIL IMAP speaks the standard protocol, so it connects to any server that does — a company Exchange box, a mailbox at your web host, Fastmail, Zoho, a self-hosted Dovecot, or one you created here. Three things are needed: the host, the address, and that mailbox’s password.

A Mailbox Anywhere

NEW EMAIL IMAP "mail.yourcompany.com" WITH "your_password" AS "you@yourcompany.com" SET ?conn
AFTER EMAIL ?conn INBOX SET ?inbox
AFTER COUNT ?inbox SET ?n
AFTER EMIT ?n & " messages"

Nothing there is Ocalt-specific. A mailbox you create here is the same shape — NEW EMAIL ACCOUNT hands you the host to use, so you never have to look one up.

A Mailbox You Created Here

NEW EMAIL ACCOUNT "hello" AT "mysite.ocalt.site" WITH PASSWORD "Password" SET ?acc
AFTER NEW EMAIL IMAP ?acc("imap_host") WITH "Password" AS ?acc("address") SET ?conn
AFTER EMAIL ?conn INBOX SET ?inbox
AFTER COUNT ?inbox SET ?n
AFTER EMIT ?n

Everything below works identically against an Ocalt mailbox and against a third-party one. The examples use Gmail because it is the strictest case — App Passwords, OAuth2, label extensions — and anything that works there works on a mailbox you created here with less setup.

Connect to a Third-Party Mailbox (Gmail requires an App Password)

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn

OAuth2 — PWTYPE selects the authentication mechanism

NEW EMAIL IMAP "imap.gmail.com" WITH "ya29.access_token" AS "user@gmail.com" PWTYPE "oauth2" SET ?conn

PWTYPE defaults to "plain" — the WITH value is sent as the account password (for Gmail this must be an App Password; Google no longer accepts regular account passwords over IMAP, POP3, or SMTP). With PWTYPE "oauth2" the WITH value is an OAuth2 access token, delivered via SASL XOAUTH2 on IMAP, POP3, and the derived SMTP transport alike. PWTYPE is accepted by both NEW EMAIL IMAP and NEW EMAIL POP3. A failed connection — wrong credentials, unreachable host, unknown PWTYPE — is a catchable E4001, as is every subsequent protocol failure on an EMAIL operation, so OR CATCH ERROR SET ?err receives ?err("code"), ?err("message"), and ?err("verb") — see Error Codes.

IMAP — Folders

List All Folders

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn LIST FOLDERS SET ?folders

Inbox, Sent, Drafts, Spam, Trash

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn INBOX SET ?inbox
AFTER EMAIL ?conn SENT SET ?sent
AFTER EMAIL ?conn DRAFTS SET ?drafts
AFTER EMAIL ?conn SPAM SET ?spam
AFTER EMAIL ?conn TRASH SET ?trash

A Custom Folder

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn FOLDER "Custom Folder Name" SET ?custom

IMAP — Unread and Search

Unread Only

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn UNREAD SET ?new
AFTER COUNT ?new SET ?n
AFTER EMIT ?n & " unread"

Search the Inbox

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn SEARCH "FROM boss@company.com" SET ?msgs

Search a Specific Folder

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn FOLDER "Sent" SEARCH "client@site.com" SET ?results

IMAP — Fetching a Message

Fetch by UID, Retrieved from a Real List

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn INBOX SET ?inbox
AFTER EMIT ?inbox(0)("uid")
AFTER EMAIL ?conn UID ?inbox(0)("uid") SET ?msg
AFTER EMIT ?msg("subject")

IMAP — Flags

Mark Read, Unread, Flagged, Unflagged, Deleted

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn INBOX SET ?inbox
AFTER EMAIL ?conn MARK ?inbox(0)("uid") AS READ
AFTER EMAIL ?conn MARK ?inbox(0)("uid") AS UNREAD
AFTER EMAIL ?conn MARK ?inbox(0)("uid") AS FLAGGED
AFTER EMAIL ?conn MARK ?inbox(0)("uid") AS UNFLAGGED
AFTER EMAIL ?conn MARK ?inbox(0)("uid") AS DELETED

IMAP — Move and Copy

Move a Message

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn INBOX SET ?inbox
AFTER EMAIL ?conn MOVE ?inbox(0)("uid") TO "Trash"

Copy a Message

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn INBOX SET ?inbox
AFTER EMAIL ?conn COPY ?inbox(0)("uid") TO "Custom Folder Name"

IMAP — Labels (Gmail Extension)

Read, Add, Remove Labels

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn INBOX SET ?inbox
AFTER EMAIL ?conn LABELS ?inbox(0)("uid") SET ?labels
AFTER EMAIL ?conn ADD LABEL ?inbox(0)("uid") AS "Important"
AFTER EMAIL ?conn REMOVE LABEL ?inbox(0)("uid") AS "Important"

IMAP — Drafts

Save a Draft

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn SAVE DRAFT TO "recipient@example.com" SUBJECT "Hello" BODY "message text"

IMAP — Close

Close the Connection

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn CLOSE

POP3

POP3 has no folders and no server-side search — it operates on a flat, download-and-delete model. NEW EMAIL POP3 connects the same way as IMAP, but the available operations are LIST, UID, DELETE, and CLOSE.

Connect

NEW EMAIL POP3 "pop.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn

List Messages

NEW EMAIL POP3 "pop.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn LIST SET ?messages

Fetch by UID, Retrieved from a Real List

POP3’s LIST only ever returns uid and size per message — the protocol does not expose subject, sender, date, or body until the full message is fetched by UID.

NEW EMAIL POP3 "pop.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn LIST SET ?messages
AFTER EMIT ?messages(0)("uid")
AFTER EMIT ?messages(0)("size")
AFTER EMAIL ?conn UID ?messages(0)("uid") SET ?msg
AFTER EMIT ?msg("subject")
AFTER EMIT ?msg("from")
AFTER EMIT ?msg("date")
AFTER EMIT ?msg("body")

Delete and Close

NEW EMAIL POP3 "pop.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn LIST SET ?messages
AFTER EMAIL ?conn DELETE ?messages(0)("uid")
AFTER EMAIL ?conn CLOSE

Sending Email

EMAIL ?conn SEND shares the exact same modifier set as MAIL: TO, SUBJECT, BODY, CC, BCC, REPLY TO, HEADER, and ATTACH. All modifiers are optional and can appear in any order.

Basic Send

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn SEND TO "recipient@example.com" SUBJECT "Hello!" BODY "This is the body"
AFTER EMAIL ?conn CLOSE

CC and BCC

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn SEND TO "boss@site.com" CC "team@site.com" SUBJECT "report" BODY "message"
AFTER EMAIL ?conn SEND TO "boss@site.com" BCC "secret@site.com" SUBJECT "hidden copy" BODY "message"

Reply-To

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn SEND TO "support@site.com" SUBJECT "support" BODY "help needed" REPLY TO "user@site.com"

Custom Header

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn SEND TO "email@email.com" HEADER "From: blah@blah.com" SUBJECT "with header" BODY "hello"

Sending Attachments

An attachment is shared to a URL first with FILE SHARE, then passed to SEND via ATTACH. This works identically for a local file or anything already reachable at a web URL. ATTACH accepts a single value or an array of values for multiple attachments.

Attach a Local File

FILE SHARE "/root/invoice.pdf" SET ?url
AFTER NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn SEND TO "client@site.com" SUBJECT "Invoice" BODY "See attached" ATTACH ?url
AFTER EMAIL ?conn CLOSE

Attach an Existing Web URL

NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn SEND TO "client@site.com" SUBJECT "Report" BODY "See attached" ATTACH "https://example.com/report.pdf"
AFTER EMAIL ?conn CLOSE

Multiple Attachments

FILE SHARE "/root/invoice.pdf" SET ?url1
AFTER FILE SHARE "/root/receipt.pdf" SET ?url2
AFTER NEW ARRAY SET ?attachments
AFTER APPEND ?url1 TO ?attachments
AFTER APPEND ?url2 TO ?attachments
AFTER NEW EMAIL IMAP "imap.gmail.com" WITH "app_password" AS "user@gmail.com" SET ?conn
AFTER EMAIL ?conn SEND TO "client@site.com" SUBJECT "Invoice + Receipt" BODY "See attached" ATTACH ?attachments
AFTER EMAIL ?conn CLOSE

EMAIL is a distinct verb family from MAIL — MAIL only sends outbound email, EMAIL connects to and manages a mailbox via IMAP or POP3. NEW EMAIL IMAP and NEW EMAIL POP3 both produce a ?conn subject passed to every subsequent operation. UIDs are always retrieved from a real prior fetch, never hardcoded. SENT, DRAFTS, SPAM, and TRASH are bare keywords; any other folder uses FOLDER "name". EMAIL ... SEND shares the complete MAIL modifier set. POP3 is intentionally more limited than IMAP — no folders, no server-side search, no flags, no labels.

← Browser Automation Weather & Currency →