Developers

End-time API

Set a timer's end date and time per email, from your own system. It works the same way as Motion Mail's /tokens/datetime API. If you already use Motion Mail, change three things:

The API address: https://api.motionmailapp.com/tokens/datetime becomes https://countdowngif.com/tokens/datetime.
The API key and secret key: use the ones you were given for CountdownGIF.
The image address: https://s.mmgo.io/t/<code> becomes your CountdownGIF timer's image address, for example https://countdowngif.com/t/Ab3dE6gH9k, or your team's own image domain if it has one.

Your request, the response fields and the endDateTimeToken image parameter stay the same.

How it works

Your timer in CountdownGIF has an image address, such as https://countdowngif.com/t/Ab3dE6gH9k. It sets the look.
Your system sends an end date and time to POST /tokens/datetime and gets back a token.
Add ?endDateTimeToken=<token> to the image address in the email. That image now counts down to your end time.

Try it in two minutes

Replace the key, the secret and the timer address with yours, then run:

curl https://countdowngif.com/tokens/datetime \
  -u YOUR_API_KEY:YOUR_SECRET_KEY \
  -d datetime=2026-11-27T23:59:59

You get back JSON with "Success": true and a token in Data. Paste your image address with the token on the end into a browser:

https://countdowngif.com/t/YOUR_TIMER_TOKEN?endDateTimeToken=PASTE_DATA_HERE

You see a countdown to November 27, 11:59:59 PM in your account's time zone. Refresh and it shows the time left right now. A test like this sends nothing and changes nothing: the token only affects images that carry it.

The request

POST https://countdowngif.com/tokens/datetime

https://countdowngif.com/api/tokens/datetime works too.

Authentication: HTTP Basic. The username is your API key and the password is your secret key.

Body: one field, datetime. Send it form-encoded (application/x-www-form-urlencoded) or as JSON ({"datetime": "..."}).

Field	Required	Format
`datetime`	Yes	`yyyy-MM-ddTHH:mm:ss`, with an optional UTC offset

The end must be in the future and no more than 400 days ahead.

Time zone rule

No offset (2026-11-27T23:59:59): read in your account's time zone (Central Time unless it was changed). Daylight saving time is handled for you.
With an offset, the time is local time at that offset, as in ISO 8601: Z, +04:00, -0400 or a URL-encoded %2B0400. So 2026-11-27T10:00:00-0500 is 3:00 PM UTC.

In a form body a plain + turns into a space. Send %2B instead, or use -, Z or JSON. (A space where the plus was is still read correctly.)

The response

Success, HTTP 200:

{
  "DateTimeCreated": "2026-10-20T23:09:51.074Z",
  "OriginalValue": "2026-11-27T23:59:59",
  "Success": true,
  "Data": "AQARERERIiJDM4REVVVVVVVVawpt3y3rfsWLR1ICaHZ7duxG4Vo"
}

Field	Meaning
`DateTimeCreated`	When the request was handled (UTC, ISO 8601)
`OriginalValue`	The `datetime` value you sent
`Success`	`true`
`Data`	The token. It is already safe to put in a URL, so paste it as it is

Errors use this shape:

{
  "DateTimeCreated": "2026-10-20T23:09:51.831Z",
  "Message": "Invalid api and secret key combination.",
  "Param": null,
  "StatusCode": 401,
  "Type": "Authentication_Error"
}

HTTP	Type	Message	Param
401	Authentication_Error	Authorization has been denied for this request. (no credentials)	null
401	Authentication_Error	Invalid secret key format.	SecretKey
401	Authentication_Error	Invalid api and secret key combination. (wrong, unknown or revoked key)	null
400	Bad_Request	The datetime field is required.	datetime
400	Bad_Request	Invalid DateTime value. (wrong format or not a real date)	datetime
400	Bad_Request	The datetime must be in the future.	datetime
400	Bad_Request	The datetime must be no more than 400 days ahead.	datetime
429	Rate_Limit_Error	Too many requests	null

StatusCode is a number and always matches the HTTP status.

Rate limit: 120 requests per minute per API key. You normally need one request per send, not one per recipient: every recipient with the same end time can share one token.

The image address

https://countdowngif.com/t/<timer token>?endDateTimeToken=<Data>

<img src="https://countdowngif.com/t/Ab3dE6gH9k?endDateTimeToken=AQARERERIiJDM4REVVVVVVVVawpt3y3rfsWLR1ICaHZ7duxG4Vo"
     alt="Countdown timer" width="324" height="108" style="display:block;border:0" />

The token sets the end time. Everything else (style, days on or off, a start time) comes from the timer.
A token works on any timer in your account, and never on another account's timers.
Tokens do not expire. The end time is inside the token, and once it passes the timer shows zeros.
If the token is missing, damaged or from another account, the image still shows, counting down to the timer's own end time. An email never shows a broken image because of a bad token.
Daily timers can use a token too. The token's end replaces the 11:59:59 PM of the ?d= date.
If your team has its own image domain, such as https://timer.yourbrand.com, use it in place of https://countdowngif.com in the image address. The API address stays https://countdowngif.com/tokens/datetime.

The token is signed, so nobody can change its end time or use it on another account. It is not secret: anyone who can see the email can see it. Keep the API key and secret key on your server and never put them in an email.