Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

C# client for MessageBus API

branch: master

This branch is 0 commits ahead and 0 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.rdoc

Message Bus C# API

Downloading the DLL

The dll can be downloaded from (github.com/downloads/messagebus/messagebus_csharp_api/MessageBus.dll)

Downloading the Source Code

git clone git@github.com:messagebus/messagebus_csharp_api.git

Sending Mail with Message Bus

Creating an instance of the Message Bus Email client:

var client = MessageBusFactory.CreateEmailClient("<Your API Key Here>");

Creating an instance of the Message Bus Stats client:

var client = MessageBusFactory.CreateStatsClient("<Your API Key Here>");

Creating an instance of the Message Bus Mailing List client:

var client = MessageBusFactory.CreateMailingListClient("<Your API Key Here>");

(For more options please see “Advanced Usage”).

Taking advantage of bufferring

The Message Bus API buffers e-mail on the client and transmits email to the server in batches. This behaviour can be managed with the following operations:

To set the number of emails to buffer before automatically sending (the default value is 20):

client.EmailBufferSize = 100; // sets the number of emails to buffer before sending to 100.

Adding mail to the buffer is done as follows:

client.Send(new MessageBusEmail {
  ToEmail = "alice@example.com",
  FromEMail = "bob@example.com",
  Subject = "Test from Messagebus",
  PlaintextBody = "Hello",
  HtmlBody = "<html><body><h1>Hello!</h1></body></htm>"
});

Typically sending occurs in a loop over a list of recipients. Mail is transmitted to the server each time the buffer is full, but you will need to Flush the buffer once the looping is complete to ensure that the last few items in the buffer are transmitted. This is achieved as follows:

client.Flush();

Alternatively, the loop can be surrounded with a using {} block as follows:

var client = MessageBusFactory.CreateEmailClient("ABCD1234DEFA5678BCDE9012FABC3456");

try {
  using(client) {
    foreach(var item in MyMailingList) {
      client.Send(new MessageBusEmail {
        FromEmail = "apitest@messagebus.com",
        ToEmail = item.EmailAddress,
        Subject = "Hello from Message Bus",
        PlaintextBody = "Hello and Welcome!",
        HtmlBody = "<html><body><h1>Hello and Welcome!</h1></body></html>"
      });
    }
  }
} catch (MessageBusException e) {  // This exception occurs in the event of a server error.
  .
  .
  .
}

Sending pre-formatted email

Preformatted email is email in which the subject and body are composed before sending to Message Bus. The following example will send a single pre-formatted email via Message Bus:

var client = MessageBusFactory.CreateEmailClient("ABCD1234DEFA5678BCDE9012FABC3456");

try {
  using(client) {
    client.Send(new MessageBusEmail {
      FromEmail = "apitest@messagebus.com",
      ToEmail = "test@example.com",
      Subject = "Hello from Message Bus",
      PlaintextBody = "Hello and Welcome!",
      HtmlBody = "<html><body><h1>Hello and Welcome!</h1></body></html>"
    });
   }
} catch (MessageBusException e) { // This exception occurs in the event of a server error.
  .
  .
  .
}

Sending Template email

An ApiTemplate can be defined on the Message Bus website. In order to send mail using an ApiTemplate, copy the ApiTemplate key into your code, for example:

var client = MessageBusFactory.CreateEmailClient("ABCD1234DEFA5678BCDE9012FABC3456");

try {
  using(client) {
    var email = new MessageBusTemplateEmail { TemplateKey = "<YOUR TEMPLATE KEY>" };
    email.MergeFields.Add("%EMAIL%", "joe@example.com");
    email.MergeFields.Add("%NAME%", "Joe Soap");
    client.Send(email);
  }
} catch (MessageBusException e) { // This exception occurs in the event of a server error.
  .
  .
  .
}

Retrieving Email Send Message Status

Status results for transmissions of messages to the Message Bus server are returned via the standard C# event model. The event is triggered each time messages are transmitted to the server and contain a status for each message that has been sent. The statues are returned in the same order they were sent.

This is an example of handling the returned events:

First define a method to be called when messages are transmitted:

void OnTransmitted(IMessageBusTransmissionEvent transmissionEvent) {

  var numberOfMessagesThatFailed = transmissionEvent.FailureCount;
  var numberOfMessagesThatSucceeded = transmissionEvent.SuccessCount;

  // statuses are returned in the same order in which they are sent.
  foreach(var status in transmissionEvent.Statuses) {
    var toEmail = status.ToEmail; // The toEmail address
    var messageId = status.MessageId; // The MessageId of the message
    var code = status.Status; // The status code - 0 for success
  }
}

Next add the method to the event chain:

client.Transmitted += OnTransmitted;

Advanced Usage

Registering IMessageBusClient with and IoC Container

The following example shows how the Message Bus API can be used to inject the Message Bus Client into application services. This example using the CastleWindsor IoC container.

This is a snippet from the component registration:

public static void AddComponentsTo(IWindsorContainer container) {
  .
  .
  container.AddComponentLifeStyle("MessageBusEmailClient", typeof(IMessageBusEmailClient), typeof(AutoBatchingClient), Castle.Core.LifestyleType.Singleton);
  container.AddComponentLifeStyle("MessageBusStatsClient", typeof(IMessageBusStatsClient), typeof(DefaultStatsClient), Castle.Core.LifestyleType.Singleton);
  container.AddComponentLifeStyle("MessageBusMailingListClient", typeof(IMessageBusMailingListClient), typeof(DefaultMailingListClient), Castle.Core.LifestyleType.Singleton);
  .
  .
  .
}

This is a snippet from the XML configuration file:

<configuration>
 .
 .
  <components>
      <component id="MessageBusEmailClient">
          <parameters>
            <apiKey>ABCD1234DEFA5678BCDE9012FABC3456</apiKey>
          </parameters>
      </component>
      <component id="MessageBusStatsClient">
          <parameters>
            <apiKey>ABCD1234DEFA5678BCDE9012FABC3456</apiKey>
          </parameters>
      </component>
      <component id="MessageBusMailingListClient">
          <parameters>
            <apiKey>ABCD1234DEFA5678BCDE9012FABC3456</apiKey>
          </parameters>
      </component>
  </components>
  .
  .
</configuration>

Logging

Logging is disabled by default. Simple console logging is supplied and can be enabled as follows:

var client = MessageBus.CreateEmailClient("ABCD1234DEFA5678BCDE9012FABC3456", new ConsoleLogger());

Logging can be made to conform with the standards of the client application by supplying a custom implementation of the ILogger interface.

License

Copyright © 2012. Mail Bypass, Inc.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License

More Info

If you have any questions or problems, please contact Message Bus (www.messagebus.com/contact)

Something went wrong with that request. Please try again.