App42 Cloud API

Windows Phone Cloud SDK

Email

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 Windows Phone API's work in an asynchronous mode that means the response will not be available immediately and all the API methods would not return any value and have return type as void. The response will be returned in callback methods which the caller will provide to the calling method.
As mentioned above that the response will be returned in callback methods, every API method is taking instance of App42Callback (as the last parameter) which will have the implementation of 2 methods: OnSuccess & OnException.(as shown below)

public class CallBack : App42Callback
{
public override void OnSuccess(Object obj)
{
Email email = (Email) obj;
//Do whatever you want with the user object
}
public override void OnException(App42Exception e)
{
//Do whatever you want with the exception
}
}

The callback methods will return the response in the form of Object which will have to be type cast to the object domain object (e.g. App42Response / Email in this case) The Domain object 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.

public override void OnSuccess(Object obj)
{
Email email =  (Email) obj /* returns the Email object. */   
String subject =  email.GetSubject();   
String body =  email.GetBody();   
IList<Email.Configuration> configList = email.GetConfigList();  
for(int i  = 0; i < configList.Count; i++)
{    
Email.Configuration config = configList[i];
Console.WriteLine("emailId is " . config.GetEmailId());
Console.WriteLine("host is " . config.GetHost());
Console.WriteLine("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".

public override void OnException(App42Exception ex)
{
int appErrorCode = ex.GetAppErrorCode();
int httpErrorCode = ex.GetHttpErrorCode();
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@gmail.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.

public void CreateMailConfiguration(String emailHost, Int64 emailPort, String emailId, String emailPassword, Boolean isSSL, App42Callback requestCallback)

Creates Email Configuration using which in future the App developer can send mail

Parameters:

emailHost - Email Host to be used for sending mail
emailPort - Email Port to be used for sending mail
emailId - Email id to be used for sending mail
emailPassword - Email Password to be used for sending mail
isSSL - Should be send using SSL or not
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Email object containing the email configuration which has been created

Response: Email Object

Exception:

This method throws following exception.
/*
2301 - BAD REQUEST - The request parameters are invalid. Email id '<emailId>' already exists. 
*/ 		   
For more details click Exception
String emailHost = "smtp.gmail.com";
int emailPort = 465;
String emailId = "nick@gmail.com";
String emailPassword = "********";
bool isSSL = true;	

emailService.CreateMailConfiguration(emailHost,emailPort,emailId,emailPassword,isSSL,requestCallback);  /* returns the Email object. */  
OnSuccess(Object obj){
Email email = (Email) obj;
IList<Email.Configuration> configList = email.GetConfigList();  
for(int i = 0; i < configList.Count; i++)  
{  
Console.WriteLine("emailId is " + configList[i].GetEmailId());
Console.WriteLine("host is " + configList[i].GetHost());
Console.WriteLine("port is " + configList[i].GetPort());   		
}   
String jsonResponse = configList.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": "true",
            "email": {
                "configurations": {
                    "config": {
                        "emailId": "nick@gmail.com",
                        "host": "smtp.gmail.com",
                        "port": 465,
                        "ssl": true
                    }
                }
            }
        }
    }
}
public void RemoveEmailConfiguration(String emailId, App42Callback requestCallback)

Removes email configuration for the given email id.
Note: In future the developer wont be able to send mails through this id

Parameters:

emailId - The email id for which the configuration has to be removed
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response if removed successfully

Response: App42Response Object

Exception:

This method throws following exception.
/*
2303 - NOT FOUND - Email with the id '<emailId>' does not exist.
*/ 		     
For more details click Exception
String emailId = "nick@gmail.com";

emailService.RemoveEmailConfiguration(emailId,requestCallback);  /* returns the Email object. */  
OnSuccess(Object obj)
{
Email email = (Email) obj;
bool success = email.isResponseSuccess(); 
String jsonResponse = email.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": "true",
            "email": {
                "configurations": {
                    "config": {
                        "emailId": "nick@gmail.com",
                        "host": "smtp.gmail.com",
                        "port": 465,
                        "ssl": true
                    }
                }
            }
        }
    }
}
public void GetEmailConfigurations(App42Callback requestCallback)

Gets all Email Configurations for the app

Parameters:

requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Email object containing all Email Configurations

Response: Email Object

Exception:

This method throws following exception.
/*
2302 - NOT FOUND - Email configurations do not exist. 
*/ 		        
For more details click Exception
emailService.GetEmailConfigurations(requestCallback);  /* returns the Email object. */  
OnSuccess(Object obj)
{
Email email = (Email) obj;
IList<Email.Configuration> configList = email.GetConfigList();  
for(int i = 0; i < configList.Count; i++)  
{  
Console.WriteLine("emailId is " + configList[i].GetEmailId());
Console.WriteLine("host is " + configList[i].GetHost());
Console.WriteLine("port is " + configList[i].GetPort());   	                     
}   
String jsonResponse = configList.ToString(); /* returns the response in JSON format. (as shown below)*/
}

{
    "app42": {
        "response": {
            "success": "true",
            "email": {
                "configurations": {
                    "config": [
                        {
                            "emailId": "nick@gmail.com",
                            "host": "smtp.gmail.com",
                            "port": 465,
                            "ssl": true
                        },
                        {
                            "emailId": "bob@gmail.com",
                            "host": "smtp.gmail.com",
                            "port": 465,
                            "ssl": true
                        },
                        {
                            "emailId": "jack@gmail.com",
                            "host": "smtp.gmail.com",
                            "port": 465,
                            "ssl": true
                        }
                    ]
                }
            }
        }
    }
}

public void SendMail(String sendTo, String sendSubject, String sendMsg, String fromEmail, string emailMimeType, App42Callback requestCallback)

Sends the Email to the specified recipient with the provided detail

Parameters:

fromEmail - The Email Id using which the mail(s) has to be sent
sendTo - The email ids to which the email has to be sent. Email can be sent to multiple email ids. Multiple email ids can be passed using comma as the seperator e.g. sid@shephertz.com, info@shephertz.com
sendSubject - Subject of the Email which to be sent
sendMsg - Email body which has to be sent
emailMime - MIME Type to be used for sending mail. EmailMime available options are PLAIN_TEXT_MIME_TYPE or HTML_TEXT_MIME_TYPE
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Email object containing all the details used for sending mail

Response: Email Object

Exception:

This method throws following exception.
/*
2300 - NOT FOUND - Email parameters not found.
*/  		       
For more details click Exception
String sendTo =  "bob@gmail.com";
String sendSubject = "Here we are sending an Email";
String sendMsg = "Body of message";
String fromEmailId = "jack@gmail.com";
String emailMimeType = EmailMIME.PLAIN_TEXT_MIME_TYPE; 

emailService.SendMail(sendTo,sendSubject,sendMsg,fromEmail,emailMimeType,requestCallback);  /* returns the Email object. */  
OnSuccess(Object obj)
{
Email email = (Email) obj;
Console.WriteLine("from is " + email.GetFrom());
Console.WriteLine("to is " + email.GetTo());
Console.WriteLine("subject is " + email.GetSubject());
Console.WriteLine("body is " + email.GetBody());   
String jsonResponse = email.ToString(); /* returns the response in JSON format. (as shown below)*/ 
}
{
    "app42": {
        "response": {
            "success": "true",
            "email": {
                "from": "jack@gmail.com",
                "to": "bob@gmail.com",
                "subject": "Here we are sending an Email!! ",
                "body": "Body of message"
            }
        }
    }
}