#moonmail

let raw = @utf8.encode(
  "From: Alice <alice@example.com>\r\n" +
  "To: Bob <bob@example.com>\r\n" +
  "Subject: =?utf-8?B?THVuY2g/?=\r\n" +
  "Date: Fri, 06 Nov 2026 12:00:00 +0000\r\n" +
  "MIME-Version: 1.0\r\n" +
  "Content-Type: text/plain; charset=utf-8\r\n" +
  "\r\n" +
  "Noon works.\r\n",
)
let message = @moonmail.Message::parse(raw[:])
assert_eq(message.subject(), Some("Lunch?"))
assert_eq(message.from()[0].address, "alice@example.com")
assert_eq(message.text(), Some("Noon works.\r\n"))

moon run src/examples/tour

#What it does

• Messages — Message::parse and encode: the header unfolded and folded again at 78 columns, a Headers table that keeps order and ignores case and refuses a value that would start a second field, Body as a leaf, parts or an attached message, and the transfer encodings taken off and put back. Writing what was read and reading it again gives the same tree.
• Addresses and dates — RFC 5322's address grammar in full, groups and the obsolete forms included, checked against Python's email; RFC 5322 dates with the old two-digit years and named zones.
• Building — Message::new picks alternative, related and mixed from what it carries. Quoted-printable, encoded words and charsets come from moonmime.
• SASL (@moonmail/sasl) — PLAIN, LOGIN, CRAM-MD5, XOAUTH2, OAUTHBEARER (RFC 7628) and SCRAM-SHA-256 (RFC 7677) with SASLprep (RFC 4013). A mechanism is a trait: one you write goes to authenticate like these.
• POP3 (@moonmail/pop3) — client with no I/O, RFC 1939 and RFC 2449: USER/PASS, APOP, SASL AUTH, STLS, CAPA, PIPELINING, STAT, LIST, UIDL, RETR and TOP dot-unstuffed with their octets kept.
• SMTP / LMTP (@moonmail/smtp) — client and server as state machines with no I/O, RFC 5321 and RFC 2033: PIPELINING groups, SIZE, 8BITMIME, BINARYMIME and CHUNKING, SMTPUTF8, DSN parameters, STARTTLS, SASL AUTH, and RFC 3463 enhanced status codes off any reply.
• Over a socket (@moonmail/net, native and wasm) — the SMTP, LMTP, IMAP and POP3 state machines on moonnet: implicit TLS, STARTTLS that a server must offer, or the clear; sending one message in one call.
• IMAP (@moonmail/imap) — IMAP4rev2 client with no I/O (RFC 9051) that also speaks to IMAP4rev1 servers: the response grammar with literals and response codes, pipelined UID commands, IDLE, CONDSTORE, LITERAL+, SASL-IR, and modified UTF-7 names toward rev1 servers. The same package carries a server: Server and Store answer IMAP4rev1 from mailboxes in memory, which is what a conformance run points a client at.
• DKIM (@moonmail/dkim) — RFC 6376 canonicalization (simple and relaxed), body hash, and RSA-SHA256 and Ed25519-SHA256 (RFC 8463) sign and verify, checked in both directions against dkimpy.
• JMAP (@moonmail/jmap) — RFC 8620's envelopes and every one of the twenty-seven methods RFC 8621 and the core document define: mailbox, thread, letter, snippet, identity, submission and vacation response, over the five standard shapes plus Email/copy, Email/import, Email/parse and Core/echo. The objects are written down once as moonmodel descriptions, which project to JSON Schema and are what @moonmail/jmap/validate checks a document against.

#Messages

let reply = @moonmail.Message::new(
  from=@moonmail.Mailbox::new("alice@example.com", name="Alice"),
  to=[@moonmail.Mailbox(@moonmail.Mailbox::new("bob@example.com"))],
  subject="Re: lunch",
  text="Noon works.\n",
)
let wire = reply.encode(utf8=true)
let again = @moonmail.Message::parse(wire[:])
assert_eq(again.subject(), Some("Re: lunch"))
assert_eq(again.text(), Some("Noon works.\n"))

#POP3

let pop = @pop3.Client::new()
ignore(pop.user("alice"))
ignore(pop.pass("secret"))
ignore(pop.retr(1))
let events = pop.feed(@utf8.encode("+OK 12 octets\r\nSubject: one\r\n\r\nbody\r\n.\r\n")[:])
assert_eq(events.length(), 1)

#SMTP / LMTP

let smtp = @smtp.Client::new()
smtp.ehlo("client.example")
let _ = smtp.mail("alice@example.com")
let _ = smtp.rcpt("bob@example.com")
let replies = smtp.feed(@utf8.encode("250 mx.example\r\n250 2.1.0 Ok\r\n250 2.1.5 Ok\r\n")[:])
assert_eq(replies.length(), 2)
for event in replies {
  match event {
    Reply(Rcpt(to), reply) if !reply.is_ok() => println("refused: " + to)
    _ => ()
  }
}

let server = @smtp.Server::new("mx.example", auth=["PLAIN"])
server.feed(@utf8.encode("EHLO client.example\r\n")[:])
let request = server.next()
assert_true(request is Some(Hello(_, extended=true)))
server.reply(250, "mx.example")
assert_eq(server.next_write().unwrap().length() > 0, true)

#JMAP

let request = @jmap.Request::new()
let boxes = request.mailbox_get("u-1")
let found = request.email_query("u-1", "mb-in", 25)
assert_eq(boxes, "c0")
assert_eq(found, "c1")
let answer = @jmap.Response::parse(
  "{\"methodResponses\":[[\"Email/query\",{\"ids\":[\"em-1\"]},\"c1\"]],\"sessionState\":\"s-2\"}",
)
assert_eq(@jmap.email_ids(answer, found), ["em-1"])

let request = @jmap.Request::new()
let _ = request.email_get(
  "u-1",
  ["em-1"],
  ["id", "subject", "bodyValues"],
  fetch_html_body_values=true,
  max_body_value_bytes=256,
)
let _ = request.email_import(
  "u-1",
  Map([
    (
      "one",
      @jmap.EmailImport::new(
        blob_id="B1",
        mailbox_ids=["mb-in"],
        keywords=["$seen"],
      ),
    ),
  ]),
)
let _ = request.search_snippet_get("u-1", ["em-1"], filter=@jmap.text_search("noon"))
assert_eq(@jmap.method_names().length(), 27)

assert_eq(@jmap.Kind::Email.methods().length(), 8)
assert_true(@jmap.has_property("Email", "subject"))
assert_false(@jmap.has_property("Email", "subjectLine"))

let answer = @jmap.Response::parse(
  "{\"methodResponses\":[[\"Email/get\",{\"list\":[{\"id\":\"em-1\",\"subject\":\"Lunch?\"}]},\"c0\"]],\"sessionState\":\"s-2\"}",
)
assert_true(@validate.valid("Email", @jmap.email_object(answer, "c0")))

let object = @jmap.email_from_message(
  raw[:],
  mailbox_ids=["mb-in"],
  keywords=["$seen"],
  received_at="2026-11-06T12:00:01Z",
)
assert_true(@validate.valid("Email", object))

#The writing desk, and the post office beside it

• JMAP — JSON over HTTPS, so the page fetches the server itself. Nothing to install, but only a server that speaks JMAP can be reached.
• Local office — the page hands the letter to 127.0.0.1, and a small server there opens the SMTP, IMAP or POP3 connection. Works with any provider; needs that server to be running.

flowchart LR
  page["writing desk<br/>(a page, no socket)"]
  desk["moonmail<br/>composes the MIME"]
  jmap["JMAP server<br/>HTTPS · no helper"]
  office["local post office<br/>127.0.0.1:12000"]
  smtp["SMTP · IMAP · POP3"]
  page --> desk
  desk -->|"jmap.request"| jmap
  desk -->|"compose"| office
  office -->|"@moonmail/net"| smtp

#Over a socket

let letter = @moonmail.Message::new(
  from=@moonmail.Mailbox::new("alice@example.com"),
  to=[@moonmail.Mailbox(@moonmail.Mailbox::new("bob@example.com"))],
  subject="Lunch",
  text="Noon works.\n",
)
let smtp = @net.Smtp::connect("smtp.example.com", Clear)
smtp.auth(@sasl.Plain::new("alice", "secret"))
let refused = smtp.send("alice@example.com", ["bob@example.com"], letter.encode())
assert_eq(refused.length(), 0)
smtp.quit()

#SASL

// SCRAM never sends the password, and refuses a server that cannot prove it
// holds the salted key. The nonce is fresh random printable ASCII each time.
let mechanism = @sasl.ScramSha256::new("alice", "secret", nonce="fyko+d2lbbFgONRv9qkxdawL")
assert_eq(mechanism.name(), "SCRAM-SHA-256")
let first = mechanism.start().unwrap()
assert_true(first.length() > 0)

#IMAP

let imap = @imap.Client::new()
let login = imap.login("alice", "secret")
let selected = imap.select("INBOX")
let fetch = imap.fetch("1:*", "(FLAGS BODY.PEEK[HEADER])", uid=true)
assert_eq([login, selected, fetch], [0, 1, 2])
let events = imap.feed(@utf8.encode("1 OK LOGIN completed\r\n")[:])
assert_eq(events.length(), 1)

#DKIM

let verdicts = @dkim.verify(raw[:], _ => None, now=0)
assert_eq(verdicts.length(), 0)

// `key` is a @dkim.Key from @x509.PrivateKey::pem; the lookup answers the TXT
// record of the selector, which verify asks for once per signature.
let domain_name = "sel._domainkey.example.com"
assert_eq(domain_name, "sel._domainkey.example.com")

#A server, for the other end of the wire

let store = @imap.Store::new()
let _ = store.deliver("INBOX", raw[:], date="06-Nov-2026 12:00:00 +0000")
let server = @imap.Server::new(
  store~,
  credentials=(user, password) => user == "tim" && password == "secret",
  clock=() => "06-Nov-2026 12:00:00 +0000",
)
server.feed(@utf8.encode("a1 LOGIN tim secret\r\n")[:])
assert_true(server.next_write() is Some(_))

#Conformance

#What it is not

#The gate

moon clean && moon fmt && moon check --target all --deny-warn \
  && moon build --target all && moon test --target all

#Licence