NAV Navbar
Request/Response details

turboSMTP Public API

Version 1.0

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 or request header should look like what follows:

Authorization: 44cf4c36d0e9cbe32f6fd83ff69a9df3b6212828c

Authentication (a.k.a. login)

Request headers:

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

Request Body Example


{
    "email": "turboSMTP email address",
    "password": "turboSMTP password",
    "no_expire": "1"
}

Response headers:

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

Response body (successful authentication):

{
    "auth" : "44cf4c36d0e9cbe32f6fd83ff69a9df3b62128s28c"
}

Response body (unsuccessful authentication):

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

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

Request endpoint:

POST https://dashboard.serversmtp.com/api/authorize

If no_expire value is not specified or is set to 0, the authentication will expire in 1 hour, otherwise it will not expire.

You can revoke API access using the deauthorize endpoint.

Revoke API Access

Request headers:

Content-Type: application/json; charset=utf-8
Authorization: "your authorization token"

Response headers:

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

Response body (successful authentication):

{
    "message": "Token deauthorized"
}

Response body (unsuccessful authentication):

{
    "errorCode": 8,
    "message": "No authorization key was specified for request"
}
{
    "errorCode": 9,
    "message": "This authorization token doesn't exist."
}

Request endpoint:

POST https://dashboard.serversmtp.com/api/deauthorize

No params needed

Send email

Send email

Request Body Example


{
    "from": "email address",
    "to": "recipient email address",
    "subject": "subject in string format",
    "content": "plain / text content",
    "html_content": "html content",
    "attachments": [
        {
            "name": "test.gif",
            "type": "image/gif",
            "content": "The Base64 encoded content of the attachment."
        },
{
            "name": "test.pdf",
            "type": "application/pdf",
            "content": "The Base64 encoded content of the attachment."
        }
    ]
}


Attachment object

{
  "content": "The Base64 encoded content of the attachment.",
  "name": "The filename of the attachment.", 
  "type": "The mime type of the content you are attaching. For example, image/gif."
}

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"
     ]
 } 

Request endpoint:

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

Attachments

It should be configured as an array of attachments.

Limitations

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

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