Service to send Email. This service can be used by app to send mail to one or multiple recipients.
In order to use the various functions available under a particular API, a developer will have to create an instance of ServiceAPI by passing the apiKey and the secretKey which has been received while creating an app.
ServiceAPI api = new ServiceAPI("<API_KEY>","<SECRET_KEY>");
After initialization, developer needs to call the buildXXXService method on ServiceAPI instance to get the instance of the particular API that you wish to build. For example, To build an instance of EmailService, buildEmailService() method needs to be called.
EmailService emailService = api.buildEmailService();
Once the API instance has been retrieved, You are ready to use the functions available for that particular API.
The methods available under a particular API will return the domain object (like Email in this case) as a response which will have the accessor / mutator to access the available properties for that object. You can get the response in the form of JSON as well. We have provided the JSON response with every function detail which can be retrieved by calling the toString() on the returned object.
String emailHost = "smtp.gmail.com";
int emailPort = 465;
String emailId = "nick@shephertz.com";
String emailPassword = "********";
boolean isSSL = true;
Email email = emailService.createMailConfiguration(emailHost,emailPort,emailId,emailPassword,isSSL); /* returns the Email object. */
ArrayList<Email.Configuration> configList = email.getConfigList();
for(Email.Configuration config : configList)
{
System.out.println("emailId is " + config.getEmailId());
System.out.println("Host is " + config.getHost());
System.out.println("Port is " + config.getPort());
}
String jsonResponse = email.toString(); /* returns the response in JSON format. */
The functions available under Email API can throw some exceptions in abnormal conditions. Example of the same has been given below.
E.g. If App developer is removing the email configuration that does not exist, the function will throw the App42Exception (as shown below) with message as "Not Found" and the appErrorCode as "2303" and the details as "Email with the id '<emailId>' does not exist".
String emailId = "nick@shephertz.com";
try
{
Email email = emailService.removeEmailConfiguration(emailId);
}
catch(App42Exception ex)
{
int appErrorCode = ex.getAppErrorCode();
int httpErrorCode = ex.getHttpErrorCode();
if(appErrorCode == 2303)
{
// Handle here for Not Found (Email with the id '<emailId>' does not exist.)
}
else if(appErrorCode == 1401)
{
// handle here for Client is not authorized
}
else if(appErrorCode == 1500)
{
// handle here for Internal Server Error
}
String jsonText = ex.getMessage(); /* returns the Exception text in JSON format. (as shown below)*/
}
{
"app42Fault": {
"httpErrorCode": 404,
"appErrorCode": 2303,
"message": "Not Found",
"details": "Email with the id 'nick@shephertz.com' does not exist"
}
}
Below are the HTTP Error Codes and their description, the function under the Email API can throw.
/* 1400 - BAD REQUEST - The Request parameters are invalid 1401 - UNAUTHORIZED - Client is not authorized 1500 - INTERNAL SERVER ERROR - Internal Server Error. Please try again */
Below are the Application Error Codes and their description, the function under the Email API can throw.
/* 2300 - NOT FOUND - Email parameters not found. 2301 - BAD REQUEST - The request parameters are invalid. Email id '<emailId>' already exists. 2302 - NOT FOUND - Email configurations do not exist. 2303 - NOT FOUND - Email with the id '<emailId>' does not exist. */
Various functions available under Email API has been explained below.
Creates Email Configuration using which in future the App developer can send mail.
Parameters:
Returns:
Response: Email Object
Exception:
/* 2301 - BAD REQUEST - The request parameters are invalid. Email id '<emailId>' already exists. */
String emailHost = "smtp.gmail.com";
int emailPort = 465;
String emailId = "nick@shephertz.com";
String emailPassword = "********";
boolean isSSL = true;
Email email = emailService.createMailConfiguration(emailHost,emailPort,emailId,emailPassword,isSSL); /* returns the Email object. */
ArrayList<Email.Configuration> configList = email.getConfigList();
for(Email.Configuration config : configList)
{
System.out.println("emailId is " + config.getEmailId());
System.out.println("Host is " + config.getHost());
System.out.println("Port is " + config.getPort());
}
String jsonResponse = email.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": "true",
"email": {
"configurations": {
"config": {
"emailId": "nick@shephertz.com",
"host": "smtp.gmail.com",
"port": 465,
"ssl": true
}
}
}
}
}
}
Removes email configuration for the given email id.
Note: In future the developer
wont be able to send mails through this id
Parameters:
Returns:
Response: App42Response Object
Exception:
/* 2303 - NOT FOUND - Email with the id '<emailId>' does not exist. */
String emailId = "nick@shephertz.com"; App42Response response = emailService.removeEmailConfiguration(emailId); /* returns the App42Response object. */ boolean success = response.isResponseSuccess(); String jsonResponse = response.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": "true",
"email": {
"configurations": {
"config": {
"emailId": "nick@shephertz.com",
"host": "smtp.gmail.com",
"port": 465,
"ssl": true
}
}
}
}
}
}
Gets all Email Configurations for the app.
Parameters:
Returns:
Response: Email Object
Exception:
/* 2302 - NOT FOUND - Email configurations do not exist. */
Email email = emailService.getEmailConfigurations(); /* returns the Email object. */
ArrayList<Email.Configuration> configList = email.getConfigList( );
for(Email.Configuration config : configList)
{
System.out.println("emailId is " + config.getEmailId());
System.out.println("Host is " + config.getHost());
System.out.println("Port is " + config.getPort());
}
String jsonResponse = email.toString( ); /* returns the response in JSON format. (as shown below) */
{
"app42": {
"response": {
"success": "true",
"email": {
"configurations": {
"config": [
{
"emailId": "nick@shephertz.com",
"host": "smtp.gmail.com",
"port": 465,
"ssl": true
},
{
"emailId": "bob@shephertz.com",
"host": "smtp.gmail.com",
"port": 465,
"ssl": true
},
{
"emailId": "jack@shephertz.com",
"host": "smtp.gmail.com",
"port": 465,
"ssl": true
}
]
}
}
}
}
}
Sends the Email to the specified recipient with the provided details.
Parameters:
Returns:
Response: Email Object
Exception:
/* 2300 - NOT FOUND - Email parameters not found. */
String sendTo = "bob@shephertz.com";
String sendSubject = "Here we are sending an Email";
String sendMsg = "Body of message";
String fromEmail = "jack@shephertz.com";
Email email = emailService.sendMail(sendTo, sendSubject, sendMsg, fromEmail, EmailMIME.PLAIN_TEXT_MIME_TYPE); /* returns the Email object. */
System.out.println("from is " + email.getFrom());
System.out.println("to is " + email.getTo());
System.out.println("subject is " + email.getSubject());
System.out.println("body is " + email.getBody());
String jsonResponse = email.toString(); /* returns the response in JSON format. (as shown below)*/
{
"app42": {
"response": {
"success": "true",
"email": {
"from": "jack@shephertz.com",
"to": "bob@shephertz.com",
"subject": "Here we are sending an Email!! ",
"body": "Body of message"
}
}
}
}