CountdownMail API

The CountdownMail API provides the means to manage countdown timers.

API Conventions

  • /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.

API Endpoint


 https://countdownmail.com/api
    

Authentication

  • 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.

Using Postman

If you use Postman you can click the following button to import the CountdownMail API as a collection:

Run in Postman

Using cURL

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"

Errors

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.

CodeStatus NameDescriptionSuggested Action
400Bad RequestThere is a problem with your request.Check your request follows the API documentation and uses correct syntax.
401UnauthorizedYou don’t have the needed authorization to make the request.Make sure you are using a valid API key.
404Not FoundThe server couldn’t find the requested file.Change your request URL to match a valid API endpoint.
405Method Not AllowedThe resource does not have the specified method.Change the method to follow the documentation for the resource.
500Internal Server ErrorSomething went wrong on our end.Try the request again later. If the error does not resolve, contact support.
503Service UnavailableWe are experiencing higher than normal levels of traffic.Try the request again.


Example Error (HTTP status code: 401)

{
    "status": "error",
    "message": "Unauthorized"
}


Countdown Timer Create

POST /create

These are the valid request options for Create a countdown timer:

FieldTypeDescriptionRequired  Notes
skin_idintegerSkin idyesValid values in range 1 - 20
namestringName of the countdown timeryesMaximum length - 100 bytes. Example: Big Sale!
time_endstringDatetime in format of YYYY-MM-DD HH:MM:SS.yesExample: 2021-03-24 20:00:00
time_zonestringStandard timezone identification string.yesExample: America/New_York. See all available time_zone values
font_familystringFont family namenoExample: Roboto-Bold. See all available font_family values
label_font_familystringLabel font family namenoExample: Roboto-Bold. See all available font_family values
color_primarystringHex color codenoExample: 9c0000
color_textstringHex color codenoExample: cc0000
color_bgstringHex color codenoExample: FFFFFF
font_sizeintegerFont size noValid values in range 14 - 73
label_font_sizeintegerLabel font Size noValid values in range 0 - 50
dayintegerWhether or not to use the days. noValid values in range 0 - 1
langstringISO 2 Letter Language CodesnoValid 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'
transparentintegerBackground Type: 0 = Solid, 1 = TransparentnoValid values are: 0, 1
expired_mes_onintegerExpiry MessagenoValid values are: 0, 1
expired_messtringExpiry MessagenoMaximum length - 100 bytes. Example: This offer has expired
labelsintegerCustom labels: 0 = off, 1 = onnoValid values are: 0, 1
daysstringCustom label for daysnoMaximum length - 15 bytes. Example: days
hoursstringCustom label for hoursnoMaximum length - 15 bytes. Example: hours
minutesstringCustom label for minutesnoMaximum length - 15 bytes. Example: minutes
secondsstringCustom label for secondsnoMaximum length - 15 bytes. Example: seconds
advanced_paramsobjectAdvanced ParamsnoExample:
{
    "separator_color"  : "4275BC",
    "separator_size" : 1.3,
    "separator_style" : 6,
    "labels_color" : "A3A3A3"
}

Examples

Request: POST /create

{
    "skin_id":3,
    "name":"Big Sale!",
    "time_end":"2024-07-17 03:37:50",
    "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"
}

Countdown Timer Update

POST /update/{code}

URI Parameters
{code}(required)  

Countdown Timer code

Example: 1j

Examples

Request: POST /update/1j

{
    "skin_id":3,
    "name":"Big Sale!",
    "time_end":"2024-07-16 20:25:32",
    "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"
}

Countdown Timer Duplicate

POST /duplicate/{code}

URI Parameters
{code}(required)  

Countdown Timer code

Example: 1j

Countdown Timer Deactivate

GET /deactivate/{code}

URI Parameters
{code}(required)  

Countdown Timer code

Example: 1j

Countdown Timer Activate

GET /activate/{code}

URI Parameters
{code}(required)  

Countdown Timer code

Example: 1j