NAV Navbar
Request/Response details

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:

Authorization: 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&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