TntConnect
Helping you build powerful connections for a lifetime of ministry...

How can I add integration for a newsletter service?


Table of Contents

It is our pleasure to provide this software free of charge to help you in your ministry.  We're so thankful for our partners who make this possible!

About TntWare

Page Details

First published by:
Troy Wolbrink
on 18 Sep 2013
Last revision by:
Troy Wolbrink
on 9 Jan 2018
This page has not yet been rated

How can I add integration for a newsletter service?

You need to host a simple text file on your site that describes to TntConnect what your various endpoints are.  It's in the "ini" format.  As an example, here's some actual endpoints:

The ini file has several sections ( //comments in blue should not be in actual file):

[APPLICATION]
MinimumVersion=3.4.8               // minimum version of TntConnect required
RecommendedVersion=3.4.8    // recommended version of TntConnect
 
[LetterService]
// if you move your query.ini url, you can put in a redirect here to update TntConnect
RedirectQueryIni=
// url to your logo (300x100)
LogoUrl=http://www.example.com/static/images/logo100.png
// url for new customer to learn about your service
AboutUrl=http://www.example.com/tntconnect
 
// for simple integration, just provide a url to TntConnect-specific instructions … done! … stop here
HowToOrderUrl=http://www.example.org/TntConnectInstructions.pdf

// advanced: optional way to allow for authentication persistence via OAUTH access token
AuthorizationRequestUrl=https://www.example.com/tntconnect/authorize?tntdb=$TNTCONNECT_DATABASE$&redirect_uri={redirect_uri}

// advanced: optional endpoint for TntConnect to exchange a temporary token with a real token
AuthorizationCompleteUrl=https://www.example.com/tntconnect/token?code={code}&redirect_uri={redirect_uri}
 
// advanced: optional endpoint for TntConnect to revoke access tokens
AuthorizationRevokeUrl=https://www.example.com/tntconnect/authorize_revoke?token=$ACCESS_TOKEN$

// deprecated: optional way to allow for authentication persistence via OAUTH access token
AccessTokenRequestUrl=https://www.example.com/tntconnect/authorize?tntdb=$TNTCONNECT_DATABASE$
AccessTokenCompleteUrl=https://www.example.com/tntconnect/authorize_callback
 
// deprecated: optional endpoint for TntConnect to revoke access tokens
AccessTokenRevokeUrl=https://www.example.com/tntconnect/authorize_revoke?token=$ACCESS_TOKEN$
 
// advanced integration:  provide url to upload CSV of partners
// return url to launch in user's default browser to complete order
CsvInvariantFieldNames=True
CsvLocalizedFieldNames=False
CsvUploadUrl=https://www.example.com/tntconnect/upload_file?v=1&ACCESS_TOKEN$

For simple integration...

You can stop with "HowToOrderUrl". 

[LetterService]
LogoUrl=http://www.chalkline.org/CL_logo.jpg
AboutUrl=http://www.chalkline.org/
HowToOrderUrl=http://www.chalkline.org/order_ev_tnt.html

The integration will look like this:

For advanced integration...

You must provide the "CsvUploadUrl".  The integration will look like this:

Authentication is optional, but if you want to provide TntConnect with an OAUTH token, you can.  The benefit is that the user doesn't have to login to your service each month to send their newsletter. 

Deprecated Info

To provide for OAUTH authentication, you must provide the following endpoints:

  • AccessTokenRequestUrl
  • AccessTokenCompleteUrl

If you include $TNTCONNECT_DATABASE$ in your AccessTokenRequestUrl, it will be substituted for the name of the current TntConnect database file.  (Prior to TntConnect 3.1.11, only $TNTMPD_DATABASE$ will be recognized.)  This way you can associate tokens with TntConnect databases for future reference.  Once user is logged in, redirect the user to the AccessTokenCompleteUrl with the access token in the fragment portion of the url as #access_token=xxxxx   In the CsvUploadUrl, $ACCESS_TOKEN$ is substituted for the OAUTH access token.

To provide for OAUTH authentication, you must provide the following endpoint:

  • AuthorizationRequestUrl

If you include $TNTCONNECT_DATABASE$ in your AccessTokenRequestUrl, it will be substituted for the name of the current TntConnect database file.  This way you can associate tokens with TntConnect databases for future reference. 

Once user is logged in (and approves access), redirect the user to the {redirect_uri} provided by TntConnect.  You can either:

  • modified OAuth 2.0 "Implicit":  Return the access token directly by adding an "access_token" parameter to the redirect_uri url.
  • OAuth 2.0 "Authorization Code":  Or you can return a temporary "authorization code" by adding a "code" query string parameter.  TntConnect will send that code to the AuthorizationCompleteUrl (in place of the {code} placeholder).  TntConnect will also include the original {redirect_uri} used.  The access token will then be returned via json as an "access_token" member (as per the OAuth 2.0 spec).

If an error occurs, you can redirect the user back to the redirect_uri with an "error" query string parameter (and optionally and "error_description").  "access_denied" is what's expected as the "error" if the user simply cancels.

If you don't want to support an OAUTH access token, don't include any of the AccessToken* urls, and don't include $ACCESS_TOKEN$ in our CsvUploadUrl.

CsvUploadUrl

TntConnect will POST the current group as UTF-8 CSV text in the body of request. 

By default, the non-localized field names are included as column headers.  But you can control the field names via the CsvInvariantFieldNames and CsvLocalizedFieldNames settings.  These are True/False settings.  You can include both as True!  If you do, invariant (non-localized) field names will always be on the first row, and the localized field names will be on the 2nd row.  You might want to include localized field names because these match up better to the mail merge fields in documents uploaded by the user.  But you might also want non-localized field names so you when you receive CSV uploads from non-English versions of TntConnect, you know what the fields stand for (i.e. you know which field is the Mailing Address Block for envelopes).

If there is an error, the service should return:

  • HTTP 401 if access token is invalid and needs to be reaquired.
  • or HTTP status 200, with “ERROR” on first line of body, actual error message on 2nd line.
    ERROR
    Example error message


If successful, return either:

  • HTTP 200, with body of “LaunchBrowserUrl=xxxxxx” 
    LaunchBrowserUrl=http://www.example.com/startorder?id=123123
  • or a standard HTTP redirect (HTTP 301/302/303 w/ Location header)

The user's default browser will then be launched with the url returned so they can complete the order.

HOW TO TEST

To test your ini url, hold down the Ctrl (or Command key on a Mac) key and right-click on the drop down list:

READY?

When you have your url ready, send me an email at: troy@tntware.com.  Tell me the NAME and URL in the email.  Once I add you to the official list, TntConnect will be updated immediately.

Recent Comments

Leave the first comment for this page.
© 2018 TntWare | Privacy | Terms of Use