HTML and plain text
POST /v1/send takes two body fields, html and text. At least one is
required, and what you supply decides the MIME structure of the message that
goes out.
| You send | The message is |
|---|---|
text only |
a single text/plain part |
html only |
a single text/html part |
| both | multipart/alternative, text first |
| neither | rejected with 400 Empty body |
Adding attachments wraps whichever of those applies inside a
multipart/mixed. See Attachments.
Send both
{
"from": "receipts@yourcompany.com",
"to": ["alice@example.com"],
"subject": "Order confirmed",
"html": "<h1>Thanks!</h1><p>Order 12345 is confirmed.</p>",
"text": "Thanks! Order 12345 is confirmed."
}
Sending both is the right default, for three reasons that have nothing to do with taste:
- Some clients will not render HTML, by configuration or by policy. They show the text part, or nothing.
- Spam filters read the absence of a text part as a weak signal against
you. A
multipart/alternativewith a genuine text alternative looks like ordinary correspondence. - Screen readers and previews use the text part, so the first line of your plain text is often the preview line a recipient actually sees.
What Lockally does not do
There is no automatic text part. Send html alone and the message goes out
as a single HTML part. Lockally will not generate the text alternative for you,
and nothing warns you that it is missing.
There is no HTML processing at all. Your markup is placed in the message as given. Nothing is minified, inlined, sanitised, or rewritten, and no links are rewritten for tracking (see Message IDs and tracking). If you need CSS inlined for older clients, inline it before you call the API.
This is a deliberate position rather than an omission, but it does mean the deliverability of your HTML is entirely your own work.
Character encoding
Both parts are sent as UTF-8, and the Subject is RFC 2047 encoded
automatically when it is not plain ASCII. Accents, non-Latin scripts and emoji
in the subject all work without you encoding anything by hand.
Size
The body counts toward the request ceiling along with everything else. A very
large HTML body is unusual but not impossible, particularly one with embedded
data: images, which inflate quickly. See Message size
limits.