Arabic transactional email in production: a bidi-safe rendering guide
A practical way to keep Arabic copy, OTPs, references, links and punctuation readable across real inboxes without confusing layout with transport or sender reputation.
Arabic transactional email usually fails in small, costly ways. A verification code appears on the wrong side of a sentence. Parentheses seem reversed. An order reference picks up nearby punctuation. A support link breaks the reading flow. The Arabic itself may be perfectly translated, yet the message becomes harder to trust at the exact moment a customer is signing in, paying or checking an order.
This is a rendering problem, not an internationalised-address problem. The mailbox can remain user@example.com; the domain can remain ASCII; and the message body can still contain Arabic. SultanByte’s guides to Arabic IDNs and internationalised email and the Arabic domain email production checklist cover address identity and SMTPUTF8 capability. Here, the concern begins after your application has chosen a recipient: how to construct a message whose Arabic body remains legible in real email clients.
Keep four production concerns separate
Teams lose time when “Arabic email support” becomes one vague ticket. Split it into four lanes:
- Rendering: Does mixed Arabic and Latin content appear in the intended visual order? Control it with
dir,lang, isolation and client testing. - MIME: Can the receiver identify and decode each body representation? Control it with
multipart/alternative, a UTF-8 charset and correct transfer encoding. - OTP security: Is the code safe to issue, verify and expire? Enforce a short TTL, single use, attempt limits and no logging.
- Deliverability: Does the message reach the inbox as an authenticated, reputable sender? This depends on SPF, DKIM, DMARC, DNS and traffic separation.
A correct dir="rtl" does not authenticate a sender. DKIM does not repair misplaced punctuation. UTF-8 does not make an OTP secure. Treat each lane as an independent release gate.
Production pipeline for Arabic transactional email. Sources: W3C HTML direction, W3C inline bidi, RFC 2046, RFC 6532, OWASP MFA, Gmail sender guidance and Yahoo sender guidance. Credit: SultanByte editorial artwork.
Build direction into the markup
Arabic script runs right to left, while numbers and Latin-script text run left to right. The browser or mail client applies the Unicode Bidirectional Algorithm to arrange those runs for display. Neutral characters such as spaces and punctuation derive their direction from their context, which is why a code followed by a full stop can appear to jump. The W3C Arabic and Persian layout requirements explain the distinction between the stored character order and the positions chosen for display.
Set the base direction in HTML, rather than hoping alignment will imply it:
<html lang="ar" dir="rtl">
lang="ar" identifies the language. dir="rtl" establishes direction. They are not substitutes for one another. W3C guidance recommends putting the overall direction on the html element and using direction markup for blocks only when their base direction changes. It also advises against using CSS as the only source of directional meaning, because the information should survive when styling does not. See the W3C’s structural RTL markup guidance for the underlying model.
Inside an RTL message, tightly wrap every known LTR token: OTPs, order IDs, dates in Latin notation, prices using Latin currency codes, URLs, email addresses and product names. W3C’s inline bidi guidance recommends a dir attribute on the smallest element containing the opposite-direction phrase. That boundary isolates the token from nearby Arabic and punctuation.
Use dir="auto" only when you genuinely do not know the value’s direction, such as a customer-supplied display name. It chooses a base direction from the first strong character. It is useful, not infallible. A value beginning with digits or punctuation can produce an unexpected result, so known machine values should use an explicit direction.
Avoid solving normal content with bdo, embedding controls or ad hoc right-to-left marks. Directional override is for exceptional cases. Invisible controls are difficult to inspect, copy and maintain. Prefer visible markup where HTML allows it.
A compact production pattern
The pattern below uses email-friendly tables and inline styles, but direction remains semantic markup. The code is isolated as LTR, while the Arabic sentence owns the punctuation outside that span. Replace variables only after HTML escaping them.
<!doctype html>
<html lang="ar" dir="rtl">
<body style="margin:0;background:#f4f4f5;">
<table role="presentation" width="100%" cellspacing="0" cellpadding="0"
style="width:100%;background:#f4f4f5;">
<tr><td align="center" style="padding:24px 12px;">
<table role="presentation" width="600" cellspacing="0" cellpadding="0"
style="width:100%;max-width:600px;background:#fff;">
<tr><td dir="rtl" lang="ar"
style="padding:32px;text-align:right;font-family:Arial,Tahoma,sans-serif;
font-size:18px;line-height:1.8;color:#18181b;">
<p style="margin:0 0 16px;">مرحباً <span dir="auto">{{display_name}}</span>،</p>
<p style="margin:0 0 12px;">رمز التحقق الخاص بك هو:</p>
<p style="margin:0 0 16px;text-align:center;">
<span dir="ltr" lang="en"
style="display:inline-block;font-family:Arial,sans-serif;
font-size:32px;font-weight:700;letter-spacing:6px;">
{{otp}}
</span>
</p>
<p style="margin:0;">تنتهي صلاحية الرمز خلال {{expiry_minutes}} دقائق. لا تشاركه مع أي شخص.</p>
</td></tr>
</table>
</td></tr>
</table>
</body>
</html>
Keep the logical source order natural. Do not reverse Arabic strings, split a number into separate characters or generate a different stored order to “match” one screenshot. Rendering engines are supposed to determine visual order from the content and declared base direction.
Template values need contextual escaping before insertion. If customer content can contain HTML, bidi controls or untrusted links, sanitise it according to the field’s contract. Yahoo explicitly recommends filtering user-generated content before sending so an email system cannot be abused by spammers.
MIME is the message envelope, not the layout engine
Send a multipart/alternative message with a meaningful text/plain part followed by text/html, both declared as UTF-8. This is not merely an HTML fallback convention. MIME defines multipart/alternative as multiple representations of the same information, and RFC 2046 defines media types, charset parameters and canonical CRLF line breaks for text parts.
A simplified structure looks like this:
Content-Type: multipart/alternative; boundary="b1"
--b1
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
[Arabic plain-text version]
--b1
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
[HTML version]
--b1--
Let a maintained email library generate boundaries, transfer encoding, header folding and CRLF. Do not concatenate raw MIME by hand in application code. The plain-text part needs its own review because HTML isolation does not carry into plain text. Keep mixed tokens on simple lines, avoid decorative punctuation around OTPs and verify the output in clients that display the text alternative.
Arabic in a subject or display name is a header concern, separate from the HTML body. RFC 6532 permits direct UTF-8 in most header field values in the internationalised message format, while header field names remain ASCII. Your sending library and delivery path must generate standards-compliant headers. None of this changes the body’s need for dir and isolation.
An OTP that looks right can still be unsafe
Treat an emailed OTP as an authentication secret. According to the OWASP MFA guidance, OTP implementations should enforce a short lifetime, make each code single-use, limit attempts and invalidate the code after successful verification. Codes should not appear in logs or remain in long-term plaintext storage. A resend should issue a new value and replace the previous record.
Rendering has security consequences at the human layer. Keep the code as one isolated LTR run, use a readable size and avoid wrapping. The value shown in the subject, preheader and body should not conflict, so the safest pattern is to put the secret in the body only. Do not place the OTP in a clickable URL. State the expiry and tell the recipient not to share it, but never let those words substitute for server-side expiry and attempt controls.
Hashing a short numeric OTP helps prevent accidental exposure, but OWASP notes that its small keyspace means hashing does not provide password-like offline resistance. The primary controls remain short validity, strict verification limits and prompt invalidation.
Deliverability is a separate operational system
A perfectly rendered message is useless if it is rejected or routed to spam. Google’s email sender guidelines require SPF or DKIM for all senders to personal Gmail accounts, with SPF, DKIM and DMARC required for bulk senders. Google also calls for valid forward and reverse DNS, RFC-compliant formatting and a valid Message-ID.
Transactional traffic should have a stable identity and should not be mixed casually with promotions. Google recommends separating message types where multiple IPs are used, and Yahoo’s sender best practices recommend separating bulk or marketing mail from user mail, transactional messages and alerts by IP or DKIM domain. That limits the chance that promotional complaints damage password resets or payment receipts.
Monitor acceptance, deferrals, bounces and complaints by provider. Delivery is not proven by a successful API response from your email service. That response usually confirms submission, not inbox placement.
QA matrix for release
Use fixed fixtures that combine Arabic with Latin names, codes, punctuation and long values. Keep screenshots for visual regressions, but assert MIME and security behaviour in automated tests.
- Arabic HTML: End a sentence with
ABC-2048.The token should remain LTR, with the full stop belonging to the sentence. - Unknown name: Try Arabic, Latin and digit-first display names. The name should remain isolated without reordering the greeting.
- OTP: Test six and eight digits on a narrow viewport with large text. Digits should retain order, stay on one line and remain selectable.
- Punctuation: Put parentheses, a colon, a slash and
%beside Arabic. Each symbol should stay with the intended phrase in every target client. - MIME: Inspect the raw received message. Both alternatives should declare UTF-8, decode cleanly and sit inside a valid boundary.
- Plain text: Force text-only display, then copy and paste the result. Meaning and code order should survive without HTML.
- Headers: Send an Arabic subject and sender display name. Raw headers should be valid, readable and include a
Message-ID. - Security: Expire, reuse and resend codes, then exceed the attempt limit. Expired and old codes should fail; success should invalidate the code; attempts should be throttled.
- Deliverability: Use seed accounts at major mailbox providers. Record authentication, acceptance, deferrals and spam placement.
- Accessibility: Use a screen reader with images disabled. Reading order should remain coherent, and essential content should stay available as text.
Ship only after testing the final message received through the production delivery path. A browser preview validates neither MIME assembly nor mailbox-client behaviour. Direction, decoding, authentication and OTP verification each need their own evidence.
Arabic transactional email becomes manageable once direction is treated as data rather than decoration. Declare the RTL base, isolate every known LTR token, package equivalent UTF-8 alternatives correctly, enforce OTP controls on the server and operate a properly authenticated sending stream. That separation turns a fragile template into a system you can test and maintain.
Cover and infographic credit: SultanByte.
