NAV Navbar
Request/Response details
  • turboSMTP Public API
  • Getting started
  • Send email
  • Accounts
  • Reports
  • Statistics
  • Tools
  • Errors
  • turboSMTP Public API

    Version 0.1

    This document contains information about turboSMTP's public API. Please report bugs to: api@turbo-smtp.com

    Getting started

    Data interchange format

    For the most part (and where not otherwise explicit) turboSMTP’s API uses JSON as the data format of choice when it comes to request and response bodies.

    Accessing resources

    Authorization to access a user’s resource is granted to clients provided they set a authentication cookie into their request, valued with the proper authentication key issued by turboSMTP servers. The authentication key is user-based and it is issued by turboSMTP servers upon successful user’s email address + password challenge, performed by means of appropriate request.

    As an example, such cookie should look like what follows:

    authorizationKey: 44cf4c36d0e9cbe32f6fd83ff69a9df3b6212828c

    Authentication (a.k.a. login)

    The auth value in the response has to be used as a custom cookie for all requests towards turboSMTP's API.

    Request endpoint:

    GET https://dashboard.serversmtp.com/api/authorize/:username/:password

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body (successful authentication):

    {
        "auth" : "44cf4c36d0e9cbe32f6fd83ff69a9df3b6212828c"
    }
    

    Response body (unsuccessful authentication):

    {
        "errorCode" : 1,
        "message": "Wrong credentials specified"
    }
    

    Send email

    Send email

    Request endpoint:

    POST https://api.turbo-smtp.com/api/mail/send

    Some implementations

    PHP: Download PHP sample code

    C#: Download C# sample code

    Java: Download Java sample code

    Python: Download Python sample code

    Perl: Download Perl sample code

    Ruby: Download Ruby sample code

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body (successful authentication):

     { 
       "message":"OK" 
     }
    
    

    Response body (in case of error):

     { 
         "message": "error",
         "errors": [
            "error message"
         ]
     } 
    

    Accounts

    The following requests will allow you to show accounts info.

    Account info

    Request endpoint:

    GET https://dashboard.serversmtp.com/api/user/info

    No params needed.

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    {
      "passwd":"",
      "active":true,
      "email":"andrea@emailchef.com",
      "gateway":"q1",
      "ip":3350965831,
      "accountid":18897904
      ...
    }
    

    Active plans

    Request endpoint:

    GET https://dashboard.serversmtp.com/api/plans

    No params needed.

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    [{
        "id": 1,
        "accountID": 584,
        "smtp_limit": 200,
        "smtp_limit_interval": "Daily",
        "plan_expiration": "2019-01-04T00:00:00.000Z",
        "smtp_count": 1,
        "last_used": "2018-04-24T08:58:06.000Z",
        "parentid": null,
        "expired": 0,
        "active": true
    }, {
        "id": 2,
        "accountID": 584,
        "smtp_limit": 100000,
        "smtp_limit_interval": "Monthly",
        "plan_expiration": "2018-05-03T00:00:00.000Z",
        "smtp_count": 0,
        "last_used": "2018-04-04T08:47:16.000Z",
        "parentid": null,
        "expired": 0,
        "active": true
    }]
    
    

    Subaccounts list

    Request endpoint:

    GET https://dashboard.serversmtp.com/api/useraccounts/summary

    No params needed.

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    [{
         "id": 584,
         "email": "subaccount@dueclic.com",
         "active": true,
         "ip": "199.244.75.99",
         "sent": 3,
         "limit": -1,
         "reputation": 5
     }]
    
    

    Reports

    The following requests will allow you to show a reports list, count results, delete a single instance and export in CSV format.

    In the list requests 20 results for page are shown.

    Reports by type in time range

    Request endpoint:

    GET https://dashboard.serversmtp.com/web/api/reports/:type?start=:start&end=:end&page=:page&filter=:filter&tz=:tz

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    [
        {
            "cid": 323223135,
            "email": "andrea.colombini@dueclic.com",
            "ts": "2018-03-27T06:31:42.000Z",
            "response": "62.149.128.154 does not like recipient. Remote host said: 550 5.1.1 <andrea.colombini@dueclic.com> : sorry, no mailbox here by that name (#5.1.1 - chkuser) {1.2.3.4} Giving up on 1.2.3.4. "
        }
    ]
    

    Count reports by type in time range

    Request endpoint:

    GET https://dashboard.serversmtp.com/web/api/reports/:type/count?start=:start&end=:end&page=:page&filter=:filter&tz=:tz

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    {
        "count" : 1
    }
    

    Export reports in CSV by type in time range

    Request endpoint:

    GET https://dashboard.serversmtp.com/web/api/reports/:type/csv?start=:start&end=:end&page=:page&filter=:filter&tz=:tz

    All reports by type

    Request endpoint:

    GET https://dashboard.serversmtp.com/web/api/reports/:type/all?page=:page&filter=:filter&tz=:tz

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    [
        {
            "cid": 323223135,
            "email": "andrea.debernardi@dueclic.com",
            "ts": "2018-03-27T06:31:42.000Z",
            "response": "62.149.128.154 does not like recipient. Remote host said: 550 5.1.1 <andrea.debernardi@dueclic.com> : sorry, no mailbox here by that name (#5.1.1 - chkuser) {1.2.3.4} Giving up on 1.2.3.4. "
        }
    ]
    

    Count all reports by type

    Request endpoint:

    GET https://dashboard.serversmtp.com/web/api/reports/:type/all/count?filter=:filter&tz=:tz&page=:page

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    {
        "count" : 520
    }
    

    Export all reports in CSV by type

    Request endpoint:

    GET https://dashboard.serversmtp.com/web/api/reports/:type/all/csv?filter=:filter&tz=:tz&page=:page

    Delete report by type

    Request endpoint:

    DELETE https://dashboard.serversmtp.com/web/api/reports/:type?ids=:ids

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    {
        "success" : true
    }
    

    Delete all spam reports

    Request endpoint:

    DELETE https://dashboard.serversmtp.com/web/api/reports/spam/all

    No params needed

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    {
        "success" : true
    }
    

    Statistics

    The following requests will allow you to show statistics list, count results and export in CSV format.

    In the list requests 10 results for page are shown.

    Email sent statistics

    Request endpoint:

    GET https://dashboard.serversmtp.com/api/stats/panes/emails?start=:start&end=:end&page=:page&filter=:filter&tz=:tz

    Some filter combinations:

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    [
        {
            "id":4612864212,
            "subject":"Test for documentation",
            "sender":"christian.serafino@dueclic.com",
            "recipient":"andrea@debbaweb.it",
            "sendTime":"2018-04-24T10:58:06.000Z",
            "status":"SUCCESS",
            "error":null
        },
        {
            "id":4611292665,
            "subject":"Test for documentation #2",
            "sender":"andrea.debernardi@dueclic.com",
            "recipient":"test-dev@dueclic.com",
            "sendTime":"2018-04-23T17:33:02.000Z",
            "status":"OPEN",
            "error":null
        }
    ]
    

    Last email sent statistics

    Request endpoint:

    GET https://dashboard.serversmtp.com/api/stats/email-feed-last/:no

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    [
        {
            "id":4612864212,
            "subject":"Last test for documentation",
            "sender":"chiara.cortese@dueclic.com",
            "recipient":"andrea.debernardi@dueclic.com",
            "sendTime":"2018-04-24T10:58:06.000Z",
            "status":"SUCCESS",
            "error":null
        }
    ]
    

    Count of email sent

    Request endpoint:

    GET https://dashboard.serversmtp.com/api/stats/panes/emails/count?start=:start&end=:end&page=:page&filter=:filter&tz=:tz

    Some filter combinations:

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body:

    {
        "count" : 220
    }
    

    Export email sent statistics in CSV

    Request endpoint:

    GET https://dashboard.serversmtp.com/api/stats/emails/csv?start_date=:start_date&end_date=:end_date&filter=:filter&tz=:tz

    Some filter combinations:

    Tools

    The following requests will allow you to enable / disable some turboSMTP tools.

    Click tracking - enable / disable

    Request endpoint:

    GET https://dashboard.serversmtp.com/api/tools/clickTracking/:action

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body (in case of enabling):

    {
        "id": "clickTracking",
        "forced": false,
        "requiredSettings": [],
        "enabled": true,
        "settings": [
            {
                "key": "clicktracking",
                "value": true
            },
            {
                "key": "clicktracking_plaintext",
                "value": false
            }
        ]
    }
    

    Open tracking - enable / disable

    Request endpoint:

    GET https://dashboard.serversmtp.com/api/tools/openingTracking/:action

    Request headers:

    Content-Type: application/json; charset=utf-8
    

    Response headers:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    

    Response body (in case of disabling):

    {
        "id": "openingTracking",
        "forced": false,
        "requiredSettings": [],
        "enabled": false,
        "settings": []
    }
    

    Errors

    The turboSMTP API uses the following error codes:

    Error Type Meaning
    1 Invalid authorization credentials
    2 Provided account is inactive. Maybe you are banned.
    3 Invalid authorization token
    4 Resource not found
    5 Server system error
    6 Concurrent modification exception
    7 Access to requested resources is denied