Runs examples for real against your account. Test keys only; kept in this tab, never stored on our side. Get a key
ZapSMTP / Docs / Modules, images & timers

Upload an image

POST/v1/template-assets

Upload an image for use in templates, as a multipart file or by URL; returns its public URL.

Requires a full-access live key; test keys get 403 test_key_restricted.

PNG, JPEG, GIF or WebP, up to 5 MB and 40 megapixels; the file content decides the type, not its name. PNG and JPEG images wider than 1,200 px are scaled down to 1,200 px (twice a 600 px email); GIF (animations included) and WebP are kept as they are. width and height are those of the stored image.

The URL is public (anyone with it can load the image) and long-lived: use it in <img src> of any template. The name keeps letters, digits, spaces and . _ ( ) -, up to 200 characters.

Each account holds up to 2,000 images and 1 GB.

Headers

Content-Typestringrequired
multipart/form-data with the image in field file, or application/json with the body below.

Body parameters

urlstringrequired
JSON upload: an http(s) URL we download the image from (private and internal addresses are refused). Limits: unreachable, not HTTP 200 or not a URL → 422 invalid_parameter
namestring
JSON upload: the file name shown in the image library. Default the last segment of the URL.

Errors

restricted_api_keyHTTP 403
test_key_restrictedHTTP 403
test-mode keys can send test email and read, not change the account: use a live key
payload_too_largeHTTP 413
images are limited to 5 MB
invalid_imageHTTP 422
only PNG, JPEG, GIF and WebP images are accepted | image dimensions are too large | images are limited to 5 MB | the image could not be decoded
invalid_parameterHTTP 422
send the image as multipart field "file", or JSON {"url": "..."} | url must be an http(s) URL | fetching url returned HTTP <n> | could not fetch url: <reason> | the image at url is over 5 MB
quota_exceededHTTP 422
image library is full (2,000 images or 1 GB): delete unused images first
storage_unavailableHTTP 503
object storage is not configured
POST/v1/template-assets
curl -X POST 'https://zapsmtp.xyz/v1/template-assets' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com/brand/logo.png",
  "name": "logo.png"
}'
Set ZAP_API_KEY in your environment.
Response 201 Created
{
  "id": "5b0e3c1a-9d2f-4e7b-8a61-2f4c6d8e0a13",
  "name": "logo.png",
  "ext": "png",
  "content_type": "image/png",
  "size": 18342,
  "width": 480,
  "height": 120,
  "created_at": "2026-10-22T16:10:00Z",
  "object": "template_asset",
  "url": "https://zapsmtp.xyz/i/5b0e3c1a-9d2f-4e7b-8a61-2f4c6d8e0a13.png"
}