Plain Text vs HTML Email: When to Send Both (and Use the Text Field)

Every send API offers an html field and a text field, and most developers fill in only the first. That works until a customer reads the message on a watch, a screen reader, a terminal, or a corporate gateway that strips HTML, or until a spam filter notices the missing text part. This guide explains what each format is for, when to send both (almost always), and how to write a text version that is not an afterthought.

Quick answer

Send both. Put the html in the html field and a hand-written or carefully generated plain text version in the text field, so the message goes out as a multipart/alternative email and each client picks the part it can show. Send text only for security-sensitive or system messages where formatting adds nothing. Send HTML only never; a missing text part costs you readers and points with spam filters.

What plain text is good for

• Security messages: codes, password changes, new-device alerts. Plain text is harder to spoof convincingly and loads instantly.
• Alerts and monitoring mail read on phones and watches.
• Personal-feeling messages, such as a founder note or a support reply, where HTML styling reads as marketing.
• Accessibility: screen readers handle text with no surprises.
• Clients that show only text: some corporate gateways, terminal clients, older devices, and "show as plain text" settings that privacy-minded users enable.

What HTML is good for

• Anything with structure: an itemised order, a table of figures, a list of comments.
• A clear call-to-action button that works without copying a URL.
• Brand recognition through a logo and consistent colours.
• Images that carry information, such as a product photo in a shipping notice, always with alt text.

Why both parts matter for deliverability

Spam filters compare the text and HTML parts of a message. A message with only HTML, or with a text part that says "view this email in your browser", is a pattern common in bulk mail and is scored accordingly. A text part that says the same thing as the HTML, in the same order, is a pattern common in legitimate transactional mail. It also means links and content are consistent across parts, which filters check. In short, filling the text field is one of the cheapest deliverability improvements available.

Writing a good text part

1. Start with the same first sentence as the HTML. This is what previews and notifications show.
2. Use line breaks and blank lines for structure. Wrap lines at around 70 characters so old clients do not produce jagged wrapping.
3. Replace buttons with the full URL on its own line. Do not shorten URLs; shortened links are a spam signal and hide the destination.
4. Replace tables with aligned lines: "1 x Trail Jacket (M) ..... USD 89.00".
5. Keep the footer: company name, address, and how to get help, in text.
6. Do not generate it by stripping tags from the HTML with a regex; the result has no structure. Either write it by hand in the template or use a converter that understands headings, lists and links.

The send request with both fields

curl -X POST https://api.oqumail.com/api/v1/emails \
  -H "Authorization: Bearer $OQUMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"orders@yourdomain.com","to":"jane@example.com","subject":"Order #10482 confirmed","html":"<p>Hi Jane, your order <strong>#10482</strong> is confirmed.</p><table><tr><td>1 x Trail Jacket (M)</td><td>USD 89.00</td></tr></table><p><a href=\"https://app.yourdomain.com/orders/10482\">View order</a></p>","text":"Hi Jane, your order #10482 is confirmed.\n\n1 x Trail Jacket (M) ..... USD 89.00\n\nView order: https://app.yourdomain.com/orders/10482\n\nAcme Ltd, 1 Example Street, Nairobi"}'

Where OquMail fits

The send API accepts html and text in the same request and builds the multipart message for you, so supporting both costs one extra field. Messages go out from your verified domain with DKIM, and each one is recorded in the delivery log with the SMTP response from the receiving server, which is how you confirm a text-only recipient's gateway accepted the message. The same free plan gives you mailboxes on the domain, so replies to either kind of email reach a person.

Common questions

Does a text-only email look unprofessional?

Not for the categories it suits. Password and security emails from the largest platforms are plain or nearly plain. Consistency and clarity matter more than decoration.

What happens if I send only the text field?

The message goes out as text/plain and every client shows it as written. Links are clickable in nearly all modern clients. This is a perfectly good choice for alerts and codes.

How do I check what the text part looks like?

In Gmail open the message menu and choose "Show original"; the raw source shows both parts. Many clients also have a "view as plain text" option.