General API Resources

📘

Welcome to the SMTP2GO API Docs 👋

The SMTP2GO API offers you an enhanced level of control and monitoring of your SMTP2GO account.

Endpoints

API calls must be prefixed with one of the following base URL's:

If you send your requests to the 'Global' endpoint, the API will automatically choose the US, EU or AU endpoint based on which is closer to the request origin.

Technical Details

To work with the API, please be sure to adhere to the following guides:

• Always use the HTTP post method.
• All requests should be in the form of JSON.
• All requests must include the api_key field, or choose to use the X-Smtp2go-Api-Key field in your header, as shown below.

{
    "api_key": "YourAPIKeyHere",
    "search_subject": "Booking",
    "event_types": ["opened", "clicked"],
    "only_latest": true,
    "limit": 1
}

{
  'Content-Type': 'application/json',
  'X-Smtp2go-Api-Key': 'YourAPIKeyHere'
}

Response Codes

SMTP2GO uses conventional HTTP response codes to indicate the success or failure of a request.

In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error and reasons the request may have failed are given in the information provided. Codes in the 5xx range indicate an error with SMTP2GO's servers (these are rare and if encountered please contact support for assistance).

Below is a list of status codes and their corresponding definitions:

Additional information is contained in the response body as in the following examples.

{
   "error": "Failed to remove the single sender email - An error occurred deleting sender email [email protected] or it doesn't exist",
   "error_code": "E_ApiResponseCodes.API_EXCEPTION"
}

Some errors contain additional field validation error information, as below.

{
   "error": "An error occurred processing the json data you sent with the request, please make sure the data conforms to the specification for this call (see the documentation here: https://apidoc.smtp2go.com/documentation/#/README) and try again. Don't forget to set Content-Type to 'application/json'.",
   "error_code": "E_ApiResponseCodes.NON_VALIDATING_IN_PAYLOAD",
   "field_validation_errors": {
      "fieldname": "sender",
      "message": "The field 'sender' was expecting a valid RFC-822 formatted email field but found 'robs_invalid.com', Please correct your JSON payload and try again."
   }
}

Rate Limiting

There are no fixed rate-limits for any calls to the API.

In the event that your interaction with the API results in what we deem to be too many requests or error responses, the IP address from which the requests originated will be timed out for an indeterminate amount of time, no less than 1 minute.

You will receive a 429 Too Many Requests response code during this time. If you begin to see these responses, pause and lower your request rate until you begin to see 200 OK returned. Should you start receiving 429 Too Many Requests, also ensure the requests you are sending are returning 200 OK.

Points to note

Maximum email size

The maximum email size when sending via the API is 50 MB (this includes content, attachments and headers).

Maximum number of recipients per email

The maximum number of recipients per email for each of the To, CC and BCC fields is 100. It is important to note that each recipient will count as one email from your plan's monthly quota.

Subaccounts

Certain API calls can be performed on subaccounts, using a parent/master account's API Key. The relevant subaccount is specified by including the 'subaccount_id' parameter in the API call. Currently supported endpoints mention this parameter in our documentation.