Mail Providers: IMailOutbound Interface

Background

The QBO Message modules includes an IMailOutbound interface that defines a contract excepted to send emails.  There are several implementations of the interface, including:
  • SMTP: the qbo.Message.Providers.Smtp class uses Microsoft's SmtpClient class to deliver emails to an SMTP provider
  • Simple Email Services (SES): the qbo.Message.Amazon.SES provider leverages Amazon's SES platform to deliver messages over HTTP
  • SESValidator: an extension of the SES provider that checks all recipients against a list of invalid recipients, to assist with implementing CAN-SPAM act requirements
  • Twilio: qbo.Message.Twilio.SMS provides a Simple Messaging Service (SMS) relay via Twilio's telephony platform
Additional providers may be created to handle custom requirements, like invoking a corporate web service to deliver emails via a corporate SMTP server.

Configuration

There are two configuration files relevant to email deliver:
  • MailOutbound.config: specifies the providers used by a particular installation
  • Credential.config: contains credentials for SMTP, SES, or other providers that need credentials to authenticate
MailOutbound.config sample:

<?xml version="1.0"?>
<MailOutbound>
<Providers>
<!-- Using Gmail as a provider may required app-specific credentials, particularly if you use two-factor authentication. -->
<MailOutbound Name="Google" Host="smtp.gmail.com" Port="587" EnableSsl="true" Type="qbo.Message.Providers.Smtp, qbo.Message"/>

<!-- This entry depends on the Twilio account created in testing to be active. You can create a new Twilio account, allocate a new number, and enter that number into the Host attribute. -->
<MailOutbound Name="SMS" Host="https://api.twilio.com/2010-04-01/+14242171014" EnableSsl="true" Type="qbo.Message.Twilio.SMS, qbo.Message.Twilio"/>

<!-- Amazon SES Plugin. Requires corresponding Credential entry-->
<MailOutbound Name="SES" Host="us-east-1" Port="0" EnableSsl="true" Type="qbo.Message.Amazon.SES, qbo.Message.Amazon"/>
</Providers>
</MailOutbound>

Notes:
  • Unless otherwise specifies, the first entry in the configuration will be the default entry used to deliver emails
  • All the examples above require a corresponding entry in the Credential.config file
  • Gmail may require application-specific credentials be defined
  • The Name attribute is referred to as the Provider
    • e.g. calling Message/Send?ToAddress=you@me.com&Subject=Test&Provider=SES would use the provider mapped to Name="SES"

Credential.config sample:

<?xml version="1.0"?>
<Credentials>
<CredentialCache>
<!-- Gmail credential -->
<Credential UriPrefix="smtp://smtp.gmail.com/" AuthType="Basic" Username="user" Password="password" Domain="" />

<!--Amazon SES matching mailer@quandis.com-->
<Credential UriPrefix="smtp://us-east-1/" AuthType="Basic" Username="AAABBBCCC" Password="xxxyyyzzz" Domain="" />

</CredentialCache>
</Credentials>

Notes:
  • The credential is matched to the mail provider via the UriPrefix starting with smtp://

Testing

To test email configuration, simply invoke the QBO Message/Send method:

// Test the generic provider
Message/Message.ashx/Send?ToAddress={your email address}&Subject=Test Email

// Test a specific provider
Message/Message.ashx/Send?ToAddress={your email address}&Subject=Test Email&Provider=SES





Comments