Skip to main content

Intro

note

This version is currently published under the next dist-tag on npm:

npm install cf-imap@next
# or with bun
bun add cf-imap@next

It will be promoted to latest once the stable 1.0.0 release ships.

cf-imap is an IMAPv4 library for use within the Cloudflare Workers platform.

This package was made because all of the other IMAP libraries are built for NodeJS, and Cloudflare Workers even with node compatibility turned does not support them.

Provider support​

Most providers stick to the two IMAP specifications (RFC 3501 and RFC 9051), however some have their own experimental implementations.

note

Gmail and Outlook require OAuth2 — both providers (and Microsoft 365, Yahoo, and others) no longer accept passwords over IMAP. cf-imap supports them via the XOAUTH2 SASL mechanism: pass an OAuth 2.0 access token with auth.accessToken (or auth.getAccessToken) and connect() handles the rest — see Initialisation → OAuth 2.0. You must obtain and refresh the token yourself (the library does not run the OAuth flow).

However, if the provider you are using isn't tested, uses their own implementation of IMAP and cf-imap is throwing errors on things that should work (see: Errors), please raise an issue on GitHub so I can promptly fix it.

Features​

RFC 9051 (IMAP4rev2) compliance​

cf-imap is written against the current IMAP specification, RFC 9051 (IMAP4rev2), while staying compatible with the widely deployed IMAP4rev1 (RFC 3501):

  • TLS — Implicit TLS on port 993 (RFC 8314) and opportunistic TLS via STARTTLS on other ports (RFC 9051 §6.2.1).
  • Authentication — AUTHENTICATE PLAIN with SASL-IR preferred; LOGIN only as a last resort and never with LOGINDISABLED; AUTHENTICATE XOAUTH2 (OAuth 2.0 access tokens) for providers that require OAuth2 (RFC 9051 §6.2.2/§6.2.3, RFC 7628-style).
  • IMAP4rev2 negotiation — ENABLE IMAP4rev2 is issued automatically on dual-version servers (RFC 9051 Appendix A).
  • Search — both * SEARCH (rev1) and * ESEARCH (rev2) responses are parsed (RFC 9051 §6.4.4).
  • Mailbox names — UTF-8 (Net-Unicode) on rev2 sessions; automatic modified UTF-7 (RFC 2152) conversion on rev1-only servers.
  • UID tracking — COPYUID (copy/move) and APPENDUID (append) response codes are surfaced.
  • Commands removed in RFC 9051 (CHECK, \Recent-based search keys) are handled gracefully.

Breaking changes from v0.x.x​

The v1.0.0 rewrite focused on protocol correctness: a tagged command pipeline with a literal-aware response reader, robust parsing, proper error handling, and full MIME support. As a result some public APIs changed:

  • The Email type was reworked — from/to/cc are now string[], date was renamed to internalDate, and body is now an object ({ text?, html?, raw }) plus a new attachments array.
  • fetchEmails props changed — folder is now optional (falls back to the selected folder), fetchBody defaults to true, and a new useUid option was added.
  • getNamespaces now returns a typed object ({ personal, other, shared }) instead of string[].
  • selectFolder now returns a fully typed MailboxInfo instead of a dynamic object.
  • expunge now takes an options object ({ range?, useUid? }), and UID EXPUNGE requires a range.
  • copy() and move() now return a CopyUidInfo (or null), and append() returns an AppendResult (or null).
  • New commands: examine(), idle(), closeMailbox(), unselect(), capability(), noop(), enable().
  • New authentication mode: auth now also accepts an OAuth 2.0 access token (auth.accessToken) or a token callback (auth.getAccessToken) for XOAUTH2 — see Initialisation → OAuth 2.0.
  • check() only works on IMAP4rev1 servers — it throws on IMAP4rev2 sessions.
  • The raw socket, writer, reader, encoder & decoder are no longer public (see Extendability).