Charchy Senddocs

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.

WayBest forHow
Hosted image (recommended)Logos, headers, product photos<img src="https://files.charchy.krd/…"> in your html
Inline imageA logo that must show even when the reader blocks remote imagesAn attachment with a content_id, and <img src="cid:…"> in your html
AttachmentInvoices, receipts, ticketsattachments: [{ 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-data in a field named file.
  • 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"
    }
  ]
}
FieldNotes
filenameRequired. What the reader sees: a plain file name, no folders, up to 255 characters.
contentRequired. The file, base64-encoded. Line breaks in it are fine.
content_typeRequired. e.g. application/pdf, image/png.
content_idOnly 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, .vbs and similar) and empty files are refused with invalid_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",
}

On this page