Creating a connector for integration with an e-mail marketing tool

As a developer, you can write a custom connector to integrate Ticketmatic with an e-mail marketing tool of choice.

The connector needs to implement an API that will be called by Ticketmatic to:

  • configure the connector
  • transmit subscriber changes that originated in Ticketmatic
  • send custom selections from Ticketmatic

Also, the connector will need to call the Ticketmatic API to:

  • transmit subscriber changes that originated in the e-mail marketing tool
  • transmit info on the e-mail campaigns that were sent to Ticketmatic

Registering a connector

To start developing an e-mail marketing connector, go to the “My Ticketmatic ID” screen and create an application. This will give you a required set of API keys. Fill in a Mailtool webhook url for the application. Ticketmatic will always call the connector on the specified webhook url. This webhook will contain:

  • the Ticketmatic account shortname, so the connector can identify which account is making the call
  • the operation to be performed

Examples of webhooks:

1 https://www.myconnector.com/{accountshortname}/{operation}
2 https://www.myconnector.com/connector?account={accountshortname}&operation={operation}

You are responsible for hosting the connector on the specified address. The url should be a secure https address.


Connector API

The connector needs to implement following calls:

  1. GET {webhookurl}/parameters
  2. POST {webhookurl}/config
  3. POST {webhookurl}/sync
  4. GET {webhookurl}/subscribers
  5. POST {webhookurl}/selections
  6. POST {webhookurl}/reset

Each succeeded API call should return a http code 200. Any code not in the 2xx range will be considered as failed by Ticketmatic.

To ensure that only Ticketmatic can call the API of your connector, Ticketmatic signs the requests to your connector in the same way as a request to the Ticketmatic API needs to be signed. In every call (except the parameters call) a Authorization header will be present. You can use this Authorization header to verify that the incoming call is an authenticated call from Ticketmatic. More info about the Authorization header can be found here

1. GET {webhookurl}/parameters

This call should return the parameters that need to be filled in by the user when configuring the connector. It can contain for example a listid or accesskey for the e-mail marketing tool.

It should return a json array with name and caption keys for each parameter. If no extra parameters are needed, return an empty array.

Example result:

 1 [
 2     {
 3         "name": "myconnector_listid",
 4         "caption": "Myconnector listid"
 5     },
 6     {
 7         "name": "myconnector_apikey",
 8         "caption": "Myconnector API-key"
 9     }
10 ]

2. POST {webhookurl}/config

This call will be done by Ticketmatic when the connector is configured. It will pass the additional parameter values for the parameters retrieved from the parameters call.

The info will be passed in the body as raw json.

The connector should store this information so it can be retrieved for subsequent calls.

Example body:

1 {
2     "myconnector_listid": "12345",
3     "myconnector_apikey": "sqdfqsdfsdfqsdfqd"
4 
5 }

The keys (in the example myconnector_listid and myconnector_apikey) are custom parameters: you will receive the same keys as specified in the earlier parameters response.

3. POST {webhookurl}/sync

This call will be done by Ticketmatic when there are changes to Ticketmatic contacts that are relevant to the e-mail marketing tool.

The body will contain an array of subscriber changes. The connector should modify the subscribers in the e-mail marketing tool according to these changes.

Each change can contain following keys:

  • email: required, the e-mail address of the subscriber
  • subscribed: optional, boolean indicating whether the contact is subscribed
  • firstname: optional, first name of the subscriber
  • lastname: optional, last name of the subscriber

Example body:

 1 [
 2     {
 3         "email": "john@ticketmatic.com",
 4         "firstname" : "John",
 5         "lastname" : "Doe",
 6         "subscribed" : true
 7     },
 8     {
 9         "email": "mary@ticketmatic.com",
10         "subscribed": false
11     }  
12 ]

There can be up to 1000 subscriber changes in a single call.

4. GET {webhookurl}/subscribers

This call will be done by Ticketmatic to perform a full sync. The connector should return the complete list of subscribers in the e-mail marketing tool.

The result should be returned in line-delimited streaming json format. Each line should contain a json object with the subscriber info. This format is well suited for transmitting a large dataset (the list of subscribers could be many megabytes of data) as it is not necessary to keep the whole dataset in memory before sending or receiving it.

For each subscriber, following keys should be passed:

  • email
  • firstname
  • lastname

The last line should be a special json object containing a status key to indicate the end of the list. In this line, you also need to pass the total number of subscribers. For example: {"status": "complete", "nbrofsubscribers": 2345 }

Example:

1 {"email" : "john@ticketmatic.com", "firstname" : "John", "lastname" : "Doe" }
2 {"email" : "mary@ticketmatic.com", "firstname" : "Mary", "lastname" : "Robs" }
3 {"email" : "jim@ticketmatic.com", "firstname" : "Jim", "lastname" : "Johnson" }
4 {"status": "complete", "nbrofsubscribers": 3 }

5. POST {webhookurl}/selections

This call will be done by Ticketmatic when a user created a custom selection and wants this to be transferred to the e-mail marketing tool. The connector should create a new segment or selection in the e-mail marketing tool for the supplied list of subscribers.

The body will contain keys:

  • name: name to be used for the selection
  • addresses: array of e-mail addresses of subscribers in the selection.

Example body:

1 {
2     "name" : "TM Newsletter 14/03/2015", 
3     "addresses" : [
4         "test@ticketmatic.com",
5         "test2@ticketmatic.com"
6      ]
7 }

6. POST reset

This call will be done by Ticketmatic when the connection to the e-mail marketing tool needs to be reset. The connector can take care of cleanup.


Ticketmatic endpoints

The connector should call the Ticketmatic endpoints specified below. It should use the keypair of th ee-mail integration application. Endpoints should be called as regular Ticketmatic API calls. See the Ticketmatic API documentation for more info.

1. POST https://apps.ticketmatic.com/api/{accountname}/subscribers/sync

The connector should call this endpoint when there are subscriber changes originating in the e-mail marketing tool, for example new subscribers, unsubscribes or updated first or last name for a subscriber.

The body should contain an array of subscriber changes completely similar to the sync call above. For example:

 1 [
 2     {
 3         "email": "john@ticketmatic.com",
 4         "firstname" : "John",
 5         "lastname" : "Doe",
 6         "subscribed" : true
 7     },
 8     {
 9         "email": "mary@ticketmatic.com",
10         "subscribed": false
11     }  
12 ]

2. POST https://apps.ticketmatic.com/api/{accountname}/subscribers/communications

The connector should call this endpoint to transfer information on sent e-mail campaigns back to Ticketmatic. Each sent e-mail campaign should correspond to 1 communication in Ticketmatic.

The body should contain:

  • name: name of the communication
  • remark: remark for the communication
  • ts: timestamp at which the communication took place
  • addresses: array of e-mail addresses of subscribers that received the e-mail

For example:

1 {
2     "name": "TM Newsletter 14/03/2015",
3     "remark": "New artists announced for the summer festival",
4     "ts": "2015-03-14",
5     "addresses": [
6         "test1@ticketmatic.com",
7         "test2@ticketmatic.com"
8     ]
9 }

Questions?

We're always happy to help! Send us an e-mail