CountdownMail API

Quickstart

This section will get you ready to use the CountdownMail API and show you how to make your first API request.

1. Get your API key:
   • Log in to your CountdownMail account.
   • Go to Profile » API.
   • Copy your API key.
2. Make your first API request:
   • We’ll use the “Create a Timer” endpoint as an example.
   • Use a tool like cURL or Postman to send a POST request to https://countdownmail.com/api/create.
   • Add your API key in the Authorization header.
   • Include the required timer details in the request body (in JSON format).

Here’s an example using cURL:

curl -v \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-X POST "https://countdownmail.com/api/create" \
-d '{
    "skin_id": 1,
    "name": "Big Sale!",
    "time_end": "2025-04-21 20:00:00",
    "time_zone": "America/Los_Angeles",
    "font_family": "Roboto-Bold",
    "color_primary": "FF3A43",
    "color_text": "FFFFFF",
    "color_bg": "000000"
}'
                                    

• Replace YOUR_API_KEY with your actual API key.
• If everything works, you’ll get a response like this:

{
    "status": "success",
    "message": {
        "id": 1057,
        "code": "td",
        "src": "http://i.countdownmail.com/td.gif"
    }
}
                                    

This response includes a timer code (e.g., "td") and a URL for the timer image.

Authentication

To use the CountdownMail API, you need to authenticate every request with your API key. Here’s how:

• Add an Authorization header to your request. The value is your API key.
• Alternatively, use basic authentication: set your API key as the username and leave the password empty.

Example with Authorization Header (cURL):

curl -v \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-X GET "https://countdownmail.com/api/some_endpoint"
                                    

• Replace YOUR_API_KEY with your actual API key.
• Always include authentication, or you’ll get a 401 Unauthorized error.

Using Postman

If you use Postman makes it easy to test API requests. To use it with CountdownMail:

• Click it to import the CountdownMail API collection.
• Add your API key to the collection’s authentication settings, and you’re ready to start making requests.

Errors

Sometimes, API requests fail. The CountdownMail API uses HTTP status codes to tell you what went wrong. Here’s a list of possible errors, what they mean, and what to do:

Example Error Response (401 Unauthorized):

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

If you see an error, check the status code and message, then follow the suggested action.

Timer Model

The Timer resource contains all the information about countdown timer. These are the fields available for defining a countdown timer:

{
    "separator_color"  : "4275BC",
    "separator_size" : 1.3,
    "separator_style" : 6,
    "labels_color" : "A3A3A3"
}
                                    

Create a Timer

This endpoint allows you to create a timer. To create a new timer, you must provide all required properties.

Example Request:

{
    "skin_id":3,
    "name":"Big Sale!",
    "time_end":"2025-05-12 20:00:00",
    "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"
}
                                    

{
    "status": "success",
    "message": {
        "id": 1057,
        "code": "td",
        "src": "http://i.countdownmail.com/td.gif"
    }
}
                                    

Update a Timer

This endpoint allows you to update any timer attribute. To update a timer, send a PUT request to /update/{code} with the fields you want to update. Replace {code} with the timer’s code (e.g., "td").

Example Request:

{
    "skin_id":6,
    "name":"Flash Sale!",
    "time_end":"2025-05-12 20:00:00"
}
                                    

{
    "status": "success",
    "message": {
        "id": 1057,
        "code": "td",
        "src": "http://i.countdownmail.com/td.gif"
    }
}
                                    

Duplicate a Timer

To make a copy of an existing timer, send a POST request to /duplicate/{code}. Replace {code} with the unique code of the timer you want to copy. This will create a new timer that starts with the same settings as the original one.

You can also update some details of the new timer by adding a JSON object in the request body. This lets you change specific attributes, like the end time or name, while keeping everything else the same as the original. The attributes you can update are the same ones you can set when creating a new timer (check the Timer Model section for the full list). If you don’t include an attribute in the request body, it will stay the same as it was in the original timer.

Important: The original timer does not change. Only the new timer is affected by the updates you send in the request.

Example Request:

{
    "skin_id":6,
    "name":"Flash Sale!",
    "time_end":"2025-05-12 20:00:00"
}
                                    

{
    "status": "success",
    "message": {
        "id": 1057,
        "code": "td",
        "src": "http://i.countdownmail.com/td.gif"
    }
}
                                    

Deactivate a Timer

To stop a timer (archive), send a GET request to /deactivate/{code}. Replace {code} with the timer’s code.

Activate a Timer

To activate a timer again, send a GET request to /activate/{code}. Replace {code} with the timer’s code.

Delete a Timer

To delete a timer, send a DELETE request to /delete/{code}. Replace {code} with the timer’s code.