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 (Outlook) 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.