NAV
Ruby JavaScript Go Python Java C#

Search results

SMTP2GO API

Send and manage emails and campaigns through this simple and intuitive API. The SMTP2GO API integrates with your applications to handle sending and receiving emails, reporting, and administration of email accounts.

Overview

This guide covers creating an SMTP2GO account, generating your API key, and choosing your region. That done, you are ready to integrate with the API.
You will also find details of the API's behaviour, inputs, and outputs.

The API has the following characteristics:

Languages Supported

The API may be called using any language that supports HTTP requests. Examples are provided for: Ruby, JavaScript, Go, Python, Java, C#.

Restrictions

Restrictions may be applied to:

There are no restrictions on attachment type.

Rate Limits

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/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 during this time. If you see this, lower your request rates until requests return 200 OK responses.

Email Restrictions

The number of emails you are able to send with a paid account is restricted in two ways:

Free accounts are further restricted. See our FAQ for more information.

Email Size

Maximum email size is 10MB, i.e. email content, headers, and attachments must remain under 10MB. You will receive an error if your emails are too large.

Quotas

Your plan determines your quota, and this may be adjusted to your needs. Alerts are sent if you approach this limit, and extra emails can be sent at a per-mail cost. See the billing and account section in our FAQ for more information.

Custom Rate Limits

Each user may have an individual quota applied in the form of a custom rate limit. This is achieved by setting each user's custom_ratelimit_period. This property is a string that may be formatted in several ways:

  1. Seconds, e.g. "3600" (i.e. 1 hour)
  2. A timestamp, e.g. "01:00:00:00" (i.e. 1 hour): this allows up to a maximum of 23:59:59:99
  3. A day specifier, e.g. "20 days"

Attachments

All attachment types are accepted.

Quick Start

Get started with SMTP2GO's simple REST API:

Authenticate

Pass your API key in all API calls.

Currently, your API key must be provided in the body of the request, e.g.: "api_key": "api-700B************************8F4E"

And, to future-proof your calls, we recommended also passing it in the X-Smtp2go-Api-Key header.

If you are new to using API keys, please consider API key security.

Choose your Region

Your options include:

Your choice of region determines the URL to which you make your API call. For example, to make a request to add senders to your allowed list using the US region, use the path:
https://us-api.smtp2go.com/v3/allowed_senders/add

API Key Security

It is important to keep your API key secure. Publicly exposing your key can compromise your account, which could result in unexpected charges. To keep your API keys secure, follow these best practices:

Responses

API Specification

Base URLs:

Email: SMTP2GO Support Web: SMTP2GO Support License: Apache 2.0

Authentication

Activity

A POST command allows you to search the activity stream. Select individual field/s to search, such as start_date, or utilise the search field to search across all fields.

Search events

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "subaccount_ids" => [

  ],
  "start_date" => "2021-04-20T00:00:00",
  "end_date" => "2021-04-21T00:00:00",
  "search" => "My search term",
  "search_subject" => "My search term",
  "search_sender" => "My search term",
  "search_recipient" => "My search term",
  "search_usernames" => "My search term",
  "limit" => 10,
  "continue_token" => "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX",
  "only_latest" => false,
  "event_types" => [
    "soft-bounced",
  ],
}

result = RestClient.post 'https://api.smtp2go.com/v3/activity/search', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "subaccount_ids": [],
  "start_date": "2021-04-20T00:00:00",
  "end_date": "2021-04-21T00:00:00",
  "search": "My search term",
  "search_subject": "My search term",
  "search_sender": "My search term",
  "search_recipient": "My search term",
  "search_usernames": "My search term",
  "limit": 10,
  "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX",
  "only_latest": false,
  "event_types": [
    "soft-bounced"
  ]
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/activity/search', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "subaccount_ids": []interface{}{

    },
    "start_date": "2021-04-20T00:00:00",
    "end_date": "2021-04-21T00:00:00",
    "search": "My search term",
    "search_subject": "My search term",
    "search_sender": "My search term",
    "search_recipient": "My search term",
    "search_usernames": "My search term",
    "limit": 10,
    "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX",
    "only_latest": false,
    "event_types": []interface{}{
      "soft-bounced",
    },
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/activity/search", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "subaccount_ids": [

  ],
  "start_date": "2021-04-20T00:00:00",
  "end_date": "2021-04-21T00:00:00",
  "search": "My search term",
  "search_subject": "My search term",
  "search_sender": "My search term",
  "search_recipient": "My search term",
  "search_usernames": "My search term",
  "limit": 10,
  "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX",
  "only_latest": False,
  "event_types": [
    "soft-bounced",
  ],
})

r = requests.post('https://api.smtp2go.com/v3/activity/search', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("subaccount_ids", array(

      )),
      field("start_date", string("2021-04-20T00:00:00")),
      field("end_date", string("2021-04-21T00:00:00")),
      field("search", string("My search term")),
      field("search_subject", string("My search term")),
      field("search_sender", string("My search term")),
      field("search_recipient", string("My search term")),
      field("search_usernames", string("My search term")),
      field("limit", number(10)),
      field("continue_token", string("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX")),
      field("only_latest", falseNode()),
      field("event_types", array(
        string("soft-bounced")
      ))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/activity/search")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/activity/search"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"subaccount_ids", new dynamic[] {

            }},
            {"start_date", "2021-04-20T00:00:00"},
            {"end_date", "2021-04-21T00:00:00"},
            {"search", "My search term"},
            {"search_subject", "My search term"},
            {"search_sender", "My search term"},
            {"search_recipient", "My search term"},
            {"search_usernames", "My search term"},
            {"limit", 10},
            {"continue_token", "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX"},
            {"only_latest", false},
            {"event_types", new dynamic[] {
              "soft-bounced",
            }},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/activity/search

This endpoint searches the activity stream for events.

Parameters

api_key required string
Example: "api-700B************************8F4E"
subaccount_ids array
start_date string
ISO-8601-formatted datetime, which defaults to the current date at midnight (the range is inclusive of start_date and exclusive of end_date)
Example: "2021-04-20T00:00:00"
end_date string
ISO-8601-formatted datetime, which defaults to now
Example: "2021-04-21T00:00:00"
search string
A string used to search across all fields
Example: "My search term"
search_subject string
A string used to search the subject field
Example: "My search term"
search_sender string
A string used to search the sender field
Example: "My search term"
search_recipient string
A string used to search the recipients field
Example: "My search term"
search_usernames string
A string used to search the username field
Example: "My search term"
limit integer
An integer to restrict the number of events returned per page
Example: 10
continue_token string
A string containing a token used to fetch the next page of results based on the current search
Example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX"
only_latest boolean, default is "false"
Pass true here to display only the latest event for each email
event_types [ActivityEventTypes]
A list of event types to filter on
processed
soft-bounced
hard-bounced
rejected
spam
delivered
unsubscribed
resubscribed
opened
clicked

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "total_events": 10,
    "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX",
    "events": [
      {
        "from": "client@example.com",
        "email_id": "1pq8bV-9Tw0Mi-7i",
        "date": "2021-04-20T00:00-M",
        "event": "soft-bounced",
        "recipients": "test-email-1@example.com, test-email-2@example.com, test-email-3@example.com",
        "subject": "This month's best buys",
        "username": "Test User",
        "reply_to": "best-offers@example.com",
        "sender": "best-offers@example.com",
        "to": "Test User",
        "cc": "Marketing",
        "bcc": "Auditing",
        "smtp_response": "250 2.0.0 OK n21si609690eju.243 - gsmtp",
        "reason": "No longer interested",
        "error": "An error occured",
        "email_client": {
          "fullname": "Hotmail 94.0",
          "name": "Hotmail"
        },
        "metadata": {
          "url": "example@example.com",
          "read_secs": 15,
          "user_agent": "Mozilla/5.0 (Linux)"
        }
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – activity stream query results returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
An object containing the results of the search
total_events integer
The total number of events that match the search criteria
Example: 10
continue_token string
A string containing a paging token in the event that there are more results to page through based on the current search criteria
Example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX"
events [object]
A list of events matching the search criteria
from string
The value of the From header
Example: "client@example.com"
email_id string
The unique ID of the email which generated the event
Example: "1pq8bV-9Tw0Mi-7i"
date string
An RFC3339-encoded timestamp with UTC timezone indicating the timestamp of the event
Example: "2021-04-20T00:00-M"
event ActivityEventTypes
A string indicating the type of the event
Example: "soft-bounced"
processed
soft-bounced
hard-bounced
rejected
spam
delivered
unsubscribed
resubscribed
opened
clicked
recipients string
A comma-seperated string listing the email recipients
Example: "test-email-1@example.com, test-email-2@example.com, test-email-3@example.com"
subject string
The subject of the email
Example: "This month's best buys"
username string
The username that sent the email
Example: "Test User"
reply_to string
The value of the ReplyTo header if available
Example: "best-offers@example.com"
sender string
The return-path / sender of the email
Example: "best-offers@example.com"
to string
The value of the To header if available
Example: "Test User"
cc string
The value of the Cc header if available
Example: "Marketing"
bcc string
The value of the Bcc header if available
Example: "Auditing"
smtp_response string
The response the SMTP server gave if applicable
Example: "250 2.0.0 OK n21si609690eju.243 - gsmtp"
reason string
The reason given for a spam / unsubscribe event if available
Example: "No longer interested"
error string
An error message for the event where applicable
Example: "An error occured"
email_client object
Information about the email client / browser that generated the open/click event
fullname string
The fullname of the email client including version information
Example: "Hotmail 94.0"
name string
The name of the email client without version information
Example: "Hotmail"
metadata object
Any additional information pertinent to the event
url string
The URL that was clicked
Example: "example@example.com"
read_secs integer
The number of seconds the email was read for (up to 30 seconds)
Example: 15
user_agent string
The raw UserAgent string of the client/browser that initiated open/click events
Example: "Mozilla/5.0 (Linux)"

Allowed Senders

The allowed senders feature is an allow-list that utilises a POST command to enable administrators to add, remove, update, and view the list of active users, known as the allowed_senders group. Pass either the:

Add Senders

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "subaccount_id" => "bKj21",
  "allowed_senders" => [
    "test-email@example.com",
    "@example.com",
  ],
}

result = RestClient.post 'https://api.smtp2go.com/v3/allowed_senders/add', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "allowed_senders": [
    "test-email@example.com",
    "@example.com"
  ]
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/allowed_senders/add', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "subaccount_id": "bKj21",
    "allowed_senders": []interface{}{
      "test-email@example.com",
      "@example.com",
    },
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/allowed_senders/add", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "allowed_senders": [
    "test-email@example.com",
    "@example.com",
  ],
})

r = requests.post('https://api.smtp2go.com/v3/allowed_senders/add', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("subaccount_id", string("bKj21")),
      field("allowed_senders", array(
        string("test-email@example.com"),
        string("@example.com")
      ))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/allowed_senders/add")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/allowed_senders/add"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"subaccount_id", "bKj21"},
            {"allowed_senders", new dynamic[] {
              "test-email@example.com",
              "@example.com",
            }},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/allowed_senders/add

This endpoint adds one or more allowed senders to your account.

Parameters

api_key required string
Example: "api-700B************************8F4E"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"
allowed_senders required [string]
A list of email addresses (and/or domains) that are allowed to send emails through this account
Example: ["test-email@example.com","@example.com"]

Response

{
  "data": {
    "allowed_senders": [
      "@example.com",
      "test-email@example.com"
    ]
  },
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – senders added to account

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
allowed_senders [any]
A list of email addresses (and/or domains) that are allowed to send emails through this account

Remove Senders

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "allowed_senders" => [
    "test-email@example.com",
    "@example.com",
  ],
}

result = RestClient.post 'https://api.smtp2go.com/v3/allowed_senders/remove', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "allowed_senders": [
    "test-email@example.com",
    "@example.com"
  ]
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/allowed_senders/remove', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "allowed_senders": []interface{}{
      "test-email@example.com",
      "@example.com",
    },
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/allowed_senders/remove", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "allowed_senders": [
    "test-email@example.com",
    "@example.com",
  ],
})

r = requests.post('https://api.smtp2go.com/v3/allowed_senders/remove', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")),
      field("allowed_senders", array(
        string("test-email@example.com"),
        string("@example.com")
      ))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/allowed_senders/remove")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/allowed_senders/remove"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"},
            {"allowed_senders", new dynamic[] {
              "test-email@example.com",
              "@example.com",
            }},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/allowed_senders/remove

This endpoint removes one or more allowed senders from your account.

Parameters

api_key required string
Example: "api-700B************************8F4E"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"
allowed_senders required [string]
A list of one or more email addresses (and/or domain names) to remove from the list of allowed senders

Response

{
  "data": {
    "allowed_senders": [
      "test-email@example.com",
      "example.com"
    ]
  },
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – senders removed from account

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
allowed_senders [any]
A list of email address (and/or domains) that are allowed to send emails through this account

Update Senders

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "subaccount_id" => "bKj21",
  "allowed_senders" => [
    "marketing@example.com",
    "@example.com",
  ],
}

result = RestClient.post 'https://api.smtp2go.com/v3/allowed_senders/update', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "allowed_senders": [
    "marketing@example.com",
    "@example.com"
  ]
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/allowed_senders/update', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "subaccount_id": "bKj21",
    "allowed_senders": []interface{}{
      "marketing@example.com",
      "@example.com",
    },
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/allowed_senders/update", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "allowed_senders": [
    "marketing@example.com",
    "@example.com",
  ],
})

r = requests.post('https://api.smtp2go.com/v3/allowed_senders/update', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("subaccount_id", string("bKj21")),
      field("allowed_senders", array(
        string("marketing@example.com"),
        string("@example.com")
      ))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/allowed_senders/update")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/allowed_senders/update"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"subaccount_id", "bKj21"},
            {"allowed_senders", new dynamic[] {
              "marketing@example.com",
              "@example.com",
            }},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/allowed_senders/update

This endpoint updates the allowed senders list on your account, overwriting the current list with the passed 'allowed_senders' value/s. Update overwrites any existing data.

Parameters

api_key required string
Example: "api-700B************************8F4E"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"
allowed_senders required [string]
A list of one or more email addresses (and/or domain names) that will be allowed to send emails through your account
Example: ["marketing@example.com","@example.com"]

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "allowed_senders": [
      "marketing@example.com",
      "@example.com"
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – sender list updated

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
allowed_senders [any]
A list of email address (and/or domains) that are allowed to send emails through this account
Example: ["marketing@example.com","@example.com"]

View Senders

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "subaccount_id" => "bKj21",
}

result = RestClient.post 'https://api.smtp2go.com/v3/allowed_senders/view', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/allowed_senders/view', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "subaccount_id": "bKj21",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/allowed_senders/view", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
})

r = requests.post('https://api.smtp2go.com/v3/allowed_senders/view', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("subaccount_id", string("bKj21"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/allowed_senders/view")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/allowed_senders/view"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"subaccount_id", "bKj21"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/allowed_senders/view

This endpoint returns the allowed sender list for your account.

Parameters

api_key required string
Example: "api-700B************************8F4E"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "allowed_senders": [
      "marketing@example.com",
      "@example.com"
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – sender list returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
allowed_senders [any]
A list of email address (and/or domains) that are allowed to send emails through this account
Example: ["marketing@example.com","@example.com"]

Emails

A POST command allows you to send an email or retrieve details of past emails that have been sent. There are two methods to send emails through the API:
1. /email/send


2. /email/mime

Send Email

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "sender" => "deals@example.com",
  "to" => [
    "test-email-1@example.com",
    "test-email-2@example.com",
    "test-email-3@example.com",
  ],
  "cc" => [
    "test-email-1@example.com",
    "test-email-2@example.com",
    "test-email-3@example.com",
  ],
  "bcc" => [
    "marketing@example.com",
    "auditing@example.com",
  ],
  "subject" => "This month's deals",
  "html_body" => "`<h1>HTML Content</h1> <p>Email Content</p>`",
  "text_body" => "A happy new year to all our customers",
  "custom_headers" => [
    {
      "header" => "marketing",
      "value" => "email-marketing-1",
    },
  ],
  "attachments" => [
    {
      "filename" => "JanuaryPortfolio.png",
      "fileblob" => "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX...",
      "mimetype" => "text/plain",
    },
  ],
  "inlines" => [
    {
      "filename" => "JanuaryPortfolio.png",
      "fileblob" => "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX...",
      "mimetype" => "text/plain",
    },
  ],
}

result = RestClient.post 'https://api.smtp2go.com/v3/email/send', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "sender": "deals@example.com",
  "to": [
    "test-email-1@example.com",
    "test-email-2@example.com",
    "test-email-3@example.com"
  ],
  "cc": [
    "test-email-1@example.com",
    "test-email-2@example.com",
    "test-email-3@example.com"
  ],
  "bcc": [
    "marketing@example.com",
    "auditing@example.com"
  ],
  "subject": "This month's deals",
  "html_body": "`<h1>HTML Content</h1> <p>Email Content</p>`",
  "text_body": "A happy new year to all our customers",
  "custom_headers": [
    {
      "header": "marketing",
      "value": "email-marketing-1"
    }
  ],
  "attachments": [
    {
      "filename": "JanuaryPortfolio.png",
      "fileblob": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX...",
      "mimetype": "text/plain"
    }
  ],
  "inlines": [
    {
      "filename": "JanuaryPortfolio.png",
      "fileblob": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX...",
      "mimetype": "text/plain"
    }
  ]
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/email/send', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "sender": "deals@example.com",
    "to": []interface{}{
      "test-email-1@example.com",
      "test-email-2@example.com",
      "test-email-3@example.com",
    },
    "cc": []interface{}{
      "test-email-1@example.com",
      "test-email-2@example.com",
      "test-email-3@example.com",
    },
    "bcc": []interface{}{
      "marketing@example.com",
      "auditing@example.com",
    },
    "subject": "This month's deals",
    "html_body": "`<h1>HTML Content</h1> <p>Email Content</p>`",
    "text_body": "A happy new year to all our customers",
    "custom_headers": []interface{}{
      map[string]interface{}{
        "header": "marketing",
        "value": "email-marketing-1",
      },
    },
    "attachments": []interface{}{
      map[string]interface{}{
        "filename": "JanuaryPortfolio.png",
        "fileblob": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX...",
        "mimetype": "text/plain",
      },
    },
    "inlines": []interface{}{
      map[string]interface{}{
        "filename": "JanuaryPortfolio.png",
        "fileblob": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX...",
        "mimetype": "text/plain",
      },
    },
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/email/send", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "sender": "deals@example.com",
  "to": [
    "test-email-1@example.com",
    "test-email-2@example.com",
    "test-email-3@example.com",
  ],
  "cc": [
    "test-email-1@example.com",
    "test-email-2@example.com",
    "test-email-3@example.com",
  ],
  "bcc": [
    "marketing@example.com",
    "auditing@example.com",
  ],
  "subject": "This month's deals",
  "html_body": "`<h1>HTML Content</h1> <p>Email Content</p>`",
  "text_body": "A happy new year to all our customers",
  "custom_headers": [
    {
      "header": "marketing",
      "value": "email-marketing-1",
    },
  ],
  "attachments": [
    {
      "filename": "JanuaryPortfolio.png",
      "fileblob": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX...",
      "mimetype": "text/plain",
    },
  ],
  "inlines": [
    {
      "filename": "JanuaryPortfolio.png",
      "fileblob": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX...",
      "mimetype": "text/plain",
    },
  ],
})

r = requests.post('https://api.smtp2go.com/v3/email/send', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("sender", string("deals@example.com")),
      field("to", array(
        string("test-email-1@example.com"),
        string("test-email-2@example.com"),
        string("test-email-3@example.com")
      )),
      field("cc", array(
        string("test-email-1@example.com"),
        string("test-email-2@example.com"),
        string("test-email-3@example.com")
      )),
      field("bcc", array(
        string("marketing@example.com"),
        string("auditing@example.com")
      )),
      field("subject", string("This month's deals")),
      field("html_body", string("`<h1>HTML Content</h1> <p>Email Content</p>`")),
      field("text_body", string("A happy new year to all our customers")),
      field("custom_headers", array(
        object(
          field("header", string("marketing")),
          field("value", string("email-marketing-1"))
        )
      )),
      field("attachments", array(
        object(
          field("filename", string("JanuaryPortfolio.png")),
          field("fileblob", string("PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX...")),
          field("mimetype", string("text/plain"))
        )
      )),
      field("inlines", array(
        object(
          field("filename", string("JanuaryPortfolio.png")),
          field("fileblob", string("PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX...")),
          field("mimetype", string("text/plain"))
        )
      ))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/email/send")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/email/send"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"sender", "deals@example.com"},
            {"to", new dynamic[] {
              "test-email-1@example.com",
              "test-email-2@example.com",
              "test-email-3@example.com",
            }},
            {"cc", new dynamic[] {
              "test-email-1@example.com",
              "test-email-2@example.com",
              "test-email-3@example.com",
            }},
            {"bcc", new dynamic[] {
              "marketing@example.com",
              "auditing@example.com",
            }},
            {"subject", "This month's deals"},
            {"html_body", "`<h1>HTML Content</h1> <p>Email Content</p>`"},
            {"text_body", "A happy new year to all our customers"},
            {"custom_headers", new dynamic[] {
              new Dictionary<string, dynamic>{
                {"header", "marketing"},
                {"value", "email-marketing-1"},
              },
            }},
            {"attachments", new dynamic[] {
              new Dictionary<string, dynamic>{
                {"filename", "JanuaryPortfolio.png"},
                {"fileblob", "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX..."},
                {"mimetype", "text/plain"},
              },
            }},
            {"inlines", new dynamic[] {
              new Dictionary<string, dynamic>{
                {"filename", "JanuaryPortfolio.png"},
                {"fileblob", "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX..."},
                {"mimetype", "text/plain"},
              },
            }},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/email/send

This endpoint implements the sending of emails via the API.

Parameters

api_key required string
Example: "api-700B************************8F4E"
sender required string
The email address to send from
Example: "deals@example.com"
to required [string]
An array of outbound email addresses (up to 100)
Example: ["test-email-1@example.com","test-email-2@example.com","test-email-3@example.com"]
cc [string]
An array of email addresses (up to 100) to Cc
Example: ["test-email-1@example.com","test-email-2@example.com","test-email-3@example.com"]
bcc [string]
An array of email addresses (up to 100) to Bcc
Example: ["marketing@example.com","auditing@example.com"]
subject required string
The subject of the email to be sent
Example: "This month's deals"
html_body string
An HTML email body
Example: "`<h1>HTML Content</h1> <p>Email Content</p>`"
text_body string
A plaintext email body
Example: "A happy new year to all our customers"
custom_headers [object]
An optional set of custom headers to be applied to the email
header required string
Custom header to add to the email
Example: "marketing"
value required string
Custom header value to set
Example: "email-marketing-1"
attachments [object]
An array of objects to be attached to the email
filename required string
The filename to use for this binary data
Example: "JanuaryPortfolio.png"
fileblob required string
The Base64-encoded binary data of the file
Example: "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX..."
mimetype required string
The mimetype of the binary data
Example: "text/plain"
inlines [object]
An array of images to be inlined into the email
filename string
The filename to use for this binary data
Example: "JanuaryPortfolio.png"
fileblob string
The Base64-encoded binary data of the file
Example: "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA5NiAzOSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgOTYgMzkiPjxwYXRoIGZXXX..."
mimetype string
The mimetype of the binary data
Example: "text/plain"

Response

{
  "email_response": {
    "succeeded": 10,
    "failed": 0,
    "failures": [
      "\"failures\":[\"Message failed - Error: 452-4.2.2 The email account that you tried to reach is over quota.\"]"
    ],
    "email_id": "1er8bV-6Tw0Mi-7h"
  },
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – email sent

email_response EmailResponseSchema
succeeded integer
Count of emails successfully sent
Example: 10
failed integer
Count of emails that failed
failures [string]
email_id string
The email ID generated (if successful)
Example: "1er8bV-6Tw0Mi-7h"
request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"

Send MIME Email

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "mime_email" => "RnJvbTogSm9obiBEb2UgPGV4YW1wbGVAZXhhbXBsZS5jb20+DQpNSU1FLVZlcnNpb246IDEuMA0KQ29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7DQoXXX...",
}

result = RestClient.post 'https://api.smtp2go.com/v3/email/mime', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "mime_email": "RnJvbTogSm9obiBEb2UgPGV4YW1wbGVAZXhhbXBsZS5jb20+DQpNSU1FLVZlcnNpb246IDEuMA0KQ29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7DQoXXX..."
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/email/mime', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "mime_email": "RnJvbTogSm9obiBEb2UgPGV4YW1wbGVAZXhhbXBsZS5jb20+DQpNSU1FLVZlcnNpb246IDEuMA0KQ29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7DQoXXX...",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/email/mime", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "mime_email": "RnJvbTogSm9obiBEb2UgPGV4YW1wbGVAZXhhbXBsZS5jb20+DQpNSU1FLVZlcnNpb246IDEuMA0KQ29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7DQoXXX...",
})

r = requests.post('https://api.smtp2go.com/v3/email/mime', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("mime_email", string("RnJvbTogSm9obiBEb2UgPGV4YW1wbGVAZXhhbXBsZS5jb20+DQpNSU1FLVZlcnNpb246IDEuMA0KQ29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7DQoXXX..."))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/email/mime")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/email/mime"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"mime_email", "RnJvbTogSm9obiBEb2UgPGV4YW1wbGVAZXhhbXBsZS5jb20+DQpNSU1FLVZlcnNpb246IDEuMA0KQ29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7DQoXXX..."},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/email/mime

This endpoint implements the sending of MIME-encoded emails via the API.

Parameters

api_key required string
Example: "api-700B************************8F4E"
mime_email required string
A valid MIME-encoded email that has been Base64-encoded
Example: "RnJvbTogSm9obiBEb2UgPGV4YW1wbGVAZXhhbXBsZS5jb20+DQpNSU1FLVZlcnNpb246IDEuMA0KQ29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7DQoXXX..."

Response

{
  "email_response": {
    "succeeded": 10,
    "failed": 0,
    "failures": [
      "\"failures\":[\"Message failed - Error: 452-4.2.2 The email account that you tried to reach is over quota.\"]"
    ],
    "email_id": "1er8bV-6Tw0Mi-7h"
  },
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – email sent

email_response EmailResponseSchema
succeeded integer
Count of emails successfully sent
Example: 10
failed integer
Count of emails that failed
failures [string]
email_id string
The email ID generated (if successful)
Example: "1er8bV-6Tw0Mi-7h"
request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"

Search Sent Email

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "continue_token" => "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX",
  "start_date" => "2021-04-20T00:00:00",
  "end_date" => "2021-04-20T00:00:00",
  "limit" => 500,
  "email_id" => [
    "1pq8bV-9Tw0Mi-7i",
  ],
  "filter_query" => "recipient:test-email@example.com",
  "username" => "Test User",
  "headers" => [
    {
      "key" => "Bcc",
      "value" => "audit@example.com",
    },
  ],
  "status_counts" => false,
  "opened_only" => false,
  "clicked_only" => false,
  "sort_by" => "delivered_at",
  "sort_dir" => "asc",
  "ignore_case" => false,
}

result = RestClient.post 'https://api.smtp2go.com/v3/email/search', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX",
  "start_date": "2021-04-20T00:00:00",
  "end_date": "2021-04-20T00:00:00",
  "limit": 500,
  "email_id": [
    "1pq8bV-9Tw0Mi-7i"
  ],
  "filter_query": "recipient:test-email@example.com",
  "username": "Test User",
  "headers": [
    {
      "key": "Bcc",
      "value": "audit@example.com"
    }
  ],
  "status_counts": false,
  "opened_only": false,
  "clicked_only": false,
  "sort_by": "delivered_at",
  "sort_dir": "asc",
  "ignore_case": false
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/email/search', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX",
    "start_date": "2021-04-20T00:00:00",
    "end_date": "2021-04-20T00:00:00",
    "limit": 500,
    "email_id": []interface{}{
      "1pq8bV-9Tw0Mi-7i",
    },
    "filter_query": "recipient:test-email@example.com",
    "username": "Test User",
    "headers": []interface{}{
      map[string]interface{}{
        "key": "Bcc",
        "value": "audit@example.com",
      },
    },
    "status_counts": false,
    "opened_only": false,
    "clicked_only": false,
    "sort_by": "delivered_at",
    "sort_dir": "asc",
    "ignore_case": false,
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/email/search", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX",
  "start_date": "2021-04-20T00:00:00",
  "end_date": "2021-04-20T00:00:00",
  "limit": 500,
  "email_id": [
    "1pq8bV-9Tw0Mi-7i",
  ],
  "filter_query": "recipient:test-email@example.com",
  "username": "Test User",
  "headers": [
    {
      "key": "Bcc",
      "value": "audit@example.com",
    },
  ],
  "status_counts": False,
  "opened_only": False,
  "clicked_only": False,
  "sort_by": "delivered_at",
  "sort_dir": "asc",
  "ignore_case": False,
})

r = requests.post('https://api.smtp2go.com/v3/email/search', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("continue_token", string("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX")),
      field("start_date", string("2021-04-20T00:00:00")),
      field("end_date", string("2021-04-20T00:00:00")),
      field("limit", number(500)),
      field("email_id", array(
        string("1pq8bV-9Tw0Mi-7i")
      )),
      field("filter_query", string("recipient:test-email@example.com")),
      field("username", string("Test User")),
      field("headers", array(
        object(
          field("key", string("Bcc")),
          field("value", string("audit@example.com"))
        )
      )),
      field("status_counts", falseNode()),
      field("opened_only", falseNode()),
      field("clicked_only", falseNode()),
      field("sort_by", string("delivered_at")),
      field("sort_dir", string("asc")),
      field("ignore_case", falseNode())
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/email/search")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/email/search"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"continue_token", "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX"},
            {"start_date", "2021-04-20T00:00:00"},
            {"end_date", "2021-04-20T00:00:00"},
            {"limit", 500},
            {"email_id", new dynamic[] {
              "1pq8bV-9Tw0Mi-7i",
            }},
            {"filter_query", "recipient:test-email@example.com"},
            {"username", "Test User"},
            {"headers", new dynamic[] {
              new Dictionary<string, dynamic>{
                {"key", "Bcc"},
                {"value", "audit@example.com"},
              },
            }},
            {"status_counts", false},
            {"opened_only", false},
            {"clicked_only", false},
            {"sort_by", "delivered_at"},
            {"sort_dir", "asc"},
            {"ignore_case", false},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/email/search

This endpoint retrieves a list of up to 5,000 sent emails matching the supplied parameters with a POST request.
Search uses boolean operators and may be applied broadly across multiple fields using the filter query. The search may be targeted according to the field or applied to headers.

Boolean Operators

The search supports boolean operators:

Filter Query Field

The filter_query field utilizes a subset of the Whoosh API, which can be used to create complex filters to make searching more efficient. From the Whoosh documentation:

Multiple terms can be combined with boolean operators to form a more complex query.

Field Query

If you want to search a specific field for something, use the field name followed by a colon and then your search term or phrase, e.g.:

The following fields are indexed and can be used for searching emails:

Field Description
sender The sender/from email address
sent_ts Unix timestamp when the message was sent
recipient The recipient email address(s)
subject The subject header
delivered_ts Unix timestamp when the message reached its destination
status (see Delivery Status list) Status of the email
email_id A unique identifier of the email sent
smtpcode The response code from the destination SMTP server
host The destination host
headers The headers of the email

Delivery Status Keywords

Where multiple keywords exist, they can be used interchangeably.

Status Description
failed Delivery failed
deferred Delivery temporarily failed
hard-bounce, refused Email rejected by destination MX
soft-bounce, returned Email returned after delivery
delivered, ok, sent Email accepted by destination MX
rejected Email rejected
unsubscribed Recipient used unsubscribe link
complained, spam Recipient made a spam complaint
unblocked Unsubscribe cancelled

Searching Headers

Any email header can be searched.

This search query must be a phrase surrounded by single quotes, e.g.:

In order to search for multiple headers, separate the header searches with a semi-colon character, e.g.:


Email Status

Note that an email has just one status at any moment in time:

Status Description
failed Delivery failed. Note, the deprecated boolean 0:failed/1:succeeded is still supported.
deferred Delivery temporarily failed
hardbounce Refused (email rejected by destination MX)
softbounce Returned (email returned after delivery)
delivered Ok, sent (email accepted by destination MX)
rejected Email rejected
unsubscribed Recipient used unsubscribe link
complained Recipient made spam complaint
unblocked Recipient cancelled unsubscribe


Parameters

api_key required string
Example: "api-700B************************8F4E"
continue_token string
Pass this if the result of this query returns it; used to continue the previous search if too many results were found
Example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX"
start_date string
ISO-8601-formatted datetime, which defaults to the current date at midnight. The range will be inclusive of start_date and exclusive of end_date. Timezone is UTC.
Example: "2021-04-20T00:00:00"
end_date string
ISO-8601-formatted datetime, which defaults to now. Timezone is UTC.
Example: "2021-04-20T00:00:00"
limit integer, default is "5000"
The maximum number of emails to return
Example: 500
email_id [string]
Returns only email/s with an ID contained within this array
filter_query string
Optional search field to filter results. The accepted syntax is described here
Example: "recipient:test-email@example.com"
username string
If passed, the query will be restricted to email details sent by this user
Example: "Test User"
headers [object]
An array of key/value properties to specify required email header values
key string
Header name / key
Example: "Bcc"
value string
Property value
Example: "audit@example.com"
status_counts boolean, default is "false"
If true, an object with counts of each unique email status will be returned (the email array will be empty)
opened_only boolean, default is "false"
If true, the results will only contain emails that at least one recipient has opened
clicked_only boolean, default is "false"
If true, the results will only contain emails that have had a link clicked by at least one recipient
sort_by string, default is "email_ts"
Specifies which field to sort by
Example: "delivered_at"
email_ts
delivered_at
sort_dir string, default is "desc"
Specifies which direction to sort by
Example: "asc"
asc
desc
ignore_case boolean, default is "false"
Set to true for case-insensitive string searches

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "count": 12,
    "emails": [
      {
        "subject": "This month's deals",
        "delivered_at": "2021-04-20T00:00:00",
        "process_status": "completed",
        "email_id": "1er8bV-6Tw0Mi-7h",
        "status": "delivered",
        "response": "250 2.0.0 OK n21si609690eju.243 - gsmtp",
        "email_ts": "2021-04-20T00:00:00",
        "host": "marketing.smtp2go.net",
        "smtpcode": 250,
        "sender": "marketing@example.com",
        "recipient": "test-email@example.com",
        "username": "authuser",
        "headers": "\"headers\": [\"key\": \"Bcc\",\"value\": \"audit@example.com\"]",
        "total_opens": 8,
        "opens": [
          {
            "opened_at": null,
            "ip_address": null,
            "user_agent": null,
            "read_secs": null
          }
        ],
        "total_clicks": 5,
        "clicks": [
          {
            "clicked_at": null,
            "ip_address": null,
            "user_agent": null,
            "url": null
          }
        ]
      }
    ],
    "status_counts": "[\"status_counts\": [\"delivered\": 206, \"defer\": 53, \"spam\": 1, \"refused\": 3]]",
    "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX"
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – query results returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
count integer
Count of emails matching the search parameters
Example: 12
emails [object]
An array of email information objects
subject string
The email subject
Example: "This month's deals"
delivered_at string
The timestamp at which the delivery was made
Example: "2021-04-20T00:00:00"
process_status string
The current status of the delivery process
Example: "completed"
completed
processing
rejected
email_id string
The unique ID for the delivery attempt
Example: "1er8bV-6Tw0Mi-7h"
status string
The status of the email
Example: "delivered"
failed
deferred
hardbounce
softbounce
delivered
rejected
unsubscribed
complained
unblocked
response string
The response from the SMTP server, or reason for failure if the server was not contacted
Example: "250 2.0.0 OK n21si609690eju.243 - gsmtp"
email_ts string
The ISO-8601-formatted timestamp that the email was originally sent at
Example: "2021-04-20T00:00:00"
host string
The SMTP server that was connected to when attempting to deliver the email
Example: "marketing.smtp2go.net"
smtpcode integer
The SMTP response code from the SMTP server
Example: 250
sender string
The email address the email was sent from
Example: "marketing@example.com"
recipient string
The email address the email was sent to
Example: "test-email@example.com"
username string
The username of the SMTP2GO user that sent the email
Example: "authuser"
headers [object]
An array of key/value properties to specify required email header values
Example: "\"headers\": [\"key\": \"Bcc\",\"value\": \"audit@example.com\"]"
key string
Header name / key
Example: "Bcc"
value string
Property value
Example: "audit@example.com"
total_opens integer, default is "0"
The number of times this email has been opened
Example: 8
opens [object]
An array of open information objects
opened_at string
The ISO-8601-formatted timestamp indicating when the email was opened
Example: "2021-05-20T00:00:00"
ip_address string
The IP Address of the client that opened the email
Example: "192.0.2.0/24"
user_agent string
The User-Agent header of the device that opened the email
Example: "Mozilla/5.0 (Linux)"
read_secs integer, default is "1"
The appromixate number of seconds the email was read for
Example: "15"
total_clicks integer
The number of times links in this email have been clicked
Example: 5
clicks [object]
An array of click information objects
clicked_at string
The ISO-8601-formatted timestamp indicating when the link in the email was clicked
Example: "2021-05-20T00:00:00"
ip_address string
The IP address of the client that opened the link
Example: "192.0.2.0/24"
user_agent string
The user-agent header of the device that opened the link
Example: "Mozilla/5.0 (Linux)"
url string
The URL of the link clicked
Example: "example@example.com"
status_counts object
If status_counts was true on the input data, this will be an object with keys of each unique status found and the number of emails with that status
Example: "[\"status_counts\": [\"delivered\": 206, \"defer\": 53, \"spam\": 1, \"refused\": 3]]"
continue_token string
A token that can be passed in order to continue this query
Example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdCI6eyJvZmYiOjUsInFpZCI6MX0XXXX"

Sender Domains

A POST command allows you to undertake the administration of email domains. Manage sender domains for your account to allow emails to be properly authenticated and improve delivery rates.

Add Sender Domain

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "subaccount_id" => "bKj21",
  "domain" => "example.com",
  "tracking_subdomain" => "track",
  "returnpath_subdomain" => "return",
  "auto_verify" => false,
}

result = RestClient.post 'https://api.smtp2go.com/v3/domain/add', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "domain": "example.com",
  "tracking_subdomain": "track",
  "returnpath_subdomain": "return",
  "auto_verify": false
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/domain/add', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "subaccount_id": "bKj21",
    "domain": "example.com",
    "tracking_subdomain": "track",
    "returnpath_subdomain": "return",
    "auto_verify": false,
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/domain/add", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "domain": "example.com",
  "tracking_subdomain": "track",
  "returnpath_subdomain": "return",
  "auto_verify": False,
})

r = requests.post('https://api.smtp2go.com/v3/domain/add', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("subaccount_id", string("bKj21")),
      field("domain", string("example.com")),
      field("tracking_subdomain", string("track")),
      field("returnpath_subdomain", string("return")),
      field("auto_verify", falseNode())
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/domain/add")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/domain/add"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"subaccount_id", "bKj21"},
            {"domain", "example.com"},
            {"tracking_subdomain", "track"},
            {"returnpath_subdomain", "return"},
            {"auto_verify", false},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/domain/add

This endpoint adds a sender domain to your account. Only add domains that you own, as you will be required to update your DNS records.

Parameters

api_key required string
Example: "api-700B************************8F4E"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"
domain required string
Domain to add as a sending domain (can be a top-level domain or a subdomain)
Example: "example.com"
tracking_subdomain string, default is "link"
A subdomain to use as a tracking subdomain (used for click/open tracking and unsubscribe lists)
Example: "track"
returnpath_subdomain string
A subdomain to use as return-path subdomain
Example: "return"
auto_verify boolean, default is "false"
If true, the domain will be automatically verified without requiring an additional call to the Verify endpoint

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "domains": [
      {
        "domain": {
          "fulldomain": "example.com",
          "subdomain": "example@example.com",
          "domain": "example.com",
          "suffix": "com",
          "dkim_selector": "s12345._domainkey",
          "dkim_verified": false,
          "dkim_status": "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
          "dkim_value": "dkim.smtp2go.net",
          "rpath_selector": "em12345",
          "rpath_verified": false,
          "rpath_status": "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
          "rpath_value": "return.smtp2go.net"
        },
        "trackers": "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – sender domain added to account

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
domains [SenderDomainActionResponse]
A list of domains that were returned by the last action
domain SenderDomainSchema
An object holding sender domain information
fulldomain string
The full sender domain name
Example: "example.com"
subdomain string
The subdomain value of the sender domain
Example: "example@example.com"
domain string
The domain value of the sender domain
Example: "example.com"
suffix string
The suffix value of the sender domain
Example: "com"
dkim_selector string
The domain’s DKIM selector
Example: "s12345._domainkey"
dkim_verified boolean
A flag indicating whether this domain has DKIM verified
dkim_status string
A string containing the last error if DKIM verification failed
Example: "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
dkim_value string
A string containing the last known value of the DKIM TXT record
Example: "dkim.smtp2go.net"
rpath_selector string
The domain’s return path selector
Example: "em12345"
rpath_verified boolean
A flag indicating whether this domain has RPATH verified
rpath_status string
A string containing the last error if RPATH verification failed
Example: "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
rpath_value string
A string containing the last known value of the RPATH CNAME record
Example: "return.smtp2go.net"
trackers [SenderDomainTrackerSchema]
List of trackers assigned to a domain
Example: "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
fulldomain string
The full tracking domain value
Example: "example"
subdomain string
The tracking subdomain value
Example: "link"
domain string
The primary domain
Example: "example.com"
suffix string
The domain suffix
Example: "com"
cname_verified boolean, default is "false"
A flag indicating whether or not this tracking subdomain has a CNAME record pointing to track.smtp2go.com
cname_status string
A status string or error message with the current status of the verification
Example: "Lookup CNAME(link.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
cname_value string
A string with the current value of the CNAME record for this subdomain
Example: "track.smtp2go.net"
enabled boolean
A boolean flag indicating whether this tracking domain is currenly enabled
ssl_status string
A string indicating the current SSL status of the tracking domain, or 'issued: [unix_secs]' if already issued
Example: "An SSL certificate has been requested and will be enabled shortly"

Remove Sender Domain

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "domain" => "begone.com",
  "subaccount_id" => "bKj21",
}

result = RestClient.post 'https://api.smtp2go.com/v3/domain/remove', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "domain": "begone.com",
  "subaccount_id": "bKj21"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/domain/remove', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "domain": "begone.com",
    "subaccount_id": "bKj21",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/domain/remove", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "domain": "begone.com",
  "subaccount_id": "bKj21",
})

r = requests.post('https://api.smtp2go.com/v3/domain/remove', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("domain", string("begone.com")),
      field("subaccount_id", string("bKj21"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/domain/remove")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/domain/remove"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"domain", "begone.com"},
            {"subaccount_id", "bKj21"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/domain/remove

This endpoint removes a sender domain from your account.

Parameters

api_key required string
Example: "api-700B************************8F4E"
domain required string
Domain to remove
Example: "begone.com"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – sender domain removed from account

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"

Modify Return Subdomain

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "subaccount_id" => "bKj21",
  "domain" => "example.com",
  "old_subdomain" => "em12345",
  "new_subdomain" => "returns",
}

result = RestClient.post 'https://api.smtp2go.com/v3/domain/returnpath', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "domain": "example.com",
  "old_subdomain": "em12345",
  "new_subdomain": "returns"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/domain/returnpath', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "subaccount_id": "bKj21",
    "domain": "example.com",
    "old_subdomain": "em12345",
    "new_subdomain": "returns",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/domain/returnpath", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "domain": "example.com",
  "old_subdomain": "em12345",
  "new_subdomain": "returns",
})

r = requests.post('https://api.smtp2go.com/v3/domain/returnpath', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("subaccount_id", string("bKj21")),
      field("domain", string("example.com")),
      field("old_subdomain", string("em12345")),
      field("new_subdomain", string("returns"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/domain/returnpath")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/domain/returnpath"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"subaccount_id", "bKj21"},
            {"domain", "example.com"},
            {"old_subdomain", "em12345"},
            {"new_subdomain", "returns"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/domain/returnpath

This endpoint renames a return-path subdomain for the specified sender domain. The return path has a default that may be reset. The default value for the return path is em[member_id], i.e. for domain "example.com", the default path becomes em[member_id].example.com.

Parameters

api_key required string
Example: "api-700B************************8F4E"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"
domain required string
Domain to update
Example: "example.com"
old_subdomain required string, default is "link"
The domain’s old return-path subdomain
Example: "em12345"
new_subdomain required string
The domain’s new return-path subdomain
Example: "returns"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "domains": [
      {
        "domain": {
          "fulldomain": "example.com",
          "subdomain": "example@example.com",
          "domain": "example.com",
          "suffix": "com",
          "dkim_selector": "s12345._domainkey",
          "dkim_verified": false,
          "dkim_status": "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
          "dkim_value": "dkim.smtp2go.net",
          "rpath_selector": "em12345",
          "rpath_verified": false,
          "rpath_status": "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
          "rpath_value": "return.smtp2go.net"
        },
        "trackers": "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – domain return-path modified

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
domains [SenderDomainActionResponse]
A list of domains that were modified by the last action
domain SenderDomainSchema
An object holding sender domain information
fulldomain string
The full sender domain name
Example: "example.com"
subdomain string
The subdomain value of the sender domain
Example: "example@example.com"
domain string
The domain value of the sender domain
Example: "example.com"
suffix string
The suffix value of the sender domain
Example: "com"
dkim_selector string
The domain’s DKIM selector
Example: "s12345._domainkey"
dkim_verified boolean
A flag indicating whether this domain has DKIM verified
dkim_status string
A string containing the last error if DKIM verification failed
Example: "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
dkim_value string
A string containing the last known value of the DKIM TXT record
Example: "dkim.smtp2go.net"
rpath_selector string
The domain’s return path selector
Example: "em12345"
rpath_verified boolean
A flag indicating whether this domain has RPATH verified
rpath_status string
A string containing the last error if RPATH verification failed
Example: "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
rpath_value string
A string containing the last known value of the RPATH CNAME record
Example: "return.smtp2go.net"
trackers [SenderDomainTrackerSchema]
List of trackers assigned to a domain
Example: "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
fulldomain string
The full tracking domain value
Example: "example"
subdomain string
The tracking subdomain value
Example: "link"
domain string
The primary domain
Example: "example.com"
suffix string
The domain suffix
Example: "com"
cname_verified boolean, default is "false"
A flag indicating whether or not this tracking subdomain has a CNAME record pointing to track.smtp2go.com
cname_status string
A status string or error message with the current status of the verification
Example: "Lookup CNAME(link.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
cname_value string
A string with the current value of the CNAME record for this subdomain
Example: "track.smtp2go.net"
enabled boolean
A boolean flag indicating whether this tracking domain is currenly enabled
ssl_status string
A string indicating the current SSL status of the tracking domain, or 'issued: [unix_secs]' if already issued
Example: "An SSL certificate has been requested and will be enabled shortly"

Modify Tracking Domain

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "subaccount_id" => "bKj21",
  "domain" => "example.com",
  "old_subdomain" => "link",
  "new_subdomain" => "track",
}

result = RestClient.post 'https://api.smtp2go.com/v3/domain/tracking', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "domain": "example.com",
  "old_subdomain": "link",
  "new_subdomain": "track"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/domain/tracking', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "subaccount_id": "bKj21",
    "domain": "example.com",
    "old_subdomain": "link",
    "new_subdomain": "track",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/domain/tracking", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "domain": "example.com",
  "old_subdomain": "link",
  "new_subdomain": "track",
})

r = requests.post('https://api.smtp2go.com/v3/domain/tracking', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("subaccount_id", string("bKj21")),
      field("domain", string("example.com")),
      field("old_subdomain", string("link")),
      field("new_subdomain", string("track"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/domain/tracking")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/domain/tracking"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"subaccount_id", "bKj21"},
            {"domain", "example.com"},
            {"old_subdomain", "link"},
            {"new_subdomain", "track"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/domain/tracking

This endpoint renames a tracking subdomain for the specified sender domain. The tracking subdomain has a default that may be reset. The default value for the tracking subdomain is "link", i.e. for domain "example.com" with a subdomain "link", the resultant path becomes link.example.com.

Parameters

api_key required string
Example: "api-700B************************8F4E"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"
domain required string
Domain to update
Example: "example.com"
old_subdomain required string, default is "link"
The domain’s old return-path subdomain
Example: "link"
new_subdomain required string
The domain’s desired new return-path subdomain
Example: "track"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "domains": [
      {
        "domain": {
          "fulldomain": "example.com",
          "subdomain": "example@example.com",
          "domain": "example.com",
          "suffix": "com",
          "dkim_selector": "s12345._domainkey",
          "dkim_verified": false,
          "dkim_status": "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
          "dkim_value": "dkim.smtp2go.net",
          "rpath_selector": "em12345",
          "rpath_verified": false,
          "rpath_status": "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
          "rpath_value": "return.smtp2go.net"
        },
        "trackers": "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – tracking subdomain modified

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
domains [SenderDomainActionResponse]
A list of domains that were modified by the last action
domain SenderDomainSchema
An object holding sender domain information
fulldomain string
The full sender domain name
Example: "example.com"
subdomain string
The subdomain value of the sender domain
Example: "example@example.com"
domain string
The domain value of the sender domain
Example: "example.com"
suffix string
The suffix value of the sender domain
Example: "com"
dkim_selector string
The domain’s DKIM selector
Example: "s12345._domainkey"
dkim_verified boolean
A flag indicating whether this domain has DKIM verified
dkim_status string
A string containing the last error if DKIM verification failed
Example: "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
dkim_value string
A string containing the last known value of the DKIM TXT record
Example: "dkim.smtp2go.net"
rpath_selector string
The domain’s return path selector
Example: "em12345"
rpath_verified boolean
A flag indicating whether this domain has RPATH verified
rpath_status string
A string containing the last error if RPATH verification failed
Example: "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
rpath_value string
A string containing the last known value of the RPATH CNAME record
Example: "return.smtp2go.net"
trackers [SenderDomainTrackerSchema]
List of trackers assigned to a domain
Example: "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
fulldomain string
The full tracking domain value
Example: "example"
subdomain string
The tracking subdomain value
Example: "link"
domain string
The primary domain
Example: "example.com"
suffix string
The domain suffix
Example: "com"
cname_verified boolean, default is "false"
A flag indicating whether or not this tracking subdomain has a CNAME record pointing to track.smtp2go.com
cname_status string
A status string or error message with the current status of the verification
Example: "Lookup CNAME(link.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
cname_value string
A string with the current value of the CNAME record for this subdomain
Example: "track.smtp2go.net"
enabled boolean
A boolean flag indicating whether this tracking domain is currenly enabled
ssl_status string
A string indicating the current SSL status of the tracking domain, or 'issued: [unix_secs]' if already issued
Example: "An SSL certificate has been requested and will be enabled shortly"

Verify Sender Domain

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "subaccount_id" => "bKj21",
  "domain" => "example.com",
  "requisition_ssl" => false,
}

result = RestClient.post 'https://api.smtp2go.com/v3/domain/verify', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "domain": "example.com",
  "requisition_ssl": false
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/domain/verify', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "subaccount_id": "bKj21",
    "domain": "example.com",
    "requisition_ssl": false,
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/domain/verify", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
  "domain": "example.com",
  "requisition_ssl": False,
})

r = requests.post('https://api.smtp2go.com/v3/domain/verify', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("subaccount_id", string("bKj21")),
      field("domain", string("example.com")),
      field("requisition_ssl", falseNode())
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/domain/verify")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/domain/verify"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"subaccount_id", "bKj21"},
            {"domain", "example.com"},
            {"requisition_ssl", false},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/domain/verify

This endpoint verifies a sender domain on your account.

Parameters

api_key required string
Example: "api-700B************************8F4E"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"
domain required string
Domain to verify
Example: "example.com"
requisition_ssl boolean, default is "false"
If passed, an SSL certificate will be requisitioned for the tracking domain to enable HTTPS links

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "domains": [
      {
        "domain": {
          "fulldomain": "example.com",
          "subdomain": "example@example.com",
          "domain": "example.com",
          "suffix": "com",
          "dkim_selector": "s12345._domainkey",
          "dkim_verified": false,
          "dkim_status": "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
          "dkim_value": "dkim.smtp2go.net",
          "rpath_selector": "em12345",
          "rpath_verified": false,
          "rpath_status": "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
          "rpath_value": "return.smtp2go.net"
        },
        "trackers": "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – domain verification status returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
domains [SenderDomainActionResponse]
A list of domains and their states following verification
domain SenderDomainSchema
An object holding sender domain information
fulldomain string
The full sender domain name
Example: "example.com"
subdomain string
The subdomain value of the sender domain
Example: "example@example.com"
domain string
The domain value of the sender domain
Example: "example.com"
suffix string
The suffix value of the sender domain
Example: "com"
dkim_selector string
The domain’s DKIM selector
Example: "s12345._domainkey"
dkim_verified boolean
A flag indicating whether this domain has DKIM verified
dkim_status string
A string containing the last error if DKIM verification failed
Example: "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
dkim_value string
A string containing the last known value of the DKIM TXT record
Example: "dkim.smtp2go.net"
rpath_selector string
The domain’s return path selector
Example: "em12345"
rpath_verified boolean
A flag indicating whether this domain has RPATH verified
rpath_status string
A string containing the last error if RPATH verification failed
Example: "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
rpath_value string
A string containing the last known value of the RPATH CNAME record
Example: "return.smtp2go.net"
trackers [SenderDomainTrackerSchema]
List of trackers assigned to a domain
Example: "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
fulldomain string
The full tracking domain value
Example: "example"
subdomain string
The tracking subdomain value
Example: "link"
domain string
The primary domain
Example: "example.com"
suffix string
The domain suffix
Example: "com"
cname_verified boolean, default is "false"
A flag indicating whether or not this tracking subdomain has a CNAME record pointing to track.smtp2go.com
cname_status string
A status string or error message with the current status of the verification
Example: "Lookup CNAME(link.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
cname_value string
A string with the current value of the CNAME record for this subdomain
Example: "track.smtp2go.net"
enabled boolean
A boolean flag indicating whether this tracking domain is currenly enabled
ssl_status string
A string indicating the current SSL status of the tracking domain, or 'issued: [unix_secs]' if already issued
Example: "An SSL certificate has been requested and will be enabled shortly"

View Sender Domains

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "subaccount_id" => "bKj21",
}

result = RestClient.post 'https://api.smtp2go.com/v3/domain/view', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/domain/view', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "subaccount_id": "bKj21",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/domain/view", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "subaccount_id": "bKj21",
})

r = requests.post('https://api.smtp2go.com/v3/domain/view', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("subaccount_id", string("bKj21"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/domain/view")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/domain/view"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"subaccount_id", "bKj21"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/domain/view

This endpoint returns a list of sender domains on your account.

Parameters

api_key required string
Example: "api-700B************************8F4E"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "domains": [
      {
        "domain": {
          "fulldomain": "example.com",
          "subdomain": "example@example.com",
          "domain": "example.com",
          "suffix": "com",
          "dkim_selector": "s12345._domainkey",
          "dkim_verified": false,
          "dkim_status": "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
          "dkim_value": "dkim.smtp2go.net",
          "rpath_selector": "em12345",
          "rpath_verified": false,
          "rpath_status": "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
          "rpath_value": "return.smtp2go.net"
        },
        "trackers": "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – sender domain/s returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
domains [SenderDomainActionResponse]
A list of domains
domain SenderDomainSchema
An object holding sender domain information
fulldomain string
The full sender domain name
Example: "example.com"
subdomain string
The subdomain value of the sender domain
Example: "example@example.com"
domain string
The domain value of the sender domain
Example: "example.com"
suffix string
The suffix value of the sender domain
Example: "com"
dkim_selector string
The domain’s DKIM selector
Example: "s12345._domainkey"
dkim_verified boolean
A flag indicating whether this domain has DKIM verified
dkim_status string
A string containing the last error if DKIM verification failed
Example: "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
dkim_value string
A string containing the last known value of the DKIM TXT record
Example: "dkim.smtp2go.net"
rpath_selector string
The domain’s return path selector
Example: "em12345"
rpath_verified boolean
A flag indicating whether this domain has RPATH verified
rpath_status string
A string containing the last error if RPATH verification failed
Example: "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
rpath_value string
A string containing the last known value of the RPATH CNAME record
Example: "return.smtp2go.net"
trackers [SenderDomainTrackerSchema]
List of trackers assigned to a domain
Example: "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
fulldomain string
The full tracking domain value
Example: "example"
subdomain string
The tracking subdomain value
Example: "link"
domain string
The primary domain
Example: "example.com"
suffix string
The domain suffix
Example: "com"
cname_verified boolean, default is "false"
A flag indicating whether or not this tracking subdomain has a CNAME record pointing to track.smtp2go.com
cname_status string
A status string or error message with the current status of the verification
Example: "Lookup CNAME(link.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
cname_value string
A string with the current value of the CNAME record for this subdomain
Example: "track.smtp2go.net"
enabled boolean
A boolean flag indicating whether this tracking domain is currenly enabled
ssl_status string
A string indicating the current SSL status of the tracking domain, or 'issued: [unix_secs]' if already issued
Example: "An SSL certificate has been requested and will be enabled shortly"

SMTP Users

A POST command allows you to manage the SMTP users in your account.

View SMTP Users

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "username" => "authuser",
}

result = RestClient.post 'https://api.smtp2go.com/v3/users/smtp/view', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "username": "authuser"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/users/smtp/view', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "username": "authuser",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/users/smtp/view", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "username": "authuser",
})

r = requests.post('https://api.smtp2go.com/v3/users/smtp/view', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("username", string("authuser"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/users/smtp/view")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/users/smtp/view"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"username", "authuser"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/users/smtp/view

This endpoint returns a list of SMTP users associated with your account.

Parameters

api_key required string
Example: "api-700B************************8F4E"
username string
Optional username to search for
Example: "authuser"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "results": [
      {
        "username": "authuser",
        "email_password": "pa$$word!1<-dontusethis-ever",
        "comments": "Head of marketing",
        "custom_ratelimit": false,
        "custom_ratelimit_value": 10000,
        "custom_ratelimit_period": "3600",
        "description": "Active since 082021",
        "feedback_enabled": false,
        "feedback_domain": "example.com",
        "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
        "feedback_text": "This month's deals.",
        "archive_enabled": false,
        "open_tracking_enabled": false,
        "audit_email": "test-email-2@example.com"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – SMTP user data returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
results [SMTPUserSchema]
A list of SMTP users
username required string
A valid SMTP2GO username to add to your account
Example: "authuser"
email_password required string
The password for this user when sending email
Example: "pa$$word!1<-dontusethis-ever"
comments string
Optional comments to attach to the user
Example: "Head of marketing"
custom_ratelimit boolean, default is "false"
Whether this user has a custom rate limit
custom_ratelimit_value integer
If custom_ratelimit is true, how many emails this user can send in the period specified in custom_ratelimit_period
Example: 10000
custom_ratelimit_period string
If custom_ratelimit is true, the period over which the user will be limited to the number of emails specified in custom_ratelimit_value. See custom rate limits for further information.
Example: "3600"
description string
Any comment or additional information about this user
Example: "Active since 082021"
feedback_enabled boolean, default is "false"
Are custom feedback inserts specified?
feedback_domain string
The domain to insert into the custom feedback links
Example: "example.com"
feedback_html string
HTML content to use in text/html email body
Example: "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>"
feedback_text string
Text content to use in text/plain email body
Example: "This month's deals."
archive_enabled boolean, default is "false"
Is archiving enabled for this user?
open_tracking_enabled boolean, default is "false"
Is open tracking enabled for this user?
audit_email string
Bcc address for this user key
Example: "test-email-2@example.com"

Add SMTP User

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "user_data" => {
    "username" => "authuser",
    "email_password" => "pa$$word!1<-dontusethis-ever",
    "comments" => "Head of marketing",
    "custom_ratelimit" => false,
    "custom_ratelimit_value" => 10000,
    "custom_ratelimit_period" => "3600",
    "description" => "Active since 082021",
    "feedback_enabled" => false,
    "feedback_domain" => "example.com",
    "feedback_html" => "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
    "feedback_text" => "This month's deals.",
    "archive_enabled" => false,
    "open_tracking_enabled" => false,
    "audit_email" => "test-email-2@example.com",
  },
}

result = RestClient.post 'https://api.smtp2go.com/v3/users/smtp/add', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "user_data": {
    "username": "authuser",
    "email_password": "pa$$word!1<-dontusethis-ever",
    "comments": "Head of marketing",
    "custom_ratelimit": false,
    "custom_ratelimit_value": 10000,
    "custom_ratelimit_period": "3600",
    "description": "Active since 082021",
    "feedback_enabled": false,
    "feedback_domain": "example.com",
    "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
    "feedback_text": "This month's deals.",
    "archive_enabled": false,
    "open_tracking_enabled": false,
    "audit_email": "test-email-2@example.com"
  }
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/users/smtp/add', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "user_data": map[string]interface{}{
      "username": "authuser",
      "email_password": "pa$$word!1<-dontusethis-ever",
      "comments": "Head of marketing",
      "custom_ratelimit": false,
      "custom_ratelimit_value": 10000,
      "custom_ratelimit_period": "3600",
      "description": "Active since 082021",
      "feedback_enabled": false,
      "feedback_domain": "example.com",
      "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
      "feedback_text": "This month's deals.",
      "archive_enabled": false,
      "open_tracking_enabled": false,
      "audit_email": "test-email-2@example.com",
    },
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/users/smtp/add", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "user_data": {
    "username": "authuser",
    "email_password": "pa$$word!1<-dontusethis-ever",
    "comments": "Head of marketing",
    "custom_ratelimit": False,
    "custom_ratelimit_value": 10000,
    "custom_ratelimit_period": "3600",
    "description": "Active since 082021",
    "feedback_enabled": False,
    "feedback_domain": "example.com",
    "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
    "feedback_text": "This month's deals.",
    "archive_enabled": False,
    "open_tracking_enabled": False,
    "audit_email": "test-email-2@example.com",
  },
})

r = requests.post('https://api.smtp2go.com/v3/users/smtp/add', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("user_data", object(
        field("username", string("authuser")),
        field("email_password", string("pa$$word!1<-dontusethis-ever")),
        field("comments", string("Head of marketing")),
        field("custom_ratelimit", falseNode()),
        field("custom_ratelimit_value", number(10000)),
        field("custom_ratelimit_period", string("3600")),
        field("description", string("Active since 082021")),
        field("feedback_enabled", falseNode()),
        field("feedback_domain", string("example.com")),
        field("feedback_html", string("<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>")),
        field("feedback_text", string("This month's deals.")),
        field("archive_enabled", falseNode()),
        field("open_tracking_enabled", falseNode()),
        field("audit_email", string("test-email-2@example.com"))
      ))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/users/smtp/add")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/users/smtp/add"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"user_data", new Dictionary<string, dynamic>{
              {"username", "authuser"},
              {"email_password", "pa$$word!1<-dontusethis-ever"},
              {"comments", "Head of marketing"},
              {"custom_ratelimit", false},
              {"custom_ratelimit_value", 10000},
              {"custom_ratelimit_period", "3600"},
              {"description", "Active since 082021"},
              {"feedback_enabled", false},
              {"feedback_domain", "example.com"},
              {"feedback_html", "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>"},
              {"feedback_text", "This month's deals."},
              {"archive_enabled", false},
              {"open_tracking_enabled", false},
              {"audit_email", "test-email-2@example.com"},
            }},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/users/smtp/add

This endpoint adds a new SMTP user.

Parameters

api_key required string
Example: "api-700B************************8F4E"
user_data SMTPUserSchema
An SMTP user’s details
username required string
A valid SMTP2GO username to add to your account
Example: "authuser"
email_password required string
The password for this user when sending email
Example: "pa$$word!1<-dontusethis-ever"
comments string
Optional comments to attach to the user
Example: "Head of marketing"
custom_ratelimit boolean, default is "false"
Whether this user has a custom rate limit
custom_ratelimit_value integer
If custom_ratelimit is true, how many emails this user can send in the period specified in custom_ratelimit_period
Example: 10000
custom_ratelimit_period string
If custom_ratelimit is true, the period over which the user will be limited to the number of emails specified in custom_ratelimit_value. See custom rate limits for further information.
Example: "3600"
description string
Any comment or additional information about this user
Example: "Active since 082021"
feedback_enabled boolean, default is "false"
Are custom feedback inserts specified?
feedback_domain string
The domain to insert into the custom feedback links
Example: "example.com"
feedback_html string
HTML content to use in text/html email body
Example: "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>"
feedback_text string
Text content to use in text/plain email body
Example: "This month's deals."
archive_enabled boolean, default is "false"
Is archiving enabled for this user?
open_tracking_enabled boolean, default is "false"
Is open tracking enabled for this user?
audit_email string
Bcc address for this user key
Example: "test-email-2@example.com"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "results": [
      {
        "username": "authuser",
        "email_password": "pa$$word!1<-dontusethis-ever",
        "comments": "Head of marketing",
        "custom_ratelimit": false,
        "custom_ratelimit_value": 10000,
        "custom_ratelimit_period": "3600",
        "description": "Active since 082021",
        "feedback_enabled": false,
        "feedback_domain": "example.com",
        "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
        "feedback_text": "This month's deals.",
        "archive_enabled": false,
        "open_tracking_enabled": false,
        "audit_email": "test-email-2@example.com"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – user added

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
results [SMTPUserSchema]
An array containing the added SMTP user details
username required string
A valid SMTP2GO username to add to your account
Example: "authuser"
email_password required string
The password for this user when sending email
Example: "pa$$word!1<-dontusethis-ever"
comments string
Optional comments to attach to the user
Example: "Head of marketing"
custom_ratelimit boolean, default is "false"
Whether this user has a custom rate limit
custom_ratelimit_value integer
If custom_ratelimit is true, how many emails this user can send in the period specified in custom_ratelimit_period
Example: 10000
custom_ratelimit_period string
If custom_ratelimit is true, the period over which the user will be limited to the number of emails specified in custom_ratelimit_value. See custom rate limits for further information.
Example: "3600"
description string
Any comment or additional information about this user
Example: "Active since 082021"
feedback_enabled boolean, default is "false"
Are custom feedback inserts specified?
feedback_domain string
The domain to insert into the custom feedback links
Example: "example.com"
feedback_html string
HTML content to use in text/html email body
Example: "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>"
feedback_text string
Text content to use in text/plain email body
Example: "This month's deals."
archive_enabled boolean, default is "false"
Is archiving enabled for this user?
open_tracking_enabled boolean, default is "false"
Is open tracking enabled for this user?
audit_email string
Bcc address for this user key
Example: "test-email-2@example.com"

Edit SMTP User

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "user_data" => {
    "username" => "authuser",
    "email_password" => "pa$$word!1<-dontusethis-ever",
    "comments" => "Head of marketing",
    "custom_ratelimit" => false,
    "custom_ratelimit_value" => 10000,
    "custom_ratelimit_period" => "3600",
    "description" => "Active since 082021",
    "feedback_enabled" => false,
    "feedback_domain" => "example.com",
    "feedback_html" => "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
    "feedback_text" => "This month's deals.",
    "archive_enabled" => false,
    "open_tracking_enabled" => false,
    "audit_email" => "test-email-2@example.com",
  },
}

result = RestClient.post 'https://api.smtp2go.com/v3/users/smtp/edit', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "user_data": {
    "username": "authuser",
    "email_password": "pa$$word!1<-dontusethis-ever",
    "comments": "Head of marketing",
    "custom_ratelimit": false,
    "custom_ratelimit_value": 10000,
    "custom_ratelimit_period": "3600",
    "description": "Active since 082021",
    "feedback_enabled": false,
    "feedback_domain": "example.com",
    "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
    "feedback_text": "This month's deals.",
    "archive_enabled": false,
    "open_tracking_enabled": false,
    "audit_email": "test-email-2@example.com"
  }
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/users/smtp/edit', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "user_data": map[string]interface{}{
      "username": "authuser",
      "email_password": "pa$$word!1<-dontusethis-ever",
      "comments": "Head of marketing",
      "custom_ratelimit": false,
      "custom_ratelimit_value": 10000,
      "custom_ratelimit_period": "3600",
      "description": "Active since 082021",
      "feedback_enabled": false,
      "feedback_domain": "example.com",
      "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
      "feedback_text": "This month's deals.",
      "archive_enabled": false,
      "open_tracking_enabled": false,
      "audit_email": "test-email-2@example.com",
    },
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/users/smtp/edit", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "user_data": {
    "username": "authuser",
    "email_password": "pa$$word!1<-dontusethis-ever",
    "comments": "Head of marketing",
    "custom_ratelimit": False,
    "custom_ratelimit_value": 10000,
    "custom_ratelimit_period": "3600",
    "description": "Active since 082021",
    "feedback_enabled": False,
    "feedback_domain": "example.com",
    "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
    "feedback_text": "This month's deals.",
    "archive_enabled": False,
    "open_tracking_enabled": False,
    "audit_email": "test-email-2@example.com",
  },
})

r = requests.post('https://api.smtp2go.com/v3/users/smtp/edit', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("user_data", object(
        field("username", string("authuser")),
        field("email_password", string("pa$$word!1<-dontusethis-ever")),
        field("comments", string("Head of marketing")),
        field("custom_ratelimit", falseNode()),
        field("custom_ratelimit_value", number(10000)),
        field("custom_ratelimit_period", string("3600")),
        field("description", string("Active since 082021")),
        field("feedback_enabled", falseNode()),
        field("feedback_domain", string("example.com")),
        field("feedback_html", string("<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>")),
        field("feedback_text", string("This month's deals.")),
        field("archive_enabled", falseNode()),
        field("open_tracking_enabled", falseNode()),
        field("audit_email", string("test-email-2@example.com"))
      ))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/users/smtp/edit")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/users/smtp/edit"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"user_data", new Dictionary<string, dynamic>{
              {"username", "authuser"},
              {"email_password", "pa$$word!1<-dontusethis-ever"},
              {"comments", "Head of marketing"},
              {"custom_ratelimit", false},
              {"custom_ratelimit_value", 10000},
              {"custom_ratelimit_period", "3600"},
              {"description", "Active since 082021"},
              {"feedback_enabled", false},
              {"feedback_domain", "example.com"},
              {"feedback_html", "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>"},
              {"feedback_text", "This month's deals."},
              {"archive_enabled", false},
              {"open_tracking_enabled", false},
              {"audit_email", "test-email-2@example.com"},
            }},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/users/smtp/edit

This endpoint edits an SMTP user’s details.

Parameters

api_key required string
Example: "api-700B************************8F4E"
user_data SMTPUserSchema
An SMTP user’s details
username required string
A valid SMTP2GO username to add to your account
Example: "authuser"
email_password required string
The password for this user when sending email
Example: "pa$$word!1<-dontusethis-ever"
comments string
Optional comments to attach to the user
Example: "Head of marketing"
custom_ratelimit boolean, default is "false"
Whether this user has a custom rate limit
custom_ratelimit_value integer
If custom_ratelimit is true, how many emails this user can send in the period specified in custom_ratelimit_period
Example: 10000
custom_ratelimit_period string
If custom_ratelimit is true, the period over which the user will be limited to the number of emails specified in custom_ratelimit_value. See custom rate limits for further information.
Example: "3600"
description string
Any comment or additional information about this user
Example: "Active since 082021"
feedback_enabled boolean, default is "false"
Are custom feedback inserts specified?
feedback_domain string
The domain to insert into the custom feedback links
Example: "example.com"
feedback_html string
HTML content to use in text/html email body
Example: "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>"
feedback_text string
Text content to use in text/plain email body
Example: "This month's deals."
archive_enabled boolean, default is "false"
Is archiving enabled for this user?
open_tracking_enabled boolean, default is "false"
Is open tracking enabled for this user?
audit_email string
Bcc address for this user key
Example: "test-email-2@example.com"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "results": [
      {
        "username": "authuser",
        "email_password": "pa$$word!1<-dontusethis-ever",
        "comments": "Head of marketing",
        "custom_ratelimit": false,
        "custom_ratelimit_value": 10000,
        "custom_ratelimit_period": "3600",
        "description": "Active since 082021",
        "feedback_enabled": false,
        "feedback_domain": "example.com",
        "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
        "feedback_text": "This month's deals.",
        "archive_enabled": false,
        "open_tracking_enabled": false,
        "audit_email": "test-email-2@example.com"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – user details updated

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
results [SMTPUserSchema]
An array containing the edited SMTP user’s details
username required string
A valid SMTP2GO username to add to your account
Example: "authuser"
email_password required string
The password for this user when sending email
Example: "pa$$word!1<-dontusethis-ever"
comments string
Optional comments to attach to the user
Example: "Head of marketing"
custom_ratelimit boolean, default is "false"
Whether this user has a custom rate limit
custom_ratelimit_value integer
If custom_ratelimit is true, how many emails this user can send in the period specified in custom_ratelimit_period
Example: 10000
custom_ratelimit_period string
If custom_ratelimit is true, the period over which the user will be limited to the number of emails specified in custom_ratelimit_value. See custom rate limits for further information.
Example: "3600"
description string
Any comment or additional information about this user
Example: "Active since 082021"
feedback_enabled boolean, default is "false"
Are custom feedback inserts specified?
feedback_domain string
The domain to insert into the custom feedback links
Example: "example.com"
feedback_html string
HTML content to use in text/html email body
Example: "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>"
feedback_text string
Text content to use in text/plain email body
Example: "This month's deals."
archive_enabled boolean, default is "false"
Is archiving enabled for this user?
open_tracking_enabled boolean, default is "false"
Is open tracking enabled for this user?
audit_email string
Bcc address for this user key
Example: "test-email-2@example.com"

Remove SMTP User

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "username" => "unauthuser",
}

result = RestClient.post 'https://api.smtp2go.com/v3/users/smtp/remove', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "username": "unauthuser"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/users/smtp/remove', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "username": "unauthuser",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/users/smtp/remove", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "username": "unauthuser",
})

r = requests.post('https://api.smtp2go.com/v3/users/smtp/remove', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("username", string("unauthuser"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/users/smtp/remove")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/users/smtp/remove"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"username", "unauthuser"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/users/smtp/remove

This endpoint removes an SMTP user from your account.

Parameters

api_key required string
Example: "api-700B************************8F4E"
username required string
The username of an existing account user you want to remove
Example: "unauthuser"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "results": [
      {
        "username": "authuser",
        "email_password": "pa$$word!1<-dontusethis-ever",
        "comments": "Head of marketing",
        "custom_ratelimit": false,
        "custom_ratelimit_value": 10000,
        "custom_ratelimit_period": "3600",
        "description": "Active since 082021",
        "feedback_enabled": false,
        "feedback_domain": "example.com",
        "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
        "feedback_text": "This month's deals.",
        "archive_enabled": false,
        "open_tracking_enabled": false,
        "audit_email": "test-email-2@example.com"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – user removed

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
results [SMTPUserSchema]
An array containing the removed SMTP User
username required string
A valid SMTP2GO username to add to your account
Example: "authuser"
email_password required string
The password for this user when sending email
Example: "pa$$word!1<-dontusethis-ever"
comments string
Optional comments to attach to the user
Example: "Head of marketing"
custom_ratelimit boolean, default is "false"
Whether this user has a custom rate limit
custom_ratelimit_value integer
If custom_ratelimit is true, how many emails this user can send in the period specified in custom_ratelimit_period
Example: 10000
custom_ratelimit_period string
If custom_ratelimit is true, the period over which the user will be limited to the number of emails specified in custom_ratelimit_value. See custom rate limits for further information.
Example: "3600"
description string
Any comment or additional information about this user
Example: "Active since 082021"
feedback_enabled boolean, default is "false"
Are custom feedback inserts specified?
feedback_domain string
The domain to insert into the custom feedback links
Example: "example.com"
feedback_html string
HTML content to use in text/html email body
Example: "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>"
feedback_text string
Text content to use in text/plain email body
Example: "This month's deals."
archive_enabled boolean, default is "false"
Is archiving enabled for this user?
open_tracking_enabled boolean, default is "false"
Is open tracking enabled for this user?
audit_email string
Bcc address for this user key
Example: "test-email-2@example.com"

Statistics

A POST command allows you to retrieve various statistical reports for your account.

Email Bounces

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
}

result = RestClient.post 'https://api.smtp2go.com/v3/stats/email_bounces', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/stats/email_bounces', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/stats/email_bounces", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
})

r = requests.post('https://api.smtp2go.com/v3/stats/email_bounces', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/stats/email_bounces")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/stats/email_bounces"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/stats/email_bounces

This endpoint provides a report on email bounce statistics.

Parameters

api_key required string
Example: "api-700B************************8F4E"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "emails": 550,
    "rejects": 50,
    "softbounces": 50,
    "hardbounces": 50,
    "bounce_percent": 18
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – report returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
emails integer
The total number of emails sent during the last 30 day period
Example: 550
rejects integer
How many of those sent emails were rejected
Example: 50
softbounces integer
How many of those rejects were softbounces
Example: 50
hardbounces integer
How many of those rejects were hardbounces
Example: 50
bounce_percent string
Percentage of emails sent that bounced
Example: 18

Email Cycle

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
}

result = RestClient.post 'https://api.smtp2go.com/v3/stats/email_cycle', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/stats/email_cycle', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/stats/email_cycle", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
})

r = requests.post('https://api.smtp2go.com/v3/stats/email_cycle', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/stats/email_cycle")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/stats/email_cycle"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/stats/email_cycle

This endpoint returns a summary showing the start date and end date of your monthly cycle, the number of emails sent in this monthly cycle, the number of emails remaining, and the total number of emails in your plan’s monthly allowance.

Parameters

api_key required string
Example: "api-700B************************8F4E"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "cycle_start": "2021-04-01T00:00:00",
    "cycle_end": "2021-05-20T00:00:00",
    "cycle_used": 500,
    "cycle_remaining": 50,
    "cycle_max": 550
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – report returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
cycle_start string
An ISO-8601-formatted datetime containing the start of the monthly cycle
Example: "2021-04-01T00:00:00"
cycle_end string
An ISO-8601-formatted datetime containing the end of the monthly cycle
Example: "2021-05-20T00:00:00"
cycle_used integer
Number of emails that have been sent during this monthly cycle
Example: 500
cycle_remaining integer
The remaining email quota in this monthly cycle
Example: 50
cycle_max integer
The total number of emails that can be sent during this monthly cycle
Example: 550

Email History

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "start_date" => "2021-04-20T00:00:00",
  "end_date" => "2021-04-22T00:00:00",
  "group_by" => "username",
}

result = RestClient.post 'https://api.smtp2go.com/v3/stats/email_history', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "start_date": "2021-04-20T00:00:00",
  "end_date": "2021-04-22T00:00:00",
  "group_by": "username"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/stats/email_history', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "start_date": "2021-04-20T00:00:00",
    "end_date": "2021-04-22T00:00:00",
    "group_by": "username",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/stats/email_history", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "start_date": "2021-04-20T00:00:00",
  "end_date": "2021-04-22T00:00:00",
  "group_by": "username",
})

r = requests.post('https://api.smtp2go.com/v3/stats/email_history', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("start_date", string("2021-04-20T00:00:00")),
      field("end_date", string("2021-04-22T00:00:00")),
      field("group_by", string("username"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/stats/email_history")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/stats/email_history"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"start_date", "2021-04-20T00:00:00"},
            {"end_date", "2021-04-22T00:00:00"},
            {"group_by", "username"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/stats/email_history

This endpoint returns a summary report of account activity across a specified date range (defaults to the last 30 days), grouped by sender email address or SMTP username. The report provides data on various metrics. These include two variables:

api_key required string
Example: "api-700B************************8F4E"
start_date string
ISO-8601-formatted datetime, which defaults to the current date at midnight; applies UTC timezone
Example: "2021-04-20T00:00:00"
end_date string
ISO-8601-formatted datetime, which defaults to 30 days prior to the current date at midnight; applies UTC timezone
Example: "2021-04-22T00:00:00"
group_by required string, default is "username"
Which field to group the results on
Example: "username"
username
email_address

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "count": 10000,
    "history": [
      {
        "used": 0,
        "bytecount": 12345,
        "avgsize": 234,
        "email_address": "marketing@example.com",
        "username": "authuser",
        "lastip": "192.0.2.0/24"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – query results returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
count integer
How many emails were sent in the search period
Example: 10000
history [object]
An array of email history records
used integer
Total count of email impact on quota
bytecount integer
Total size, in bytes, of the combined emails
Example: 12345
avgsize number
Average size, in bytes, of each email
Example: 234
email_address string
The email address used to send
Example: "marketing@example.com"
username string
The username used to send
Example: "authuser"
lastip string
The IP address of the last email sent
Example: "192.0.2.0/24"

Email Spam

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
}

result = RestClient.post 'https://api.smtp2go.com/v3/stats/email_spam', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/stats/email_spam', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/stats/email_spam", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
})

r = requests.post('https://api.smtp2go.com/v3/stats/email_spam', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/stats/email_spam")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/stats/email_spam"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/stats/email_spam

This endpoint returns a report on email spam statistics.

Parameters

api_key required string
Example: "api-700B************************8F4E"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "emails": 550,
    "rejects": 50,
    "spams": 50,
    "spam_percent": 5
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – report returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
emails integer
The total number of emails sent during the last 30 day period
Example: 550
rejects integer
How many of those emails sent were rejected
Example: 50
spams integer
How many of those rejects were marked as spam
Example: 50
spam_percent string
Percentage of emails sent that were rejected as spam
Example: 5

Email Unsubscribes

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
}

result = RestClient.post 'https://api.smtp2go.com/v3/stats/email_unsubs', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/stats/email_unsubs', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/stats/email_unsubs", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
})

r = requests.post('https://api.smtp2go.com/v3/stats/email_unsubs', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/stats/email_unsubs")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/stats/email_unsubs"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/stats/email_unsubs

This endpoint returns a report on email unsubscribe statistics.

Parameters

api_key required string
Example: "api-700B************************8F4E"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "emails": 550,
    "rejects": 20,
    "unsubscribes": 10,
    "unsubscribes_percent": 1.8
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – report returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
emails integer
The total number of emails sent during the last 30 day period
Example: 550
rejects integer
How many of those emails sent were rejected
Example: 20
unsubscribes integer
How many of those rejects were marked as unsubscribes
Example: 10
unsubscribes_percent string
Percentage of emails sent that were rejected as unsubscribes
Example: 1.8

Email Summary

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
}

result = RestClient.post 'https://api.smtp2go.com/v3/stats/email_summary', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/stats/email_summary', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/stats/email_summary", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
})

r = requests.post('https://api.smtp2go.com/v3/stats/email_summary', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/stats/email_summary")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/stats/email_summary"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/stats/email_summary

This endpoint returns a summary report providing an overview of the /stats/email_bounces, /stats/email_cycle, /stats/email_spam and /stats/email_unsubs calls.

Parameters

api_key required string
Example: "api-700B************************8F4E"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "cycle_start": "2021-04-01T00:00:00",
    "cycle_end": "2021-04-30T00:00:00",
    "cycle_used": 550,
    "cycle_remaining": 450,
    "cycle_max": 1000,
    "email_count": 550,
    "bounce_rejects": 10,
    "softbounces": 10,
    "hardbounces": 10,
    "bounce_percent": 5.5,
    "spam_rejects": 10,
    "spam_percent": 1.8,
    "unsubscribes": 10,
    "unsubscribes_percent": 10
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – report returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
cycle_start string
An ISO-8601-formatted datetime containing the start of the monthly cycle
Example: "2021-04-01T00:00:00"
cycle_end string
An ISO-8601-formatted datetime containing the end of the monthly cycle
Example: "2021-04-30T00:00:00"
cycle_used integer
Number of emails that have been sent during this monthly cycle
Example: 550
cycle_remaining integer
The remaining email quota in this monthly cycle
Example: 450
cycle_max integer
The total number of emails that can be sent during this monthly cycle
Example: 1000
email_count integer
The total number of emails sent during the last 30 day period
Example: 550
bounce_rejects integer
How many of those emails were bounce rejects
Example: 10
softbounces integer
How many of those rejects were softbounces
Example: 10
hardbounces integer
How many of those emails were hardbounces
Example: 10
bounce_percent string
Percentage of emails sent that were bounced
Example: 5.5
spam_rejects integer
How many of those emails were rejected as spam
Example: 10
spam_percent string
Percentage of emails sent that were rejected as spam
Example: 1.8
unsubscribes integer
How many of those rejects were marked as unsubscribes
Example: 10
unsubscribes_percent string
Percentage of emails sent that were rejected as unsubscribes
Example: 10

Suppressions

A POST command allows you to manage the list of email addresses and domains that are automatically excluded (suppressed) from receiving emails. This suppression list may contain past:

You may also curate the email address suppression list by manually adding or removing addresses.

Add Suppression

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email_address" => "test-email@example.com",
  "block_description" => "Out of date",
}

result = RestClient.post 'https://api.smtp2go.com/v3/suppression/add', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email_address": "test-email@example.com",
  "block_description": "Out of date"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/suppression/add', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email_address": "test-email@example.com",
    "block_description": "Out of date",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/suppression/add", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email_address": "test-email@example.com",
  "block_description": "Out of date",
})

r = requests.post('https://api.smtp2go.com/v3/suppression/add', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email_address", string("test-email@example.com")),
      field("block_description", string("Out of date"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/suppression/add")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/suppression/add"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email_address", "test-email@example.com"},
            {"block_description", "Out of date"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/suppression/add

This endpoint suppresses the specified email address or domain.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email_address required string
The email address or domain you would like to suppress from deliveries
Example: "test-email@example.com"
block_description string
The description given for suppressing the email or domain
Example: "Out of date"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "added": true,
    "block_description": "Out of date",
    "email_address": "test-email@example.com"
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – email or domain suppression attempted

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
added boolean
True if the email address or domain was added; otherwise, false. This field has been deprecated.
Example: true
block_description string
The description you gave for suppressing the email or domain from deliveries
Example: "Out of date"
email_address string
The email address or domain that you attempted to suppress for deliveries
Example: "test-email@example.com"

Remove Suppression

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email_address" => "test-email-2@example.com",
  "reasons" => [
    "spam",
  ],
}

result = RestClient.post 'https://api.smtp2go.com/v3/suppression/remove', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email_address": "test-email-2@example.com",
  "reasons": [
    "spam"
  ]
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/suppression/remove', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email_address": "test-email-2@example.com",
    "reasons": []interface{}{
      "spam",
    },
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/suppression/remove", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email_address": "test-email-2@example.com",
  "reasons": [
    "spam",
  ],
})

r = requests.post('https://api.smtp2go.com/v3/suppression/remove', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email_address", string("test-email-2@example.com")),
      field("reasons", array(
        string("spam")
      ))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/suppression/remove")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/suppression/remove"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email_address", "test-email-2@example.com"},
            {"reasons", new dynamic[] {
              "spam",
            }},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/suppression/remove

This endpoint removes address suppression on the specified email address or domain.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email_address required string
The email address or domain you would like to remove from your suppression list
Example: "test-email-2@example.com"
reasons required [string]
A list of block types you would like to remove for the given email or domain
manual
spam
bounce
unsubscribe

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "suppressions": [
      {
        "email_address": "test-email@example.com",
        "reason": "spam",
        "removed": true
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – suppression status update attempted

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
suppressions [object]
An array of suppression removal results
email_address string
The email address or domain that you attempted to remove from your suppressions
Example: "test-email@example.com"
reason string
The block type that you attempted to remove for the given email or domain
Example: "spam"
removed boolean
True if the email address was removed from your suppressions; otherwise, false
Example: true

View Suppressions

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email_address" => "test-email-3@example.com",
  "wildcard" => "@example.com",
}

result = RestClient.post 'https://api.smtp2go.com/v3/suppression/view', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email_address": "test-email-3@example.com",
  "wildcard": "@example.com"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/suppression/view', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email_address": "test-email-3@example.com",
    "wildcard": "@example.com",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/suppression/view", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email_address": "test-email-3@example.com",
  "wildcard": "@example.com",
})

r = requests.post('https://api.smtp2go.com/v3/suppression/view', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email_address", string("test-email-3@example.com")),
      field("wildcard", string("@example.com"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/suppression/view")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/suppression/view"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email_address", "test-email-3@example.com"},
            {"wildcard", "@example.com"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/suppression/view

This endpoint returns your suppressed email addresses and domains.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email_address string
Check if a specific email address or domain is in the block list
Example: "test-email-3@example.com"
wildcard string
A name, domain, or partial email address. If this is provided, the API call will return only addresses matching this wildcard.
Example: "@example.com"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "suppressions": [
      {
        "email_address": "@example.com",
        "complain": "why did I get this spam",
        "block_description": "I no longer wish to receive these emails",
        "reason": "spam",
        "timestamp": "2021-04-30T00:00:00"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – subaccount added

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
suppressions [object]
An array of suppression results
email_address string
The email address or domain that is suppressed
Example: "@example.com"
complain string
Complaint string (if any was lodged)
Example: "why did I get this spam"
block_description string
The description for why the email/domain was suppressed
Example: "I no longer wish to receive these emails"
reason string
The block type that you attempted to remove for the given email/domain
Example: "spam"
manual
spam
bounce
unsubscribe
timestamp string
Datetime when this email/domain was blocked
Example: "2021-04-30T00:00:00"

Subaccounts

A POST command allows you to manage your subaccounts.

Add Subaccount

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email" => "test-email-5@example.com",
  "fullname" => "Test account 5",
  "limit" => 250000,
  "dedicated_ip" => false,
}

result = RestClient.post 'https://api.smtp2go.com/v3/subaccount/add', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email": "test-email-5@example.com",
  "fullname": "Test account 5",
  "limit": 250000,
  "dedicated_ip": false
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/subaccount/add', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email": "test-email-5@example.com",
    "fullname": "Test account 5",
    "limit": 250000,
    "dedicated_ip": false,
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/subaccount/add", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email": "test-email-5@example.com",
  "fullname": "Test account 5",
  "limit": 250000,
  "dedicated_ip": False,
})

r = requests.post('https://api.smtp2go.com/v3/subaccount/add', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email", string("test-email-5@example.com")),
      field("fullname", string("Test account 5")),
      field("limit", number(250000)),
      field("dedicated_ip", falseNode())
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/subaccount/add")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/subaccount/add"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email", "test-email-5@example.com"},
            {"fullname", "Test account 5"},
            {"limit", 250000},
            {"dedicated_ip", false},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/subaccount/add

This endpoint adds a new subaccount on your master account that can send emails.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email required string
The email address of the subaccount you want to invite
Example: "test-email-5@example.com"
fullname required string
The full name of the subaccount
Example: "Test account 5"
limit integer
The number of emails the subaccount is allowed to send each billing cycle
Example: 250000
10000
20000
40000
60000
80000
100000
250000
500000
1000000
2000000
3000000
5000000
10000000
dedicated_ip boolean, default is "false"
Auto-assign a dedicated IP to the subaccount (only if limit > 100,000)

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "name": "Monthly Deals",
    "email": "deals@example.com",
    "plan_size": 250000,
    "plan_used": 150000,
    "plan_remaining": 100000,
    "state": "Active"
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – subaccount added

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
name string
The name of the subaccount
Example: "Monthly Deals"
email string
The email address of the subaccount
Example: "deals@example.com"
plan_size integer
The plan size the subaccount currently has
Example: 250000
plan_used integer
The number of emails the subaccount has sent in this billing cycle
Example: 150000
plan_remaining integer
The number of emails the subaccount has left in this billing cycle
Example: 100000
state string
The current state of the subaccount
Example: "Active"
Active
Closed
Suspended

Edit Subaccount

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email" => "test-email@example.com",
  "new_email" => "test-email-2@example.com",
  "fullname" => "Test account 2",
  "limit" => 250000,
  "dedicated_ip" => false,
}

result = RestClient.post 'https://api.smtp2go.com/v3/subaccount/edit', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email": "test-email@example.com",
  "new_email": "test-email-2@example.com",
  "fullname": "Test account 2",
  "limit": 250000,
  "dedicated_ip": false
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/subaccount/edit', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email": "test-email@example.com",
    "new_email": "test-email-2@example.com",
    "fullname": "Test account 2",
    "limit": 250000,
    "dedicated_ip": false,
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/subaccount/edit", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email": "test-email@example.com",
  "new_email": "test-email-2@example.com",
  "fullname": "Test account 2",
  "limit": 250000,
  "dedicated_ip": False,
})

r = requests.post('https://api.smtp2go.com/v3/subaccount/edit', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email", string("test-email@example.com")),
      field("new_email", string("test-email-2@example.com")),
      field("fullname", string("Test account 2")),
      field("limit", number(250000)),
      field("dedicated_ip", falseNode())
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/subaccount/edit")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/subaccount/edit"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email", "test-email@example.com"},
            {"new_email", "test-email-2@example.com"},
            {"fullname", "Test account 2"},
            {"limit", 250000},
            {"dedicated_ip", false},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/subaccount/edit

This endpoint updates the details of an existing subaccount.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email required string
The existing email address of the subaccount you want to update
Example: "test-email@example.com"
new_email string
Pass this if you would like to update to a new email address
Example: "test-email-2@example.com"
fullname required string
Pass this if you would like to update the full name of the subaccount
Example: "Test account 2"
limit integer
The number of emails the subaccount is allowed to send each billing cycle
Example: 250000
10000
20000
40000
60000
80000
100000
250000
500000
1000000
2000000
3000000
5000000
10000000
dedicated_ip boolean, default is "false"
Auto assign a dedicated IP to the subaccount (only if limit > 100,000)

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "name": "Black Friday",
    "id": "NDU5OTgw",
    "email": "black-friday@example.com",
    "plan_size": 250000,
    "plan_used": 150000,
    "plan_remaining": 100000,
    "state": "Active"
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – subaccount updated

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data SubaccountSchema
Represents a subaccount object
name string
The name of the subaccount
Example: "Black Friday"
id string
The ID of the subaccount
Example: "NDU5OTgw"
email string
The email address of the subaccount
Example: "black-friday@example.com"
plan_size integer
The plan size assigned to the subaccount
Example: 250000
plan_used integer
The number of emails the subaccount has sent in this billing cycle
Example: 150000
plan_remaining integer
The number of emails the subaccount has left in this billing cycle
Example: 100000
state string
The current state of the subaccount
Example: "Active"
Active
Closed
Suspended

Close Subaccount

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email" => "test-email-3@example.com",
}

result = RestClient.post 'https://api.smtp2go.com/v3/subaccount/close', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email": "test-email-3@example.com"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/subaccount/close', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email": "test-email-3@example.com",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/subaccount/close", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email": "test-email-3@example.com",
})

r = requests.post('https://api.smtp2go.com/v3/subaccount/close', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email", string("test-email-3@example.com"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/subaccount/close")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/subaccount/close"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email", "test-email-3@example.com"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/subaccount/close

This endpoint changes the status of an Active subaccount to Closed.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email required string
The email address of the subaccount to close
Example: "test-email-3@example.com"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – subaccount closed

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"

Reinvite Subaccount

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email" => "test-email@example.com",
}

result = RestClient.post 'https://api.smtp2go.com/v3/subaccount/reinvite', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email": "test-email@example.com"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/subaccount/reinvite', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email": "test-email@example.com",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/subaccount/reinvite", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email": "test-email@example.com",
})

r = requests.post('https://api.smtp2go.com/v3/subaccount/reinvite', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email", string("test-email@example.com"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/subaccount/reinvite")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/subaccount/reinvite"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email", "test-email@example.com"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/subaccount/reinvite

This endpoint initiates a resend in the event that a subaccount didn't receive an invite.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email required string
The email address of the subaccount you want to resend the invitation email to
Example: "test-email@example.com"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – invite sent

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"

Reopen Subaccount

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email" => "test-email@example.com",
}

result = RestClient.post 'https://api.smtp2go.com/v3/subaccount/reopen', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email": "test-email@example.com"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/subaccount/reopen', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email": "test-email@example.com",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/subaccount/reopen", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email": "test-email@example.com",
})

r = requests.post('https://api.smtp2go.com/v3/subaccount/reopen', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email", string("test-email@example.com"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/subaccount/reopen")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/subaccount/reopen"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email", "test-email@example.com"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/subaccount/reopen

This endpoint reverts the status of a closed subaccount back to active.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email required string
The email address of the subaccount you want to re-open
Example: "test-email@example.com"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – subaccount active

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"

Search Subaccounts

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "fuzzy_search" => true,
  "search_terms" => [
    [
      "january",
      "deals",
    ],
  ],
  "states" => "active",
  "sort_direction" => "asc",
  "page_size" => 100,
  "continue_token" => "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdXXXX",
}

result = RestClient.post 'https://api.smtp2go.com/v3/subaccount/search', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "fuzzy_search": true,
  "search_terms": [
    [
      "january",
      "deals"
    ]
  ],
  "states": "active",
  "sort_direction": "asc",
  "page_size": 100,
  "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdXXXX"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/subaccount/search', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "fuzzy_search": true,
    "search_terms": []interface{}{
      []interface{}{
        "january",
        "deals",
      },
    },
    "states": "active",
    "sort_direction": "asc",
    "page_size": 100,
    "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdXXXX",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/subaccount/search", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "fuzzy_search": True,
  "search_terms": [
    [
      "january",
      "deals",
    ],
  ],
  "states": "active",
  "sort_direction": "asc",
  "page_size": 100,
  "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdXXXX",
})

r = requests.post('https://api.smtp2go.com/v3/subaccount/search', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("fuzzy_search", trueNode()),
      field("search_terms", array(
        array(
          string("january"),
          string("deals")
        )
      )),
      field("states", string("active")),
      field("sort_direction", string("asc")),
      field("page_size", number(100)),
      field("continue_token", string("eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdXXXX"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/subaccount/search")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/subaccount/search"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"fuzzy_search", true},
            {"search_terms", new dynamic[] {
              new dynamic[] {
                "january",
                "deals",
              },
            }},
            {"states", "active"},
            {"sort_direction", "asc"},
            {"page_size", 100},
            {"continue_token", "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdXXXX"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/subaccount/search

This endpoint returns any subaccounts that match the provided search criteria.

Parameters

api_key required string
Example: "api-700B************************8F4E"
fuzzy_search boolean, default is "true"
Determines if search terms are matched exactly or use wildcards (true means fuzzy search is active, false an exact match)
search_terms [string]
An array of strings to search across the email address of the subaccount or the name assigned to that email
states string
Controls which states are returned
Example: "active"
active
closed
suspended
sort_direction string
Sort direction; sorts either ascending or descending by subaccount name
Example: "asc"
asc
desc
page_size integer
Number of subaccounts to retrieve per call
Example: 100
continue_token string
A token provided by a prior call to this endpoint, passing this will cause it to fetch the next page of results
Example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdXXXX"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "data": {
    "continue_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdXXX",
    "total_count": 25,
    "subaccounts": [
      {
        "name": "Black Friday",
        "id": "NDU5OTgw",
        "email": "black-friday@example.com",
        "plan_size": 250000,
        "plan_used": 150000,
        "plan_remaining": 100000,
        "state": "Active"
      }
    ]
  }
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success – results of search returned

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
data object
continue_token string
If present, can be passed to the call again in order to retrieve the next page of results
Example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0Njc4NTY4ODEsImRhdXXX"
total_count integer
The total number of subaccounts available
Example: 25
subaccounts [SubaccountSchema]
A list of subaccounts matching the search criteria
name string
The name of the subaccount
Example: "Black Friday"
id string
The ID of the subaccount
Example: "NDU5OTgw"
email string
The email address of the subaccount
Example: "black-friday@example.com"
plan_size integer
The plan size assigned to the subaccount
Example: 250000
plan_used integer
The number of emails the subaccount has sent in this billing cycle
Example: 150000
plan_remaining integer
The number of emails the subaccount has left in this billing cycle
Example: 100000
state string
The current state of the subaccount
Example: "Active"
Active
Closed
Suspended

Single sender Email

Add Single Sender Email

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email_address" => "test@test.com",
  "subaccount_id" => "bKj21",
  "message" => "string",
}

result = RestClient.post 'https://api.smtp2go.com/v3/single_sender_emails/add', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email_address": "test@test.com",
  "subaccount_id": "bKj21",
  "message": "string"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/single_sender_emails/add', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email_address": "test@test.com",
    "subaccount_id": "bKj21",
    "message": "string",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/single_sender_emails/add", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email_address": "test@test.com",
  "subaccount_id": "bKj21",
  "message": "string",
})

r = requests.post('https://api.smtp2go.com/v3/single_sender_emails/add', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email_address", string("test@test.com")),
      field("subaccount_id", string("bKj21")),
      field("message", string("string"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/single_sender_emails/add")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/single_sender_emails/add"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email_address", "test@test.com"},
            {"subaccount_id", "bKj21"},
            {"message", "string"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/single_sender_emails/add

Use the API to add a single sender email address to your account, to use from which to send mail. If the email address has previously been added and not yet verified, this action will simply resend the verification email.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email_address required string
The email address to add as a single sender
Example: "test@test.com"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"
message string
An optional message to add into the verification email

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"

Remove Single Sender Email

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email_address" => "test@test.com",
  "subaccount_id" => "bKj21",
}

result = RestClient.post 'https://api.smtp2go.com/v3/single_sender_emails/remove', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email_address": "test@test.com",
  "subaccount_id": "bKj21"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/single_sender_emails/remove', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email_address": "test@test.com",
    "subaccount_id": "bKj21",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/single_sender_emails/remove", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email_address": "test@test.com",
  "subaccount_id": "bKj21",
})

r = requests.post('https://api.smtp2go.com/v3/single_sender_emails/remove', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email_address", string("test@test.com")),
      field("subaccount_id", string("bKj21"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/single_sender_emails/remove")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/single_sender_emails/remove"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email_address", "test@test.com"},
            {"subaccount_id", "bKj21"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/single_sender_emails/remove

Remove a single sender email address from your account.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email_address required string
The email address to remove as a single sender
Example: "test@test.com"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"

View Single Sender Email

Code Sample

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Smtp2go-Api-Key' => 'API_KEY'
}

params = {
  "api_key" => "api-700B************************8F4E",
  "email_address" => "test@test.com",
  "subaccount_id" => "bKj21",
}

result = RestClient.post 'https://api.smtp2go.com/v3/single_sender_emails/view', params.to_json, headers

p JSON.parse(result)

const inputBody = {
  "api_key": "api-700B************************8F4E",
  "email_address": "test@test.com",
  "subaccount_id": "bKj21"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-Smtp2go-Api-Key':'API_KEY'
};

fetch('https://api.smtp2go.com/v3/single_sender_emails/view', {
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
  .then(function(res) {
    return res.json();
  })
  .then(function(body) {
    console.log(body);
  });

package main

import (
  "fmt"
  "bytes"
  "net/http"
  "io/ioutil"
  "encoding/json"
)

func main() {
  headers := map[string][]string{
    "Content-Type": []string{"application/json"},
    "Accept": []string{"application/json"},
    "X-Smtp2go-Api-Key": []string{"API_KEY"},
  }

  requestData, _ := json.Marshal(map[string]interface{}{
    "api_key": "api-700B************************8F4E",
    "email_address": "test@test.com",
    "subaccount_id": "bKj21",
  })
  requestBody := bytes.NewBuffer(requestData)

  req, _ := http.NewRequest("POST", "https://api.smtp2go.com/v3/single_sender_emails/view", requestBody)
  req.Header = headers

  client := &http.Client{}
  resp, _ := client.Do(req)

  body, _ := ioutil.ReadAll(resp.Body)
  fmt.Println(string(body))
}

import requests
import json

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Smtp2go-Api-Key': 'API_KEY'
}

data = json.dumps({
  "api_key": "api-700B************************8F4E",
  "email_address": "test@test.com",
  "subaccount_id": "bKj21",
})

r = requests.post('https://api.smtp2go.com/v3/single_sender_emails/view', data=data, headers=headers)

print(r.json())

import argo.jdom.*;
import argo.format.*;
import static argo.jdom.JsonNodeFactories.*;
import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class Main {
  public static void main(String[] args) throws IOException {
    var client = new OkHttpClient();
    var JSON = MediaType.get("application/json; charset=utf-8");

    JsonNode json = object(
      field("api_key", string("api-700B************************8F4E")),
      field("email_address", string("test@test.com")),
      field("subaccount_id", string("bKj21"))
    );
    JsonFormatter JSON_FORMATTER = new CompactJsonFormatter();
    RequestBody body = RequestBody.create(JSON_FORMATTER.format(json), JSON);

    Request request = new Request.Builder()
      .url("https://api.smtp2go.com/v3/single_sender_emails/view")
      .addHeader("Content-Type", "application/json")
      .addHeader("Accept", "application/json")
      .addHeader("X-Smtp2go-Api-Key", "API_KEY")
      .post(body)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Flurl;
using Flurl.Http;

namespace csharp
{
  class Program
  {
    static async Task Main(string[] args)
    {
      dynamic response = await "https://api.smtp2go.com/v3/single_sender_emails/view"
        .WithHeaders(new Dictionary<string, dynamic>{
          {"Content-Type", "application/json"},
          {"Accept", "application/json"},
          {"X-Smtp2go-Api-Key", "API_KEY"},
        })
        .PostJsonAsync(
          new Dictionary<string, dynamic>{
            {"api_key", "api-700B************************8F4E"},
            {"email_address", "test@test.com"},
            {"subaccount_id", "bKj21"},
          }
        ).ReceiveString();

      Console.WriteLine(response);
    }
  }
}

HTTP Request

POST
/single_sender_emails/view

Returns a list of single sender email addresses on your account.

Parameters

api_key required string
Example: "api-700B************************8F4E"
email_address string
If passed only retrieve records where email address matches this
Example: "test@test.com"
subaccount_id string
If you wish to make this API call on behalf of a subaccount then include it's unique ID here
Example: "bKj21"

Response

{
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2",
  "senders": [
    {
      "email_address": "string",
      "verified": true
    }
  ]
}

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644"
}

Success Response 200

Success

request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
senders [SingleSenderSchema]
A list of senders that were returned by the last action
email_address string
The email address of the sender
verified boolean
A flag indicating whether or not this email address has been verified

Schemas

EmailResponseSchema

{
  "succeeded": 10,
  "failed": 0,
  "failures": [
    "\"failures\":[\"Message failed - Error: 452-4.2.2 The email account that you tried to reach is over quota.\"]"
  ],
  "email_id": "1er8bV-6Tw0Mi-7h"
}

Properties

succeeded integer
Count of emails successfully sent
Example: 10
failed integer
Count of emails that failed
failures [string]
email_id string
The email ID generated (if successful)
Example: "1er8bV-6Tw0Mi-7h"

ActivityEventTypes

"soft-bounced"

A string indicating the type of the event

Properties

*anonymous* string
A string indicating the type of the event
Example: "soft-bounced"
processed
soft-bounced
hard-bounced
rejected
spam
delivered
unsubscribed
resubscribed
opened
clicked

SenderDomainSchema

{
  "fulldomain": "example.com",
  "subdomain": "example@example.com",
  "domain": "example.com",
  "suffix": "com",
  "dkim_selector": "s12345._domainkey",
  "dkim_verified": false,
  "dkim_status": "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
  "dkim_value": "dkim.smtp2go.net",
  "rpath_selector": "em12345",
  "rpath_verified": false,
  "rpath_status": "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
  "rpath_value": "return.smtp2go.net"
}

An object holding sender domain information

Properties

fulldomain string
The full sender domain name
Example: "example.com"
subdomain string
The subdomain value of the sender domain
Example: "example@example.com"
domain string
The domain value of the sender domain
Example: "example.com"
suffix string
The suffix value of the sender domain
Example: "com"
dkim_selector string
The domain’s DKIM selector
Example: "s12345._domainkey"
dkim_verified boolean
A flag indicating whether this domain has DKIM verified
dkim_status string
A string containing the last error if DKIM verification failed
Example: "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
dkim_value string
A string containing the last known value of the DKIM TXT record
Example: "dkim.smtp2go.net"
rpath_selector string
The domain’s return path selector
Example: "em12345"
rpath_verified boolean
A flag indicating whether this domain has RPATH verified
rpath_status string
A string containing the last error if RPATH verification failed
Example: "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
rpath_value string
A string containing the last known value of the RPATH CNAME record
Example: "return.smtp2go.net"

SenderDomainTrackerSchema

{
  "fulldomain": "example",
  "subdomain": "link",
  "domain": "example.com",
  "suffix": "com",
  "cname_verified": false,
  "cname_status": "Lookup CNAME(link.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
  "cname_value": "track.smtp2go.net",
  "enabled": false,
  "ssl_status": "An SSL certificate has been requested and will be enabled shortly"
}

An object holding sender domain tracking information

Properties

fulldomain string
The full tracking domain value
Example: "example"
subdomain string
The tracking subdomain value
Example: "link"
domain string
The primary domain
Example: "example.com"
suffix string
The domain suffix
Example: "com"
cname_verified boolean, default is "false"
A flag indicating whether or not this tracking subdomain has a CNAME record pointing to track.smtp2go.com
cname_status string
A status string or error message with the current status of the verification
Example: "Lookup CNAME(link.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN"
cname_value string
A string with the current value of the CNAME record for this subdomain
Example: "track.smtp2go.net"
enabled boolean
A boolean flag indicating whether this tracking domain is currenly enabled
ssl_status string
A string indicating the current SSL status of the tracking domain, or 'issued: [unix_secs]' if already issued
Example: "An SSL certificate has been requested and will be enabled shortly"

SenderDomainActionResponse

{
  "domain": {
    "fulldomain": "example.com",
    "subdomain": "example@example.com",
    "domain": "example.com",
    "suffix": "com",
    "dkim_selector": "s12345._domainkey",
    "dkim_verified": false,
    "dkim_status": "Lookup CNAME(s12345._domainkey.example123.com) failed, The target NS server f.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
    "dkim_value": "dkim.smtp2go.net",
    "rpath_selector": "em12345",
    "rpath_verified": false,
    "rpath_status": "Lookup CNAME(em12345.example123.com) failed, The target NS server d.gtld-servers.net. returned a non-success RCode of NXDOMAIN",
    "rpath_value": "return.smtp2go.net"
  },
  "trackers": "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"
}

Properties

domain SenderDomainSchema
An object holding sender domain information
trackers [SenderDomainTrackerSchema]
List of trackers assigned to a domain
Example: "\"trackers\": [\"fulldomain\": \"link.example123.com\",\"subdomain\": \"link\",\"domain\": \"example123\",\"suffix\": \"com\",\"cname_verified\": true,\"cname_status\": \"\",\"cname_value\": \"track.smtp2go.net\",\"enabled\": true,\"ssl_status\": \"issued: 1623371453\"]"

SMTPUserSchema

{
  "username": "authuser",
  "email_password": "pa$$word!1<-dontusethis-ever",
  "comments": "Head of marketing",
  "custom_ratelimit": false,
  "custom_ratelimit_value": 10000,
  "custom_ratelimit_period": "3600",
  "description": "Active since 082021",
  "feedback_enabled": false,
  "feedback_domain": "example.com",
  "feedback_html": "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>",
  "feedback_text": "This month's deals.",
  "archive_enabled": false,
  "open_tracking_enabled": false,
  "audit_email": "test-email-2@example.com"
}

An SMTP user’s details

Properties

username required string
A valid SMTP2GO username to add to your account
Example: "authuser"
email_password required string
The password for this user when sending email
Example: "pa$$word!1<-dontusethis-ever"
comments string
Optional comments to attach to the user
Example: "Head of marketing"
custom_ratelimit boolean, default is "false"
Whether this user has a custom rate limit
custom_ratelimit_value integer
If custom_ratelimit is true, how many emails this user can send in the period specified in custom_ratelimit_period
Example: 10000
custom_ratelimit_period string
If custom_ratelimit is true, the period over which the user will be limited to the number of emails specified in custom_ratelimit_value. See custom rate limits for further information.
Example: "3600"
description string
Any comment or additional information about this user
Example: "Active since 082021"
feedback_enabled boolean, default is "false"
Are custom feedback inserts specified?
feedback_domain string
The domain to insert into the custom feedback links
Example: "example.com"
feedback_html string
HTML content to use in text/html email body
Example: "<p><a href=\"%%UNSUBSCRIBE%%\">unsubscribe</a></p>"
feedback_text string
Text content to use in text/plain email body
Example: "This month's deals."
archive_enabled boolean, default is "false"
Is archiving enabled for this user?
open_tracking_enabled boolean, default is "false"
Is open tracking enabled for this user?
audit_email string
Bcc address for this user key
Example: "test-email-2@example.com"

SubaccountSchema

{
  "name": "Black Friday",
  "id": "NDU5OTgw",
  "email": "black-friday@example.com",
  "plan_size": 250000,
  "plan_used": 150000,
  "plan_remaining": 100000,
  "state": "Active"
}

Represents a subaccount object

Properties

name string
The name of the subaccount
Example: "Black Friday"
id string
The ID of the subaccount
Example: "NDU5OTgw"
email string
The email address of the subaccount
Example: "black-friday@example.com"
plan_size integer
The plan size assigned to the subaccount
Example: 250000
plan_used integer
The number of emails the subaccount has sent in this billing cycle
Example: 150000
plan_remaining integer
The number of emails the subaccount has left in this billing cycle
Example: 100000
state string
The current state of the subaccount
Example: "Active"
Active
Closed
Suspended

SingleSenderSchema

{
  "email_address": "string",
  "verified": true
}

Represents a single sender object

Properties

email_address string
The email address of the sender
verified boolean
A flag indicating whether or not this email address has been verified

APIKeyField

"api-700B************************8F4E"

APIKey

Properties

APIKey string
API Key from SMTP2GO App > Settings > API Keys; required for authentication
Example: "api-700B************************8F4E"

BadRequestResponse

{
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  },
  "request_id": "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"
}

400 Bad Request

Properties

data object
error_code string
An API error code string
Example: "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED"
error string
An error description
Example: "You do not have permission to access this API endpoint"
request_id string
Unique ID for this request
Example: "40cbb6f2-935f-11e7-b5be-480fcf01a6f2"