The CountdownMail API provides the means to manage countdown timers.
/something is equivalent to /something/.
URL paths, URL query parameter names, and JSON field names are case sensitive.
URL paths use lower case, with dashes separating words.
Query parameters and JSON fields use lower case, with underscores separating words.
The HTTP status indicates whether an operation failed or succeeded, with extra information included in the HTTP response body.
All APIs return standard error code formats.
Unexpected query parameters are ignored.
Unexpected JSON fields in the request body are ignored.
The JSON number type is bounded to a signed 32-bit integer.
https://countdownmail.com/api
To authenticate with the APIs, specify the "Authorization" header with each request. The value of the Authorization header must be a valid API key or basic auth with the API key as username and an empty password. Get a CountdownMail API key.
For examples of supplying the Authorization header, refer to the cURL example below or any of the individual API request examples.
If you use Postman you can click the following button to import the CountdownMail API as a collection:
If you are using cURL to call the API, you must include the resource URI in quotes when you pass in multiple query parameters separated by an &
.
For example:
curl -v \
-H "Content-Type: application/json" \
-H "Authorization: wEw476d2e5b1d2bad079bf5bbf5b1d22" \
-X GET "https://countdownmail.com/api/deactivate/1g"
When you make an API call you may receive an error message in response. Either there is something wrong with your request or something went wrong on our end. Errors respond with an error code and JSON that contains a more precise message.
Code | Status Name | Description | Suggested Action |
---|---|---|---|
400 | Bad Request | There is a problem with your request. | Check your request follows the API documentation and uses correct syntax. |
401 | Unauthorized | You don’t have the needed authorization to make the request. | Make sure you are using a valid API key. |
404 | Not Found | The server couldn’t find the requested file. | Change your request URL to match a valid API endpoint. |
405 | Method Not Allowed | The resource does not have the specified method. | Change the method to follow the documentation for the resource. |
500 | Internal Server Error | Something went wrong on our end. | Try the request again later. If the error does not resolve, contact support. |
503 | Service Unavailable | We are experiencing higher than normal levels of traffic. | Try the request again. |
(HTTP status code: 401)
{
"status": "error",
"message": "Unauthorized"
}
POST /create
Field | Type | Description | Required | Notes |
---|---|---|---|---|
skin_id | integer | Skin id | yes | Valid values in range 1 - 20 |
name | string | Name of the countdown timer | yes | Maximum length - 100 bytes. Example: Big Sale! |
time_end | string | Datetime in format of YYYY-MM-DD HH:MM:SS. | yes | Example: 2021-03-24 20:00:00 |
time_zone | string | Standard timezone identification string. | yes | Example: America/New_York . See all available time_zone values |
font_family | string | Font family name | no | Example: Roboto-Bold . See all available font_family values |
label_font_family | string | Label font family name | no | Example: Roboto-Bold . See all available font_family values |
color_primary | string | Hex color code | no | Example: 9c0000 |
color_text | string | Hex color code | no | Example: cc0000 |
color_bg | string | Hex color code | no | Example: FFFFFF |
font_size | integer | Font size | no | Valid values in range 14 - 73 |
label_font_size | integer | Label font Size | no | Valid values in range 0 - 50 |
day | integer | Whether or not to use the days. | no | Valid values in range 0 - 1 |
lang | string | ISO 2 Letter Language Codes | no | Valid values are: 'ar', 'bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'fa', 'fi', 'fr', 'he', 'hi', 'hu', 'it', 'ja', 'ko', 'lt', 'nl', 'no', 'pl', 'pt', 'ro', 'ru', 'sk', 'sv', 'th', 'tr', 'uk', 'vi', 'zh' |
transparent | integer | Background Type: 0 = Solid, 1 = Transparent | no | Valid values are: 0, 1 |
expired_mes_on | integer | Expiry Message | no | Valid values are: 0, 1 |
expired_mes | string | Expiry Message | no | Maximum length - 100 bytes. Example: This offer has expired |
labels | integer | Custom labels: 0 = off, 1 = on | no | Valid values are: 0, 1 |
days | string | Custom label for days | no | Maximum length - 15 bytes. Example: days |
hours | string | Custom label for hours | no | Maximum length - 15 bytes. Example: hours |
minutes | string | Custom label for minutes | no | Maximum length - 15 bytes. Example: minutes |
seconds | string | Custom label for seconds | no | Maximum length - 15 bytes. Example: seconds |
advanced_params | object | Advanced Params | no | Example:
|
Request: POST /create
{
"skin_id":3,
"name":"Big Sale!",
"time_end":"2024-10-13 16:20:42",
"time_zone":"America\/Los_Angeles",
"font_family":"Roboto-Bold",
"color_primary":"FF3A43",
"color_text":"FFFFFF",
"color_bg":"000000",
"transparent":"0",
"lang_local":"0",
"font_size":"38",
"day":"1",
"lang":"en",
"expired_mes_on":"1",
"expired_mes":"This offer has expired",
"labels":"1",
"days":"days",
"hours":"hours",
"minutes":"minutes",
"seconds":"seconds"
}
Response: (HTTP status code: 200)
{
"status": "success",
"message": {
"code": "td",
"src": "http://i.countdownmail.com/td.gif"
}
POST /update/{code}
{code} | (required) Countdown Timer code Example:1j |
Request: POST /update/1j
{
"skin_id":3,
"name":"Big Sale!",
"time_end":"2024-10-14 03:13:08",
"time_zone":"America\/Los_Angeles",
"font_family":"Roboto-Bold",
"color_primary":"FF3A43",
"color_text":"FFFFFF",
"color_bg":"000000",
"transparent":"0",
"lang_local":"0",
"font_size":"38",
"day":"1",
"lang":"en",
"expired_mes_on":"1",
"expired_mes":"This offer has expired",
"labels":"1",
"days":"days",
"hours":"hours",
"minutes":"minutes",
"seconds":"seconds"
}
Response: (HTTP status code: 200)
{
"status": "success",
"message": {
"code": "td",
"src": "http://i.countdownmail.com/td.gif"
}
POST /duplicate/{code}
{code} | (required) Countdown Timer code Example:1j |
GET /deactivate/{code}
{code} | (required) Countdown Timer code Example:1j |
GET /activate/{code}
{code} | (required) Countdown Timer code Example:1j |