Repository navigation
Releases
v0.6.0
Minor Changes
-
5a166c9: Bring address parsing to RFC parity with the Go SDK's
raven/mailparser, fix
the places where the Go implementation was wrong, and export the parser.MessageandClientnow parse and normalize every address with the full
RFC 5322 mailbox grammar:- Internationalized domains are converted to their Punycode (A-label) form and
every domain is lowercased, souser@例え.jpbecomesuser@xn--r8jz45g.jp
andUser@Example.COMbecomesUser@example.com. A non-ASCII domain no
longer forcesSMTPUTF8, because the envelope is ASCII again. - RFC 2047 encoded-words in display names are decoded (
=?UTF-8?B?...?=), so a
display name round-trips instead of being stored and re-emitted verbatim. - Quoted local parts are unquoted in the parsed model and re-quoted only when
they cannot be written as a dot-string, so"john.doe"@example.comis the
same mailbox asjohn.doe@example.com(RFC 5321 section 4.1.2). - Obsolete syntax (
user . name@example.com, CFWS around dots) is accepted and
normalized, and folded header values are accepted as RFC 5322 permits.
New public API:
parseAddressandparseAddressListreturn aMailboxAddress
(localPart,domain,displayName) that is normalized exactly as the SDK
normalizes envelope and header addresses, so invalid input can be rejected
before aMessageis built and the wire form can be inspected up front.
parseAddressListexpands groups and is the entry point for a header such as
ToorCc. The formatting helpers stay internal.Address validation is now strict where the address may become an envelope
recipient: the RFC 5321 length limits are enforced, every domain label must be a
valid DNS label (user@a_b.comanduser@-x.comare rejected), the local part
may not contain control characters, a domain literal must be a real IPv4, IPv6,
or general address literal, and encoded display names may not contain control
characters. Rejections raise the newAddressErrorclass with a stable
addressErrorKind, so callers can branch on the failure instead of matching
message text. AMessage.build()failure keeps each address error's kind
inside theAggregateError.Behavior worth knowing about:
- An RFC 2047 display name that decodes to CRLF or another control character is
rejected rather than emitted into a header. - Backslashes in quoted display names are escaped, so parse/format/parse
preserves the name. - A domain that normalizes to an empty label (
user@例え.\u200b.jp) is
rejected, as is an address literal that is not a real IPv4, IPv6, or general
address literal. - Encoded-words using a character set the platform understands (
windows-1252,
iso-8859-15) are decoded, andiso-8859-1is read as its windows-1252
superset, which is what senders mean. - Display-name dots are preserved (
John Q. Public, notJohn Q Public). - A trailing comment is not promoted to a display name: RFC 5322 makes
(Comment)CFWS, souser@example.com (Comment)has no display name, and
Name <user@example.com> (Comment)keepsName.
parseEmailfrom@mxraven/mail/mimenow reports the same normalized,
RFC 2047-decoded addresses, and decodes each display name exactly once. A
display name is only taken from the RFC 5322 phrase, so a legacy trailing
comment such asbob@example.com (Bob)no longer appears as a name. Raw
8-bit header bytes are reinterpreted as UTF-8 before the address header is
parsed, which fixes mojibake in non-encoded international display names. Address
headers are parsed as a real RFC 5322 list, so groups are expanded
(Friends: a@b.example, c@d.example;yields both members) and an empty group
such asundisclosed-recipients:;yields none. The obsolete leading commas of
obs-addr-listare accepted, while empty list elements and trailing commas are
rejected rather than silently dropped; a malformed header is still salvaged
entry by entry. - Internationalized domains are converted to their Punycode (A-label) form and
v0.5.0
Minor Changes
- 7855ec9: Expose the mxRaven message reference on notification and status payloads.
InboundEmail,DeliveryStatus,StorageStatus, and the notifyAttemptEvent
now carrymessage_ref(messageRefonAttemptEvent), the value a submission
reply reports asmessage_ref=. It is the only field in those payloads that a
caller already holds before the event arrives, so it joins an event stream back
to the send that produced it, including every recipient a single send fanned
out to.
v0.4.1
Patch Changes
- Use the published production hosts in examples and TSDoc: SMTP submission at
smtp.mxraven.emailon port 587 (STARTTLS; implicit TLS on 465 is not
published), recipient feedback at thehttps://api.mxraven.combase URL (the
client appends/v1/feedback/...), and the client notification stream at
wss://notifications.mxraven.com.
v0.4.0
Minor Changes
- 4f7e873: Add RFC 8689
REQUIRETLSsupport toClient.sendandClient.sendRawthrough
SendOptions.requireTls, matching the Go SDK'sMessage.RequireTLSand
Envelope.RequireTLS. The submission server must advertiseREQUIRETLSor the
send fails with anSMTPError(550 5.7.30). A requestedDELIVERBYdeadline on
a server that does not advertise it now throws the exported
DeliveryByUnsupportedError, giving callers the same stable programmatic
identity as the Go SDK'sErrDeliveryByUnsupported.
v0.2.4
Patch Changes
- 9c74627: Fix BDAT transactions so the final server reply populates the public result.
Automatic BDAT sends (composed messages larger than 1 MiB) and chunked BDAT
sends previously returnedcode: 0, an emptymessage, and an empty
messageRefbecause the final reply was validated but never recorded. - 9c74627: Expose envelope extension parameters.
SendOptionsgainsdeliveryBy
(RFC 2852),dsnRetandenvid(RFC 3461), andextensionParamsfor
additionalMAIL FROMparameters.Envelope.tonow accepts
EnvelopeRecipientobjects with per-recipient DSNnotifyandorcpt
values alongside plain addresses.
v0.2.3
Patch Changes
- 4f00a07: Fix submission of messages with non-ASCII or over-long text lines. Text parts
with a line longer than the RFC 5322 limit (998 characters) are now encoded
with quoted-printable, so the serialized message never exceeds the SMTP line
limit enforced by submission servers. Non-ASCII bodies with shorter lines keep
Content-Transfer-Encoding: 8bitand now declareBODY=8BITMIMEon
MAIL FROM, which servers such as raven require before accepting 8-bit
DATA. Previously both cases were rejected with
451 4.3.0 unable to spool message body.
v0.2.2
Patch Changes
- 9b1f335: Add a template renderer seam:
Message.render(renderer, input)accepts any
TemplateRendererand runs it insideClient.send. The exported
TemplateRendererandRenderedTemplatetypes require only HTML (text and
subject are optional), so template engines can live in separate plugin packages.
Rendered HTML replaces an explicit.html()body, rendered text replaces an
explicit.text()body when present, and an explicit.subject()wins. Text
and HTML together are sent asmultipart/alternative.
v0.2.1
Patch Changes
- 928adc6: Add
@mxraven/mail/mimefor inbound message parsing:parseEmaildecodes raw
RFC 5322 bytes into headers, addresses, text and HTML bodies, and attachments,
andfetchAndParseRawEmaildownloads a webhookraw_emailreference and parses
it in one call.multipart/mixed,multipart/alternative, and
multipart/relatedare traversed,base64andquoted-printabletransfer
encodings, RFC 2047 encoded words, and RFC 2231 parameters are decoded, with
UTF-8 and Latin-1 fallbacks for unknown charsets.message/rfc822parts are
surfaced as attachments. - 928adc6: Add the exported
MediaTypetype and use it forAttachment.contentType.
Common media types now autocomplete in editors while any othertype/subtype
string is still accepted, because the MIME registry is open. - 928adc6: Add
WebhookHandlerto@mxraven/mail/webhook. It verifies, decodes, and
dispatches mxRaven webhook events to typed listeners with
on(eventType.inboundEmail, ...).handleaccepts either a Fetch API
Requestor framework request primitives (method,url,headers,body),
so Express/Fastify/other adapters can call it without rebuilding a request.
Protocol failures are reported as typed statuses
(400/401/413/500) instead of thrown errors, listeners run in
registration order, and the delivery is only acknowledged after every listener
resolves so failures trigger an mxRaven retry. New error classes
WebhookError,WebhookRequestError, andPayloadTooLargeErrorare exported
alongside the existingInvalidSignatureError.
@mxraven/mail@0.2.0
Minor Changes
- 1983725: Parse full RFC 5322 mailboxes in the address parser, including comments and
folding whitespace (CFWS), quoted strings, quoted local parts, domain
literals, and obsolete phrase dots. A trailing comment after a bareaddr-spec
is used as the display name, and bare line feeds are rejected. - 1eff167: Add the
@mxraven/mail/feedbackentry point: aClientfor tenant spam/ham
training over HTTP Basic auth (learn,learnSpam,learnHam), RFC 8058
one-click unsubscribes, theLearningResultandDispositiontypes, and
FeedbackErrorwith aretryableproperty. - 1eff167: Add the initial message-composition API: the chainable
Messagebuilder
(plain text, HTML,multipart/alternative, andmultipart/mixedattachments),
theSMTPErrorclass, and the submissionResult/RecipientResulttypes. - 1eff167: Add the public SMTP submission
ClientwithsendandsendRaw, the
ClientOptionsandSendOptionstypes, andSMTPTransactionErrorfor
submissions where every recipient was rejected. - 1eff167: Add the
@mxraven/mail/webhookentry point: theVerifierfor HMAC-SHA256
signature verification with key rotation and timestamp tolerance,decodefor
DELIVER_WEBHOOKandNOTIFY_WEBHOOKpayloads, the webhook payload types, and
fetchRawEmailfor downloading the referenced raw message.