Email API

API change history

Email API contains methods for handling various aspects of email campaigns (design, send) as well as recipients (list of email addresses, additional data to merge into message text), etc.

createTemplate

Adds a new template for an existing client by providing the name of the template and URLs for the HTML file and a zip of all other files.

Try it

Request

Request URL

https://api.touchbasepro.com/email/templates

Request headers

Authorization

string

The authorization token. The token will be in the format "Bearer API_KEY". For example: "Authorization: Bearer 123456789". Please include the space between "Bearer" and "API_KEY".

Request body

Template to create for client

application/json

Sample
Schema

{
  "Name": "Template2",
  "HtmlPageURL": "http://www.touchbasepro.com/t/923845340",
  "ZipFileURL": "http://www.touchbasepro.com/zip/923845340"
}

{
  "required": [
    "Name",
    "HtmlPageURL",
    "ZipFileURL"
  ],
  "type": "object",
  "properties": {
    "Name": {
      "type": "string",
      "description": "Template name"
    },
    "HtmlPageURL": {
      "type": "string",
      "description": "URL to your HTML page for the template",
      "format": "uri"
    },
    "ZipFileURL": {
      "type": "string",
      "description": "URL to your template ZIP file",
      "format": "uri"
    }
  }
}

Responses

201 Created

Template successfully created.

Representations

application/json

Sample
Schema

"ac14a97192c84fe64364e98f10f6cba4"

{
  "type": "string",
  "example": "\"ac14a97192c84fe64364e98f10f6cba4\""
}

400 Bad Request

The request was incorrect. These are the possible errors which may be included in the body of the response:

Code	Description
4002	Template Name Required The template name passed cannot be empty.
4003	Invalid Template Name The template name entered is invalid.
4004	HTML Page URL Required The URL to your HTML page for the template cannot be empty.
4005	Invalid HTML Page URL You must provide a valid URL to your HTML page for the template.
4006	Invalid ZIP File URL The URL of the zip file you have passed is invalid.
4101	No Editable Region in Template You need have at least one <singleline />, <multiline /> or <img editable="true" /> tag in your template. Without these, your clients can't add any content to their emails.
4102	No Closing Repeater tag We found your <repeater> tag, but we couldn’t track down the </repeater> tag. Please add it to close the loop.
4103	No Width Specified in the Image Tag The image you’ve added as <image> needs a width added so we can resize all the images your client adds to be the same width as this image (height is not required).
4104	No Editable Regions in Repeater We found your <repeater> and </repeater> tags, but couldn't track down a <singleline>, <multiline> or <img editable="true" /> tag. You'll need one of these tags so you can add content to any repeating items.
4105	No Opening Repeater tag We found your </repeater> tag, but we couldn’t track down the <repeater> tag. Please add it to close the loop.
4108	No Closing Table of Contents We found the <tableofcontents> tag, but couldn’t track down the </tableofcontents> tag. You’ll need to add this before the table of contents will work.
4109	No repeatertitle Tag We found your <tableofcontents> and </tableofcontents> tags, but couldn’t track down the <repeatertitle>tag.
4110	Mulitple repeatertitle tags You have more than one repeatertitle tag within your tableofcontents tags. We can only reference one of them, so please remove the extras.
4111	No tableofcontents tags You have provided a repeatertitle tag, but have not wrapped it in tableofcontents tags.
4118	Table of Contents With No Repeater Tag If you’re adding table of contents, you’ll also need a repeater in your template. The table of contents is automatically created based on what your client adds for each repeater title. If you have a table of contents, you’ll need to also add the <repeater> and </repeater> and associated tags to your template.
4128	Nested Repeaters Your template contains a repeater tag within an open repeater, or nested repeaters. Repeaters cannot be nested and must be separate of other repeaters in your template.
4129	Table Based Repeater Contains Multiple Trs A repeater in your template contains multiple <tr> tags which is not allowed.
4130	No Closing Singleline tag We found your <singleline> tag, but we couldn’t track down the </singleline> tag. Please add it to close the loop.
4131	No Closing Multiline tag We found your <multiline> tag, but we couldn’t track down the </multiline> tag. Please add it to close the loop.
4132	No Repeater with Title You have provided a tableofcontents, but haven't included a repeater with a <singleline repeatertitle="true" /> tag. Please add a singleline tag with the repeatertitle="true" attribute to the repeater you want to populate your table of contents.
4201	Contains Flash Flash is not supported by almost every email client out there and should not be included in your emails.
4202	Contains Script Almost every popular email client and spam filter does not support JavaScript. Your campaign will either be filtered as spam, or will display a security warning to your recipients. We recommend removing all JavaScript code from your campaign and then re-import it.
4203	Contains Java Java is not supported by almost every email client out there and should not be included in your emails. Please remove it from your content.
4300	No Unsubscribe Tag We require a single-click unsubscribe link in every campaign you send. To add an unsubscribe link, you can... Do it yourself by adding the tags <unsubscribe> and </unsubscribe> around the words you want to become an unsubscribe link, and then re-import your template.
4301	Unsubscribe Tag Hidden In Comments Your unsubscribe tag appears to be hidden inside HTML comment tags such as <!- -> . Please ensure your unsubscribe link is visible and not commented out of the page.
4302	Unsubscribe Tag Contains Less Than 3 Chars You'll need to add some text, such as 'unsubscribe' in between your and tags. Those words will then become an unsubscribe link for each recipient.
4303	Unsubscribe Tag Contains A Link It appears your <unsubscribe> tag contains a link. Please ensure you add the tags and around only the words (and not links) you want to become an unsubscribe link. We'll automatically convert that to a link for each recipient.
4304	No Closing Unsubscribe Tag We found the <unsubscribe> tag, but couldn't track down the </unsubscribe> tag. You'll need to add this before the unsubscribe link will work.
4305	Clickable unsubscribe link required You're using a text email unsubscribe link - [unsubscribe]. Please change this to one suitable for a HTML email by adding the tags<unsubscribe> and </unsubscribe> around the words you want to become an unsubscribe link.
4306	Nested Unsubscribe tag We've detected an <unsubscribe> tag inside another Campaign Monitor tag. This will render the Unsubscribe link unusable, and can cause problems with your subscribers attempting to unsubscribe. Please place the <unsubscribe> tag outside the Campaign Monitor tag.
4307	Nested Unsubscribe tag We've detected an <unsubscribe> tag inside another link (ie. an <a> tag). This will render the Unsubscribe link unusable, and can cause problems with your subscribers attempting to unsubscribe. Please place the <unsubscribe> tag outside the link.
4350	Files Missing from ZIP File It appears that there are files missing from your zip file which are referenced by your HTML file. Please ensure that all necessary files are included in the zip file and that the HTML file references all other files correctly.
4401	Layout not in a Repeater We found a <layout> tag, but it wasn't wrapped in <repeater> and </repeater> tags. Different layouts can only be placed within a repeater.
4402	No Closing Layout tag We found your <layout> tag, but we couldn’t track down the </layout> tag. Please add it to close the loop.
4403	No Opening Layout tag We found your </layout> tag, but we couldn’t track down the <layout> tag. Please add it to close the loop.
4404	No Editable Regions in Layout We found your <layout> and </layout> tags, but couldn't track down a <singleline>, <multiline> or <img editable="true" /> tag. You'll need one of these tags so you can add content to any repeating items.
4405	Table Based Layout Contains Multiple Trs A layout in your template contains multiple <tr> tags which is not allowed.
4406	Not all Layouts Have a Label We found a <layout> tag in a repeater that has a label, but not all of the layouts in that repeater do. To make it easy to choose between each layout option, please make sure each <layout> has a label.
4501	Nested datarepeater tags Your template contains a datarepeater tag within an open repeater, or nested repeaters. Repeaters cannot be nested and must be separate of other repeaters in your template.
4502	Invalid datarepeater type The type provided is invalid for a datarepeater. Please refer to the documentation to see what types are acceptable.
4503	Invalid datarepeater tag The tag provided is invalid for this type of datarepeater. Please refer to the template documentation to see which tags are accepted.
4504	Invalid tag chosen for TOC The tag provided is not a valid tag to be included in the table of contents for this type of datarepeater. Please refer to the template documentation to see which tags are accepted.
4505	Missing required attribute in tag An attribute is required for a particular tag in this type of datarepeater. Please refer to the template documentation to see which attributes are required.
4506	Invalid attribute value in tag The value you've supplied for an attribute is invalid for the given tag. Please refer to the template documentation to see what values are accepted.
4507	Missing required attribute in data tag An attribute is required for the data tag when the given type is specified. Please refer to the template documentation to see which attributes are required for what tags.
4508	Missing datarepeater type The type attribute is required for the datarepeater tag. Please refer to the template documentation to see what values are accepted.
4509	Invalid tag nesting The tag is not able to have other data tags nested within it. Please refer to the template documentation to see which tags are able to be nested.
4510	Invalid tag nesting The tag is not able to be nested within other data tags. Please refer to the template documentation to see which tags are able to be nested.
4511	Invalid site URL or no feeds The url you have provided as the source for your <datarepeater> is either invalid, or does not contain any RSS feeds. Please check the url and make sure there are some feeds on your site.

Representations

application/json

Sample
Schema

{
  "Code": 4002,
  "Message": "Template Name Required"
}

{
  "required": [
    "Code",
    "Message"
  ],
  "type": "object",
  "properties": {
    "Code": {
      "type": "integer",
      "description": "Error code",
      "format": "int32"
    },
    "Message": {
      "type": "string",
      "description": "Error message"
    }
  }
}

401 Unauthorized

The API key is invalid. Please verify it is correct and try again.

Representations

application/json

{
  "status": 401,
  "message": "API key is invalid."
}

403 Forbidden

There is not enough credits on your account or your account has been suspended. Please check with your account representative for more information.

Representations

application/json

{
  "status": 403,
  "message": "Not enough credits in this account."
}

429 Too many requests

The number of API calls has been exceeded. The return will include the number of seconds (represented by (number of seconds) in the example) until the API call can be tried again.

Representations

text/html

{
    "status": 429,
    "message": "Rate limit is exceeded.  Try again in {number of seconds} seconds."
}

500 Internal Server Error

Some error occurred in the processing request. Please try it again at a later time.

Representations

application/json

{
  "status": 500,
  "message": "An internal error has occurred. We have been notified about it and will restore service functionality as soon as possible."
}

Code samples

@ECHO OFF

curl -v -X POST "https://api.touchbasepro.com/email/templates"
-H "Authorization: Bearer API_KEY"
-H "Content-Type: application/json"

--data-ascii "{body}"

using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");

            var uri = "https://api.touchbasepro.com/email/templates?" + queryString;

            HttpResponseMessage response;

            // Request body
            byte[] byteData = Encoding.UTF8.GetBytes("{body}");

            using (var content = new ByteArrayContent(byteData))
            {
               content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
               response = await client.PostAsync(uri, content);
            }

        }
    }
}

// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://api.touchbasepro.com/email/templates");


            URI uri = builder.build();
            HttpPost request = new HttpPost(uri);
            request.setHeader("Authorization", "Bearer API_KEY");
            request.setHeader("Content-Type", "application/json");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
        };
      
        $.ajax({
            url: "https://api.touchbasepro.com/email/templates?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Authorization","Bearer API_KEY");
                xhrObj.setRequestHeader("Content-Type","application/json");
            },
            type: "POST",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://api.touchbasepro.com/email/templates";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"POST"];
    // Request headers
    [_request setValue:@"Bearer API_KEY" forHTTPHeaderField:@"Authorization"];
    [_request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}

<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://api.touchbasepro.com/email/templates');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Authorization' => 'Bearer API_KEY',
    'Content-Type' => 'application/json',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_POST);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>

########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Authorization': 'Bearer API_KEY',
    'Content-Type': 'application/json',
}

params = urllib.urlencode({
})

try:
    conn = httplib.HTTPSConnection('api.touchbasepro.com')
    conn.request("POST", "/email/templates?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Authorization': 'Bearer API_KEY',
    'Content-Type': 'application/json',
}

params = urllib.parse.urlencode({
})

try:
    conn = http.client.HTTPSConnection('api.touchbasepro.com')
    conn.request("POST", "/email/templates?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

require 'net/http'

uri = URI('https://api.touchbasepro.com/email/templates')


request = Net::HTTP::Post.new(uri.request_uri)
# Request headers
request['Authorization'] = 'Bearer API_KEY'
# Request headers
request['Content-Type'] = 'application/json'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body