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

Create a countdown timer

POST/v1/template-timers

Create a countdown timer image: an animated GIF that shows the time left whenever the email is opened.

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

Nothing is stored: the URL carries the signed settings, so changing it breaks the image. Put it in an <img> of a template (the visual editor’s timer block does this for you).

Each open renders one frame per second for a minute, then the last frame stays; after end it shows zeros. Renders are shared for 5 seconds, so a broadcast opened by many recipients at once costs one render.

Body parameters

endstring (RFC 3339)required
When the countdown reaches zero. Limits: missing → 422 invalid_parameter "end is required"; not RFC 3339 → 400 validation_error
widthinteger
Image width in px, 200-600; the height follows. Limits: otherwise 422 invalid_parameter "w must be 200–600" Default 600.
digit_colorstringrequired
Digit colour, hex RRGGBB or RRGGBBAA (a leading # is allowed). Limits: otherwise 422 invalid_parameter "fg: colour must be RRGGBB or RRGGBBAA"
label_colorstringrequired
Label colour, same format. Limits: 422 invalid_parameter "lc: …"
backgroundstringrequired
Background colour, same format; alpha 00 (e.g. ffffff00) is transparent. Limits: 422 invalid_parameter "bg: …"
labelsstring[]
Exactly 4 labels under days, hours, minutes and seconds, each up to 12 characters, without |. "" hides one label; four empty labels hide the label row. Limits: 422 invalid_parameter "l must hold 4 labels separated by |" / "labels are limited to 12 characters" Default ["days", "hours", "minutes", "seconds"].

Errors

validation_errorHTTP 400
invalid JSON body (e.g. end not RFC 3339)
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
invalid_parameterHTTP 422
see the fields
POST/v1/template-timers
curl -X POST 'https://zapsmtp.xyz/v1/template-timers' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "end": "2026-11-28T23:59:59Z",
  "digit_color": "111827",
  "label_color": "6b7280",
  "background": "ffffff"
}'
Set ZAP_API_KEY in your environment.
Response 200 OK
{
  "object": "template_timer",
  "url": "https://zapsmtp.xyz/i/timer.gif?bg=ffffff&end=1795910399&fg=111827&l=days%7Chours%7Cminutes%7Cseconds&lc=6b7280&w=600&sig=Hk3x9vQm2LrT8aWc"
}