Jakarta Mail crosswalk
This crosswalk compares Mail API with Jakarta Mail
(Jakarta EE), formerly JavaMail.
Jakarta Mail provides an extensible MIME message object model and a pluggable
transport SPI (jakarta.mail.Transport). It is the foundation for Java email
handling and the underlying model used by Spring.
| Jakarta Mail concept | Mail API field | Mapping |
|---|---|---|
InternetAddress (From, To, Cc, Bcc, Reply-To) |
from, to, cc, bcc, replyTo |
Convert address and personal name to an EmailAddress. |
MimeMessage.getSubject() |
subject |
Direct correspondence. |
MimeBodyPart (text/plain, text/html) |
text, html |
Map text and HTML body parts to their respective fields. |
MimeBodyPart attachments |
attachments |
Base64-encode body content and preserve filename and MIME type. |
| Supplemental headers | headers |
Preserve headers not mapped to structured fields. |
Potential transport adapter
Section titled “Potential transport adapter”A Mail API transport extends jakarta.mail.Transport and registers as a
protocol provider (such as mailapi). Applications configure the session
property mail.transport.protocol=mailapi or call
session.getTransport("mailapi").
The adapter parses the composed MimeMessage, constructs an
OutboundMessageRequest, and submits it to POST /v1/messages over HTTP.
Because Jakarta Mail’s Transport.send() is synchronous and expects a void
return, the transport treats HTTP 200 and 202 as success and raises
MessagingException subtypes on HTTP error responses. It can send
Prefer: wait=N to request a bounded wait for submission completion.
Differences and limits
Section titled “Differences and limits”- Mail API
202indicates asynchronous acceptance, while200indicates completion within an applied wait. Neither confirms recipient delivery. - Inline MIME parts with
Content-IDheaders have no structured field in Mail APIv1. The transport requires an explicit policy (such as rejecting inline attachments) to prevent broken message rendering. MimeMessage.getSentDate()has no structuredv1field; the provider stamps the submission time.- Idempotency requires caller coordination: the transport should accept an
Idempotency-Keyvia message headers or session properties to make retries safe. - Exception mapping: HTTP
401should map toAuthenticationFailedException;403should map toSendFailedException(or anotherMessagingExceptionthat represents authorization failure), because the credentials were accepted but the submission was not authorized. Map422toSendFailedException. Because the transport itself serializes the HTTP request, a400indicates an adapter defect rather than a malformed caller message and should map to a generalMessagingException. Unexpected provider errors (500/503) also map toMessagingException.
