Contact Management in Cloud Mail

Requirements: Cloud Mail

Cloud Mail provides a suite of easy-to-use mail and contact management components. This article covers contact management using popular cloud services such as Office365 (Graph API) and Gmail. For sending mail, please see Getting Started with Cloud Mail

Contents

Gmail

The Gmail component provides an easy to use interface to Google Contacts using Google's REST API. The Gmail component supports listing contacts and groups, creating, updating, and deleting contacts.

OAuth Authentication

Before using the component, an OAuth token must be provided through the Authorization property. The OAuth component included in the toolkit can be used to assist in this process.

By design, user-interaction is required to fetch an OAuth authorization string the first time. A user must be directed to a URL where they will authenticate and grant access to the connecting application. The user is then redirected back to the application along with a code which will be exchanged for an authorization string by the OAuth component. The authorization string is then used in requests to the cloud service.

The authorization string is valid only for a limited period of time; however a parameter can be included in the initial authorization to request a refresh token which can be used without user interaction to update the authorization token. To add an additional parameter the AddParam method can be used. In the below example, the "access_type" parameter is set to "offline".

Fetching an OAuth authorization string using the OAuth component:

Oauth oauth = new Oauth(); oauth.ClientId = "CLIENT_ID"; // This is for testing purposes only oauth.ClientSecret = "CLIENT_SECRET"; // This is for testing purposes only oauth.ServerAuthURL = "https://accounts.google.com/o/oauth2/auth"; oauth.ServerTokenURL = "https://accounts.google.com/o/oauth2/token"; oauth.AuthorizationScope = "https://www.googleapis.com/auth/contacts http://www.google.com/m8/feeds/contacts/default/full"; oauth.GrantType = OauthGrantTypes.ogtAuthorizationCode; oauth.AddParam("access_type", "offline"); gmail.Authorization = oauth.GetAuthorization();

Creating Contacts

Use the CreateContact method to create a new contact. After creating a contact with basic information, you can update it and set additional fields by editing the contact in the Contacts collection and calling the UpdateContact method.

Creating a Contact:

// Create a contact in the main contacts folder. gmail.CreateContact("Pavel", "Bansky", "pavelb@gmail.com", ""); // Set a company name gmail.Contacts[0].CompanyName = "Volkswagen"; // Set notes gmail.Contacts[0].Notes = "testNotes"; // Set multiple phone numbers gmail.Contacts[0].PhonesCount = 2; gmail.Contacts[0].PhoneIndex = 0; gmail.Contacts[0].PhoneType = TGLPhoneTypes.ptMobile; gmail.Contacts[0].PhoneNumber = "0123456789"; gmail.Contacts[0].PhoneIndex = 1; gmail.Contacts[0].PhoneType = TGLPhoneTypes.ptWork; gmail.Contacts[0].PhoneNumber = "9876543210"; // Set birthday gmail.SetContactField(0, "/json/birthdays", "[{ date: { "year": 1999, "month": 12, "day": 1 }}]", 1); // The last argument is the type of the field. 1 (Array) // Set address gmail.SetContactField(0, "/json/addresses", "[{ \"city\": \"Sydney\", \"region\": \"New South Wales\", \"postalCode\": \"2000\", \"country\": \"Australia\", \"countryCode\": \"AU\" }]", 1); // The last argument is the type of the field. 1 (Array) // Update the contact gmail.UpdateContact(0);

Listing Contacts

Contacts for the user can be retrieved via the ListContacts method. The ContactList event will fire for each contact, and the Contacts collection will be populated when the method returns. If the number of contacts exceeds the page size, the ListContactsMarker will be populated. You can call ListContacts again to retrieve the next page of contacts. These contacts will be added to the end of the Contacts collection.

Listing Messages in the Mailbox:

do{ gmail.ListContacts(); } while(!gmail.ListContactsMarker.isEmpty());

A specific contact can also be retrieved using the GetContact method.

Retrieving a Contact by ID:

// Retrieve a contact by its ID string contactId = "12345"; // Replace with the actual contact ID gmail.GetContact(contactId); // Access the retrieved contact var retrievedContact = gmail.Contacts[gmail.Contacts.Count - 1]; retrievedContact.FirstName; //first name retrievedContact.LastName; //last name retrievedContact.EmailAddressIndex=0; //set the index to zero to retrieve access the first email address retrievedContact.EmailAddress; //first email address value retrievedContact.PhonesIndex=0; //set the index to zero to retrieve access the first phone number retrievedContact.PhoneNumber; //first phone number value gmail.GetContactField(gmail.Contacts.Count - 1, "/json/birthdays/[1]/date"); //birthday of the contact gmail.GetContactField(gmail.Contacts.Count - 1, "/json/nicknames/[1]"); //nickname of the contact

Deleting Contacts

Contacts for the user can be deleted via the DeleteContacts method.

Delete a Contact:

// List contacts and search for a contact with the name "John Doe" gmail.ListContacts(); for (int i = 0; i < gmail.Contacts.Count; i++) { if (gmail.Contacts[i].DisplayName == "John Doe") { //Delete the contact gmail.DeleteContact(gmail.Contacts[i].Id); break; } }

Office365

The Office365 component provides an easy to use interface to contact management via Microsoft's Graph API. The Office365 component supports listing contacts and groups, creating, updating, and deleting contacts.

OAuth Authentication

Before using the component, an OAuth token must be provided through the Authorization property. The OAuth component included in the toolkit can be used to assist in this process.

By design, user-interaction is required to fetch an OAuth authorization string the first time. A user must be directed to a URL where they will authenticate and grant access to the connecting application. The user is then redirected back to the application along with a code which will be exchanged for an authorization string by the OAuth component. The authorization string is then used in requests to the cloud service.

The authorization string is valid only for a limited period of time; however a parameter can be included in the initial authorization to request a refresh token which can be used without user interaction to update the authorization token.

Fetching an OAuth authorization string using the OAuth component:

Oauth oauth = new Oauth(); oauth.ClientId = "CLIENT_ID"; // This is for testing purposes only oauth.ClientSecret = "CLIENT_SECRET"; // This is for testing purposes only oauth.ServerAuthURL = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"; oauth.ServerTokenURL = "https://login.microsoftonline.com/common/oauth2/v2.0/token"; oauth.AuthorizationScope = "offline_access user.read user.readwrite Contacts.Read Contacts.ReadWrite"; oauth.GrantType = OauthGrantTypes.ogtAuthorizationCode; office365.Authorization = oauth.GetAuthorization();

Creating Contacts

Use the CreateContact method to create a new contact. After creating a contact with basic information, you can update it and set additional fields by editing the contact in the Contacts collection and calling the UpdateContact method.

Creating and Updating a Contact:

office365.CreateContact("Pavel", "Bansky", "pavelb@contoso.com", "");// Create a contact in the main contacts folder. // Set a company name office365.Contacts[0].CompanyName = "Volkswagen"; // Set notes office365.Contacts[0].Notes = "testNotes"; // Set multiple phone numbers office365.Contacts[0].PhonesCount = 2; office365.Contacts[0].PhoneIndex = 0; office365.Contacts[0].PhoneType = TOLPhoneTypes.ptMobile; office365.Contacts[0].PhoneNumber = "0123456789"; office365.Contacts[0].PhoneIndex = 1; office365.Contacts[0].PhoneType = TOLPhoneTypes.ptBusiness; office365.Contacts[0].PhoneNumber = "9876543210"; // Set birthday office365.SetContactField(0, "/json/birthday", "2024-05-21", 2); // The last argument is the type of the field. 2 (String) // Set home address office365.SetContactField(0, "/json/businessAddress", "{ \"city\": \"string\", \"countryOrRegion\": \"string\", \"postalCode\": \"string\", \"state\": \"string\", \"street\": \"string\" }", 0); // The last argument is the type of the field. 0 (Object) // Update the contact office365.UpdateContact(0);

Listing Contacts

Contacts for the user can be retrieved via the ListContacts method. The ContactList event will fire for each contact, and the Contacts collection will be populated when the method returns. If the number of contacts exceeds the page size, the ListContactsMarker will be populated. You can call ListContacts again to retrieve the next page of contacts. These contacts will be added to the end of the Contacts collection.

Listing Contacts:

office365.ListContactFolders(""); // List root folders (no need to do this if you already have a Folder Id) office365.ListContacts(office365.ContactFolders[0].Id); //Lists contacts // Listing all contacts do{ office365.ListContacts(""); } while(!office365.ListContactsMarker.isEmpty());

A specific contact can also be retrieved using the GetContact method.

Retrieving a Contact by ID:

// Retrieve a contact by its ID string contactId = "12345"; // Replace with the actual contact ID office365.GetContact(contactId); // Access the retrieved contact var retrievedContact = office365.Contacts[office365.Contacts.Count - 1]; retrievedContact.FirstName; //first name retrievedContact.LastName; //last name retrievedContact.EmailAddressIndex=0; //set the index to zero to retrieve access the first email address retrievedContact.EmailAddress; //first email address value retrievedContact.PhonesIndex=0; //set the index to zero to retrieve access the first phone number retrievedContact.PhoneNumber; //first phone number value office365.GetContactField(office365.Contacts.Count - 1, "/json/birthday"); //birthday of the contact office365.GetContactField(office365.Contacts.Count - 1, "/json/middleName"); //middle name of the contact

Deleting Contacts

Contacts for the user can be deleted via the DeleteContacts method.

Delete a Contact:

// List contacts and search for a contact with the name "John Doe" office365.ListContacts("folder_id"); for (int i = 0; i < office365.Contacts.Count; i++) { if (office365.Contacts[i].DisplayName == "John Doe") { //Delete the contact office365.DeleteContact(office365.Contacts[i].Id); break; } }

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.