OAuth | Blog | Limilabs

System.Net.Mail vs Mail.dll

Limilabs support — Mon, 17 Dec 2012 16:27:01 +0000

In this article we’ll try to describe advantages of Mail.dll over standard .NET System.Net.Mail namespace.

The fundamental difference is that with System.Net.Mail you can’t receive emails. System.Net.Mail does not have support for POP3 and IMAP protocols – two fundamental protocols for email retrieval, also .NET does not have any classes that would parse received email.

System.Net.Mail is great for sending simple emails, but Mail.dll gives you much more, even in terms of sending. You get appointments (iCal) and vCard support, you can send S/MIME signed and encrypted emails (if you plan to use EDI). It gives you easy to use template engine and VERP support out-of-the-box.

Here’s the comparison chart:

	System.Net.Mail	Mail.dll component
Send emails
SMTP protocol support (over SSL/TLS)
Send emails using VERP
Send S/MIME encrypted emails
Send S/MIME signed emails
Send S/MIME signed emails (detached)
Send DKIM (Domain Key Identified Mail)
Templates support
Receive emails
IMAP protocol support (over SSL/TLS)
POP3 protocol support (over SSL/TLS)
Retrieve and parse emails
Extract HTML, plain text, images
Attachment retrieval
Send and retrieve iCalendar appointments
Send and retrieve vCards
OAuth 1.1a/2.0 support
Spam filter
Bounce handling
Convert HTML only emails to plain text

If you need help or more information about any of these features visit Mail.dll samples.

The post System.Net.Mail vs Mail.dll first appeared on Blog | Limilabs.

Get Google contacts

Limilabs support — Fri, 13 Apr 2012 14:30:44 +0000

Consider using OAuth 2.0:
https://www.limilabs.com/blog/get-google-contacts-with-oauth2

Although neither POP3 nor IMAP protocol allows retrieving the list of user’s contacts, it is possible to use Google API for that.

As long as you are using OAuth to access Gmail, Mail.dll email component allows you to easy download Gmail contacts of a particular user.

// C#

GmailOAuth oauth = new GmailOAuth(_consumerKey, _consumerSecret);

List scopes = new List;
    {
        GoogleScope.EmailScope,
        GoogleScope.ContactsScope
    };

string authUrl = oauth.GetAuthorizationUrl("http://localhost:64119/", scopes);

// ASP.NET client:
// Save oauth in permanent storage:
// Cache[oauth.RequestToken.Token] = oauth;

// Windows client:
Process.Start(url);

// ASP.NET client:
// Response.Redirect(url);

// Windows client with url:
string rawReturnUrl = Console.ReadLine();
ReturnUrl returnUrl = new ReturnUrl(rawReturnUrl);
oauth.GetAccessToken(returnUrl.OAuthVerifier);

// Windows client with verification code (oob):
// string oauthVerifier = HttpUtility.UrlDecode(Console.ReadLine());
// oauth.GetAccessToken(oauthVerifier);

// ASP.NET client:
// ReturnUrl returnUrl = new ReturnUrl(Request.RawUrl);
// Retrieve oauth from permanent storage:
// GmailOAuth oauth = Cache[returnUrl.OAuthToken]
// oauth.GetAccessToken(returnUrl.OAuthVerifier);

GoogleApi google = new GoogleApi(oauth.ConsumerToken, oauth.AccessToken);

XmlDocument contacts = google.GetContacts();

XmlNamespaceManager nsmgr = new XmlNamespaceManager(contacts.NameTable);
nsmgr.AddNamespace("gd", "http://schemas.google.com/g/2005");
nsmgr.AddNamespace("a", "http://www.w3.org/2005/Atom");

foreach (XmlNode contact in contacts.GetElementsByTagName("entry"))
{
    XmlNode title = contact.SelectSingleNode("a:title", nsmgr);
    XmlNode email = contact.SelectSingleNode("gd:email", nsmgr);

    Console.WriteLine("{0}: {1}",
        title.InnerText,
        email.Attributes["address"].Value);
}

oauth.RevokeToken(oauth.AccessToken.Token);

' VB.NET

Dim oauth As New GmailOAuth(_consumerKey, _consumerSecret)

Dim scopes As New List(Of GoogleScope)() { _
	GoogleScope.EmailScope, _
	GoogleScope.ContactsScope _
}
Dim authUrl As String = oauth.GetAuthorizationUrl("http://localhost:64119/", scopes)

' ASP.NET client:
' Save oauth in permanent storage:
' Cache[oauth.RequestToken.Token] = oauth;

' Windows client:
Process.Start(url)

' ASP.NET client:
' Response.Redirect(url)

' Windows client with url:
Dim rawReturnUrl As String = Console.ReadLine()
Dim returnUrl As New ReturnUrl(rawReturnUrl)
oauth.GetAccessToken(returnUrl.OAuthVerifier)

' Windows client with verification code (oob):
' Dim oauthVerifier As String = HttpUtility.UrlDecode(Console.ReadLine())
' oauth.GetAccessToken(oauthVerifier)

' ASP.NET client:
' Dim returnUrl As New ReturnUrl(Request.RawUrl)
' Retrive oauth from permanent storage:
' Dim oauth As GmailOAuth = Cache(returnUrl.OAuthToken)
' oauth.GetAccessToken(returnUrl.OAuthVerifier)

Dim google As New GoogleApi(oauth.ConsumerToken, oauth.AccessToken)
Dim contacts As XmlDocument = google.GetContacts()

Dim nsmgr As New XmlNamespaceManager(contacts.NameTable)
nsmgr.AddNamespace("gd", "http://schemas.google.com/g/2005")
nsmgr.AddNamespace("a", "http://www.w3.org/2005/Atom")

For Each contact As XmlNode In contacts.GetElementsByTagName("entry")
	Dim title As XmlNode = contact.SelectSingleNode("a:title", nsmgr)
	Dim email As XmlNode = contact.SelectSingleNode("gd:email", nsmgr)
	Console.WriteLine("{0}: {1}", _
            title.InnerText, _
            email.Attributes("address").Value)
Next

oauth.RevokeToken(oauth.AccessToken.Token)

The post Get Google contacts first appeared on Blog | Limilabs.

OAuth 1.0 with Gmail (deprecated)

Limilabs support — Fri, 21 Oct 2011 17:27:39 +0000

OAuth 1.0 is deprecated, switch to OAuth 2.0:

OAuth is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.

In this post I’ll show how to access Gmail account using 3-legged OAuth authentication method with Mail.dll .NET IMAP component. The key advantage of this method is that it allows an application to access user email without knowing user’s password.

You can read more on OAuth authentication with Google accounts here:
http://code.google.com/apis/accounts/docs/OAuth_ref.html

Gmail IMAP and SMTP using OAuth:
http://code.google.com/apis/gmail/oauth/protocol.html

If your application/website is not registered, you should use following key and secret:
consumer key: “anonymous”
consumer secret: “anonymous”

Remember to add reference to Mail.dll and appropriate namespaces.

// C#

using Limilabs.Client.IMAP;
using Limilabs.Client.Authentication;
using Limilabs.Client.Authentication.Google;

const string consumerKey = "anonymous";
const string consumerSecret = "anonymous";

GmailOAuth oauth = new GmailOAuth(consumerKey, consumerSecret);

string url = oauth.GetAuthorizationUrl("http://localhost:64119/");

// ASP.NET client:
// Save oauth in permanent storage:
// Cache[oauth.RequestToken.Token] = oauth;

// Windows client:
Process.Start(url);

// ASP.NET client:
// Response.Redirect(url);

// Windows client with url:
string rawReturnUrl = Console.ReadLine();
ReturnUrl returnUrl = new ReturnUrl(rawReturnUrl);
oauth.GetAccessToken(returnUrl.OAuthVerifier);

// Windows client with verification code (oob):
// string oauthVerifier = HttpUtility.UrlDecode(Console.ReadLine());
// oauth.GetAccessToken(oauthVerifier);

// ASP.NET client:
// ReturnUrl returnUrl = new ReturnUrl(Request.RawUrl);
// Retrieve oauth from permanent storage:
// GmailOAuth oauth = Cache[returnUrl.OAuthToken]
// oauth.GetAccessToken(returnUrl.OAuthVerifier);

using (Imap client = new Imap())
{
    client.ConnectSSL("imap.gmail.com");
    string oauthImapKey = oauth.GetXOAuthKeyForImap();
    client.LoginOAUTH(oauthImapKey);

    // Now you can access user's emails
    //...

    client.Close();
    oauth.RevokeToken(oauthImapKey);
}

1.
GmailOAuth.GetAuthorizationUrl method returns url you should redirect your user to, so he can authorize access.
As you can see, Mail.dll is asking for access to user’s email information and Gmail access:

2.
If you don’t specify callback parameter, user will have to manually copy&paste the token to your application (oob):

In case of a web project, you can specify a web address on your website. oauth_verifier will be included as the redirection url parameter.

After the redirection, your website/application needs to read oauth_verifier query parameter:

3.
GmailOAuth.GetAccessToken method authorizes the token.

4.
GmailOAuth.GetXOAuthKeyForImap method uses Google API to get the email address of the user, and generates XOAuth key for IMAP protocol (you can use GetXOAuthKeyForSmtp for SMTP).

5.
GmailOAuth.RevokeToken method revokes XOAuth key, so no further access can be made with it.

…and finally VB.NET version of the code:

' VB.NET

Imports Limilabs.Client.IMAP
Imports Limilabs.Client.Authentication
Imports Limilabs.Client.Authentication.Google

Const  consumerKey As String = "anonymous"
Const  consumerSecret As String = "anonymous"

Dim oauth As New GmailOAuth(consumerKey, consumerSecret)

Dim url As String = oauth.GetAuthorizationUrl("http://localhost:64119/")

' ASP.NET client:
' Save oauth in permanent storage:
' Cache[oauth.RequestToken.Token] = oauth;

' Windows client:
Process.Start(url)

' ASP.NET client:
' Response.Redirect(url)

' Windows client with url:
Dim rawReturnUrl As String = Console.ReadLine()
Dim returnUrl As New ReturnUrl(rawReturnUrl)
oauth.GetAccessToken(returnUrl.OAuthVerifier)

' Windows client with verification code (oob):
' Dim oauthVerifier As String = HttpUtility.UrlDecode(Console.ReadLine())
' oauth.GetAccessToken(oauthVerifier)

' ASP.NET client:
' Dim returnUrl As New ReturnUrl(Request.RawUrl)
' Retrive oauth from permanent storage:
' Dim oauth As GmailOAuth = Cache(returnUrl.OAuthToken)
' oauth.GetAccessToken(returnUrl.OAuthVerifier)

Using client As New Imap()
	client.ConnectSSL("imap.gmail.com")
	Dim oauthImapKey As String = oauth.GetXOAuthKeyForImap()
	client.LoginOAUTH(oauthImapKey)

	' Now you can access user's emails
	'...

	client.Close()
	oauth.RevokeToken(oauthImapKey)
End Using

The post OAuth 1.0 with Gmail (deprecated) first appeared on Blog | Limilabs.

2-legged OAuth with Gmail

Limilabs support — Fri, 21 Oct 2011 16:31:02 +0000

OAuth is deprecated switch to using OAuth 2.0:

OAuth is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.

In this post I’ll show how to access Gmail account using 2-legged OAuth authentication method and .NET IMAP component. The basic idea is that domain administrator can use this method to access user email without knowing user’s password.

You can read more on OAuth authentication with Google accounts here:
http://code.google.com/apis/accounts/docs/OAuth_ref.html

Gmail IMAP and SMTP using OAuth:
http://code.google.com/apis/gmail/oauth/protocol.html

Remember to add reference to Mail.dll and appropriate namespaces.

// C#

using Limilabs.Client.IMAP;
using Limilabs.Client.Authentication;
using Limilabs.Client.Authentication.Google;

const string consumerKey = "example.com";
const string consumerSecret = "secret";
const string email = "pat@example.com";

Gmail2LeggedOAuth oauth = new Gmail2LeggedOAuth(
    consumerKey, consumerSecret);

using (Imap client = new Imap())
{
    client.ConnectSSL("imap.gmail.com");

    string oauthImapKey = oauth.GetXOAuthKeyForImap(email);

    client.LoginOAUTH(oauthImapKey);

    //...

    client.Close();
}

' VB.NET

Imports Limilabs.Client.IMAP
Imports Limilabs.Client.Authentication
Imports Limilabs.Client.Authentication.Google

Const  consumerKey As String = "example.com"
Const  consumerSecret As String = "secret"
Const  email As String = "pat@example.com"

Dim oauth As New Gmail2LeggedOAuth(consumerKey, consumerSecret)

Using client As New Imap()
	client.ConnectSSL("imap.gmail.com")

	Dim oauthImapKey As String = oauth.GetXOAuthKeyForImap(email)

	client.LoginOAUTH(oauthImapKey)

	'...

	client.Close()
End Using

Here are the google apps configuration screens:

The post 2-legged OAuth with Gmail first appeared on Blog | Limilabs.

Gmail extensions in Mail.dll

Limilabs support — Mon, 13 Jun 2011 13:05:11 +0000

Here’s the list of Gmail IMAP protocol extensions implemented in Mail.dll:

Extension of the LIST command: XLIST
Extension of the SEARCH command: X-GM-RAW
Access to the Gmail unique message ID: X-GM-MSGID
Access to the Gmail thread ID: X-GM-THRID
Access to Gmail labels: X-GM-LABELS
OAuth and OAuth 2.0: XOAUTH, XOAUTH2

You can read on how to use Mail.dll with Gmail in the following articles:

OAuth 2.0

OAuth 1.0

The post Gmail extensions in Mail.dll first appeared on Blog | Limilabs.

2-legged OAuth with IMAP

Limilabs support — Wed, 12 Jan 2011 20:09:42 +0000

OAuth is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.

This article describes generic OAuth class.
If you are using Gmail please read 2-legged OAuth authentication with Gmail.

Remember to add reference to Mail.dll .NET IMAP component and appropriate namespaces.

// C#

using Limilabs.Client.Authentication;
using Limilabs.Client.IMAP;

string consumerKey = "your_domain.com";
string consumerSecret = "your_oauth_consumer_secret";
string emailAccount = "address@your_domain.com";

using (Imap client = new Imap())
{
    client.ConnectSSL("imap.gmail.com");

    string imapUrl = string.Format(
        "https://mail.google.com/mail/b/{0}/imap/?xoauth_requestor_id={1}",
        emailAccount,
        HttpUtility.UrlEncode(emailAccount));

    string oauthImapKey = OAuth.ForUrl(imapUrl)
        .Consumer(consumerKey, consumerSecret)
        .SignatureMethod(SignatureType.HMACSHA1)
        .Sign()
        .GetXOAuthKey();

    client.LoginOAUTH(oauthImapKey);

    //...

    client.Close();
}

' VB.NET

Imports Limilabs.Client.Authentication
Imports Limilabs.Client.IMAP

Dim consumerKey As String = "example.com"
Dim consumerSecret As String = "secret"
Dim emailAccount As String = "pat@example.com"

Using client As New Imap()
    client.ConnectSSL("imap.gmail.com")

    Dim imapUrl As String = String.Format( _
        "https://mail.google.com/mail/b/{0}/imap/?xoauth_requestor_id={1}", _
        emailAccount, _
        HttpUtility.UrlEncode(emailAccount))

    Dim oauthImapKey As String = OAuth.ForUrl(imapUrl) _
        .Consumer(consumerKey, consumerSecret) _
        .SignatureMethod(SignatureType.HMACSHA1) _
        .Sign() _
        .GetXOAuthKeyForImap()

    client.LoginOAUTH(oauthImapKey)

    '...

    client.Close()
End Using

The post 2-legged OAuth with IMAP first appeared on Blog | Limilabs.

OAuth 1.0 with IMAP (deprecated)

Limilabs support — Mon, 28 Jun 2010 19:44:43 +0000

OAuth is an open protocol to allow secure API authorization for Mail.dll email client in a simple and standard method from desktop and web applications.

OAuth 1.0 is deprecated, switch to OAuth 2.0:

The following code makes several HTTP requests to authenticate your application. It also fires up the web browser, so the user can allow or deny the application to access his emails.

Remember to add reference to Mail.dll .NET email component and appropriate namespaces.

// C#

using Limilabs.Client.Authentication;
using Limilabs.Client.IMAP;

const string consumerKey = "anonymous";
const string consumerSecret = "anonymous";

// Get request token
ParameterList parameters1 = OAuth.ForUrl(
        "https://www.google.com/accounts/OAuthGetRequestToken")
    .Consumer(consumerKey, consumerSecret)
    .AddParameter("scope", "https://mail.google.com/")
   .AddParameter(OAuthParameterName.OAuthCallback, "oob")
    .Sign()
    .ExecuteWebRequest();

// Authorize token
string url2 = OAuth.ForUrl(
        "https://www.google.com/accounts/OAuthAuthorizeToken")
   .Consumer(consumerKey, consumerSecret)
   .Token(parameters1.GetValue(OAuthParameterName.OAuthToken))
   .TokenSecret(parameters1.GetValue(OAuthParameterName.OAuthTokenSecret))
   .Sign()
   .GetUrl();

// Fire up the browser.
Process.Start(url2);
// You can use Response.Redirect(url) in ASP.NET

2.
The user needs now to log-in to Gmail account (note that user does not enter credentials in your application):

3.
Then he needs to allow your application to access Gmail:

4.
If you don’t specify callback parameter, user will have to manually copy&paste the token to your application:

In case of a web project, instead of oob value as OAuthCallback parameter, you can specify a web address on your website. oauth_verifier will be included as the redirection url parameter.

After the redirection, your website/application needs to read oauth_verifier query parameter:

// C#

Console.WriteLine("Please enter the key: ");
string oauth_verifier = Console.ReadLine();
// You can use Request["oauth_verifier"].ToString() in ASP.NET

// Get access token
ParameterList parameters3 = OAuth.ForUrl(
        "https://www.google.com/accounts/OAuthGetAccessToken")
   .Consumer(consumerKey, consumerSecret)
   .Token(parameters1.GetValue(OAuthParameterName.OAuthToken))
   .TokenSecret(parameters1.GetValue(OAuthParameterName.OAuthTokenSecret))
   .AddParameter("oauth_verifier", oauth_verifier)
   .Sign()
   .ExecuteWebRequest();

// Log-in to IMAP server using XOAuth
using (Imap client = new Imap())
{
    client.ConnectSSL("imap.gmail.com");

    string imapUrl = string.Format(
        "https://mail.google.com/mail/b/{0}/imap/", userEmailAccount);

    string oauthImapKey = OAuth.ForUrl(imapUrl)
        .Consumer(consumerKey, consumerSecret)
        .Token(parameters3.GetValue(OAuthParameterName.OAuthToken))
        .TokenSecret(parameters3.GetValue(OAuthParameterName.OAuthTokenSecret))
        .Sign()
        .GetXOAuthKey();

    client.LoginOAUTH(oauthImapKey);

    // Now you can access user's emails.
    //...

    client.Close();
}

Here’s the VB.NET version of the code samples:

Remember to add reference to Mail.dll and appropriate namespaces.

' VB.NET

import Limilabs.Client.Authentication
import Limilabs.Client.IMAP

Const  consumerKey As String = "anonymous"
Const  consumerSecret As String = "anonymous"

' Gget request token
Dim parameters1 As ParameterList = OAuth _
	.ForUrl("https://www.google.com/accounts/OAuthGetRequestToken") _
	.Consumer(consumerKey, consumerSecret) _
	.AddParameter("scope", "https://mail.google.com/") _
	.AddParameter(OAuthParameterName.OAuthCallback, "oob") _
	.Sign() _
	.ExecuteWebRequest()

' Authorize token
Dim url2 As String = OAuth _
	.ForUrl("https://www.google.com/accounts/OAuthAuthorizeToken") _
	.Consumer(consumerKey, consumerSecret) _
	.Token(parameters1.GetValue(OAuthParameterName.OAuthToken)) _
	.TokenSecret(parameters1.GetValue(OAuthParameterName.OAuthTokenSecret)) _
	.Sign() _
	.GetUrl()

' Fire up the browser
Process.Start(url2)
' You can use Response.Redirect(url) in ASP.NET

2.
First the user needs to log in to Gmail account (note that user does not enter credentials in your application):

3.
Then he needs to allow your application to access Gmail:

4.
If you don’t specify callback parameter, user will have to manually copy&paste the token to your application:

In case of a web project, instead of oob value as OAuthCallback parameter, you can specify a web address on your website. oauth_verifier will be included as the redirection url parameter.

After the redirection, your website/application needs to read oauth_verifier query parameter:

' VB.NET

Console.WriteLine("Please enter the key: ")
Dim oauth_verifier As String = Console.ReadLine().Trim()
' You can use Request("oauth_verifier").ToString() in ASP.NET

' Third: get access token
Dim parameters3 As ParameterList = OAuth _
	.ForUrl("https://www.google.com/accounts/OAuthGetAccessToken") _
	.Consumer(consumerKey, consumerSecret) _
	.Token(parameters1.GetValue(OAuthParameterName.OAuthToken)) _
	.TokenSecret(parameters1.GetValue(OAuthParameterName.OAuthTokenSecret)) _
	.AddParameter("oauth_verifier", oauth_verifier) _
	.Sign() _
	.ExecuteWebRequest()

' Log-in to IMAP server using XOAuth
Using client As New Imap()
	client.ConnectSSL("imap.gmail.com")

	Dim imapUrl As String = String.Format("https://mail.google.com/mail/b/{0}/imap/", userEmailAccount)

	Dim oauthImapKey As String = OAuth.ForUrl(imapUrl) _
		.Consumer(consumerKey, consumerSecret) _
		.Token(parameters3.GetValue(OAuthParameterName.OAuthToken)) _
		.TokenSecret(parameters3.GetValue(OAuthParameterName.OAuthTokenSecret)) _
		.Sign() _
		.GetXOAuthKeyForImap()

	client.LoginOAUTH(oauthImapKey)

	' Now you can access user's emails.
	' ...

	client.Close()
End Using

The post OAuth 1.0 with IMAP (deprecated) first appeared on Blog | Limilabs.