Email API - LiquidAnalytics/ld-api-examples GitHub Wiki

#Email API

##Overview

The email API is a way to send emails through Liquid Server. All emails sent through this API are subject to the restrictions imposed by our Amazon SES settings, and a given communities environmentConfig.

i.e. you cannot use the Email API to spoof emails from arbitrary addresses, or to send emails to addresses that belong to domains that are not allowed through environmentConfig.

Two API's are provided for use.

##/ls/api/email/emailWithBody

Usage

You can use the emailWithBody API to send out an email where the exact body of the email is completely formulated ahead of time.

###Post format:

• OAuth2 authorization header, (Authorization bearer token)
  • See OAuth2
• Post Parameters
  1. to
     • csv String of email addresses to send the email to
  2. cc
     • csv String of email addresses to cc on the email
  3. bcc
     • csv String of email addresses to bcc on the email
  4. from
     • email address that will display as the from address on the email (subject to Amazon SES settings)
  5. replyTo
     • email address that will be set as the reply-to on the email
  6. subject
     • subject line of the email
  7. body
     • body of the email

###Example

to = '[email protected]'
cc = '[email protected],[email protected]'
subject = 'test subject' 
body = 'test body'
fromStr = '[email protected]'

resp = requests.post('https://ldcloud-dev.liquidanalytics.com/ls/api/email/emailWithBody', headers = {'Authorization': 'Bearer ' + token}, data = { 
                "to": to, 
                "from": fromStr,
                "subject": subject,
                "body": body,
                "cc": cc
        })  

##/ls/api/email/emailWithTemplate

Usage

You can use the emailWithTemplate API to send out an email where a velocity template and model is provided to form the body of the email. (See https://velocity.apache.org/engine/releases/velocity-1.5/user-guide.html for more information on Velocity)

###Post format:

• OAuth2 authorization header, (Authorization bearer token)
  • See OAuth2
• Post Parameters
  1. to
     • csv String of email addresses to send the email to
  2. cc
     • csv String of email addresses to cc on the email
  3. bcc
     • csv String of email addresses to bcc on the email
  4. from
     • email address that will display as the from address on the email (subject to Amazon SES settings)
  5. replyTo
     • email address that will be set as the reply-to on the email
  6. subject
     • subject line of the email
  7. template
     • velocity template that will be used to form the body of the email, using the provided model
  8. model
     • JsonMap representing the model that will be used with the template to form the body of the email

Example

to = '[email protected]'
subject = 'template test'
template = 'Hi $!username,<br>Welcome to Liquid Analytics'
fromStr = '[email protected]'
modelStr = '{"username": "testUser"}'



resp = requests.post('https://ldcloud-dev.liquidanalytics.com/ls/api/email/emailWithTemplate', headers = {'Authorization': 'Bearer ' + token}, data = { 
                "to": to, 
                "from": fromStr,
                "subject": subject,
                "template": template,
                "model": modelStr
        })

Server Responses

If the email was sent successfully, an http 200 response will be returned, with body of "Email Sent".

If the email could not be sent for some reason, A 500 error will be returned, the body will have additional information on why the email could not be sent. Some reasons an email will not be sent, is a malformed email address provides for the to, cc, or bcc parameters.

Note: If a properly formed email address is provided, however the email address is not actually in use, a 200 response will still be returned. Synchronously detecting that an email address is not actually valid is outside the scope of this API.