Logos, images and attachments
Three ways to put a logo, an image or a file in an email — hosted images, inline images and attachments — and when to use each.
| Way | Best for | How |
|---|---|---|
| Hosted image (recommended) | Logos, headers, product photos | <img src="https://files.charchy.krd/…"> in your html |
| Inline image | A logo that must show even when the reader blocks remote images | An attachment with a content_id, and <img src="cid:…"> in your html |
| Attachment | Invoices, receipts, tickets | attachments: [{ filename, content, content_type }] |
Hosted images
A link to a file on the web: the email stays small, delivers better and loads faster. Use this for logos. Upload once — on Developers → Images in the dashboard, or with the API (a full key) — and use the URL in every email:
import { readFile } from "node:fs/promises"
import { CharchySend } from "@charchy/send"
const send = new CharchySend() // reads CHARCHY_SEND_KEY
const { data, error } = await send.images.upload(await readFile("logo.png"), { filename: "logo.png" }){
"id": "img_4t8w2k6m1q9v3n7p5r0s2x8c",
"url": "https://files.charchy.krd/i/4t8w2k6m1q9v3n7p5r0s2x8c/logo.png",
"content_type": "image/png",
"size": 18342
}<img src="https://files.charchy.krd/i/4t8w2k6m1q9v3n7p5r0s2x8c/logo.png" alt="Darin Game" width="120" height="40">- PNG, JPEG, GIF or WebP, up to 2 MB each, 200 per workspace. The
type is judged by the file's content, not its name: an SVG, or a file that
only calls itself
image/png, is refused. (No SVG: Gmail and Outlook don't show it.) - Send the file as
multipart/form-datain a field namedfile. - Over 2 MB answers
413 payload_too_large; not an image, or a 201st image,400 validation_error. - The URL is public and never changes. Images are never deleted by age — they live in emails people open months later.
- Delete an image on the Images page (API uploads are listed there too) to make room once you have 200. Its URL stops working at once, so sent emails show a broken image. Deleting your workspace deletes them all.
- Any other
https://image URL works too.
Always set alt, width and height: many readers see the email before
images load, or never load them.
Inline images
An inline image travels inside the email, so it shows even when remote images
are blocked — but its size is added to every email. Attach it with a
content_id and point an <img> at cid: plus that id:
{
"from": "Darin Game <orders@daringaming.com>",
"to": ["customer@example.com"],
"subject": "Your order #4821",
"html": "<img src=\"cid:logo\" alt=\"Darin Game\" width=\"120\" height=\"40\"><p>Thanks for your order!</p>",
"attachments": [
{
"filename": "logo.png",
"content": "iVBORw0KGgoAAAANSUhEUgAA…",
"content_type": "image/png",
"content_id": "logo"
}
]
}An inline image counts toward the attachment limits below.
Attachments
{
"attachments": [
{
"filename": "invoice-4821.pdf",
"content": "JVBERi0xLjcKJeLjz9MK…",
"content_type": "application/pdf"
}
]
}| Field | Notes |
|---|---|
filename | Required. What the reader sees: a plain file name, no folders, up to 255 characters. |
content | Required. The file, base64-encoded. Line breaks in it are fine. |
content_type | Required. e.g. application/pdf, image/png. |
content_id | Only for inline images: 1–100 letters, digits, ., _, @ or -, different on each file. |
- Up to 3 files, 3 MB together (before base64). A PDF invoice is usually 50–500 KB; bigger files belong behind a download link.
- Base64 adds about a third, so keep the whole request under the 5 MB body limit.
- Executable and script types (
.exe,.bat,.js,.vbsand similar) and empty files are refused withinvalid_attachment. - No attachments in a batch.
- Files are deleted from our storage once the email is sent; the log keeps only their names.
import { readFile } from "node:fs/promises"
const invoice = await readFile("invoice-4821.pdf")
const attachment = {
filename: "invoice-4821.pdf",
content: invoice.toString("base64"),
content_type: "application/pdf",
}