API Information

Modified on Thu, 30 Sep, 2021 at 10:27 AM

This is for advanced users. If you would like to use the same countdown timer design with a different DateTime or a dynamic DateTime generated from your server, then using our API sounds like it's right for you. This is beneficial if you have system generated emails that need a countdown timer. The following is a walk-through on how to request a token through our API which you can append to your timer embed code. 


Pass Data via Query String


Note: Dealing with tokens too complex or doesn't fit in your set up? An alternate way of changing the date end time is to pass it directly via the query string in the following format ?endDateTime=yyyy-MM-ddTHH:mm:ss 


You can also adjust the date end time for the timezone the user is in by subtracting or adding the hours to the end of your parameter. 


Adding to UTC - In the example below 4 hours will be added to the UTC Time. Note that a plus is treated as a space in a URL so you need to encode the plus as a %2B as seen in the example.

?endDateTime=yyyy-MM-ddTHH:mm:ss%2B0400


Subtracting from UTC - in the example below hours will be subtracted from UTC. 

 ?endDateTime=yyyy-MM-ddTHH:mm:ss-0400


*New* - Updated the colors of your timer via query string


You can adjust the Background Color by using the BgColor parameter with the hex code of the color you would like to use.  In the example below we are overwriting the choices we made when we set up the timer and forcing it to have a green background.

?BgColor=32a852


You can adjust the Text Color by using the TxtColor parameter with the hex code of the color you would like to use.  In the example below we are overwriting the choices we made when we set up the timer and forcing it to have a powder blue background.

?TxtColor=aafffa

You can adjust the Primary Color of the timer by using the PrimaryColor parameter with the hex code of the color you would like to use.  In the example below we are overwriting the choices we made when we set up the timer and forcing it to be red.

?PrimaryColor=AA0000



Warning: URL hijacking protection is on by default on all MotionMail accounts. This prevents the ability to pass dates and times in plain text to timer URL's and requires users to use the API to dynamically change the end date and time of a timer. By disabling URL hijacking protection it will allow you to pass dates and times in plain via a query string (?endDateTime=yyyy-MM-ddTHH:mm:ss) however this would also allow others to take your timer URL and insert their own date.


API Calls:

Request Format

Your application needs to send a web request to our API endpoint to receive a token. Include the desired end date time, your API key and secret key — both found in the settings section of your dashboard —  as parameters: 


                        
                          $ curl https://api.motionmailapp.com/tokens/datetime
                            -u [API KEY]:[Secret Key]
                            -d datetime=[yyyy-MM-ddTHH:mm:ss] 
                    


Example request

Note: the datetime value should be formatted accordingly, yyyy-MM-ddTHH:mm:ss (ISO 8601).

                        
                          $ curl https://api.motionmailapp.com/tokens/datetime 
                            -u c30ca519-8d8b-4989-b05b-a2a00102d7c2:2d3b4600-89b0-4de5-8f8a-a2a00102d7c2 
                            -d datetime=2015-08-16T17:24:59 
                    


Example token response

Note: the Value parameter is your new DateTime Url Token

                        
                          {
                            "DateTimeCreated": "8/14/2015 5:24:59 PM +00:00",
                            "OriginalValue": "2015-08-16T17:24:59",
                            "Success": true,
                            "Data": "cjyCXDJBz73MDKo%2b6vGYlNLrBDfu9miZmshGelMycRs%3d"
                          }
                    


Example error response
                        
                          {
                            "DateTimeCreated": "8/14/2015 5:24:59 PM +00:00",
                            "Message": "Invalid DateTime value.",
                            "Param": "DateTime",
                            "StatusCode": "400",
                            "Type": "Bad_Request"
                          }
                        
                    


How to use the DateTime Url Token

After you have successfully generated the token, you simply append it to your embed code image url

<img src="...?endDateTimeToken=cjyCXDJBz73MDKo%2b6vGYlNLrBDfu9miZmshGelMycRs%3d" />


Warning: URL hijacking protection is on by default on all MotionMail accounts. This prevents the ability to pass dates and times in plain text to timer URL's and requires users to use the API to dynamically change the end date and time of a timer. By disabling URL hijacking protection it will allow you to pass dates and times in plain via a query string (?endDateTime=yyyy-MM-ddTHH:mm:ss) however this would also allow others to take your timer URL and insert their own date.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article