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

Webhooks

TurboSMTP offers two types of event webhooks (Server To Server notification of events that occur to your emails): delivery and engagement events. The status of email delivery to the recipient is indicated by the delivery event, while the interaction of recipients with the email is represented by the engagement event. Please check the following pages for further information:

Send email

Send email V2

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 (Turbo-SMTP successfully received your message):

 { 
   "message":"OK" 
   "mid": 1475205839938715648
 }

Response body Example (in case of error):

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

Request endpoint:

POST https://api.eu.turbo-smtp.com/api/v2/mail/send --> for EU users

POST https://api.turbo-smtp.com/api/v2/mail/send --> for NON EU users

Attachments

It should be configured as an array of attachments.

Limitations

Failed requests will always return an error response, including a response code and a message explaining the reason for the error.

Response Code Response Message Description
200 OK Turbo-SMTP successfully received your message
400 BAD REQUEST Something wrong with the request body/parameters
401 UNAUTHORIZED Wrong credentials
500 SERVER_UNAVAILABLE An error occurred on a Turbo-Smtp server.

Errors

Please check Errors section for a detailed errors documentation.

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

Send email V1 deprecated

This endpoint is deprecated and will stop working on April 1st, 2022

Migration instructions

  1. Change the API url from https://api.turbo-smtp.com/api/mail/send to:
    https://api.turbo-smtp.com/api/v2/mail/send (NON EU users)
    or
    https://api.eu.turbo-smtp.com/api/v2/mail/send (EU users)
  2. Handle all types of status codes and status messages refer to Send API v2

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 see if turboSMTP tools are enabled / disabled and change.

Click tracking status

Request endpoint:

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

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 status

Request endpoint:

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

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": "openingTracking",
  "forced": false,
  "requiredSettings": [],
  "enabled": true,
  "settings": []
}

Enable / disable click tracking

Request endpoint:

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

Enable / disable open tracking

Request endpoint:

PUT 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

General 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

Send Api errors

Missing username/password

{
    "errorCode": 3,
    "message": "Invalid authorization token",
    "details": "No authorization key was specified for request: POST /api/mail/send"
}

Invalid username/password

{
    "error": 3,
    "message": "Wrong credentials specified"
}

Missing sender

{
    "message": "error",
    "errors": [
        "missing or not valid sender email (from)"
    ]
}

Missing recipients

{
    "message": "error",
    "errors": [
        "missing recipients (to)"
    ]
}

Invalid recipients (to-cc-bcc)

{
    "message": "error",
    "errors": [
        [
            "'INVALID_EMAIL' 'to' email not valid"
        ]
    ]
}

Invalid Mime

{
    "message": "error",
    "errors": {
        "message": "error",
        "errors": "Invalid Mime"
    }
}

No enough credit in account subscription

{
    "message": "error",
    "errors": {
        "message": "error",
        "errors": "nocredit"
    }
}

deactivated account

{
    "error": 3,
    "message": "Account for  test@domain.com  is inactive"
}
Request/Response details