The dll can be downloaded from (github.com/downloads/messagebus/messagebus_csharp_api/MessageBus.dll)
git clone git@github.com:messagebus/messagebus_csharp_api.git
var client = MessageBusFactory.CreateEmailClient("<Your API Key Here>");
var client = MessageBusFactory.CreateStatsClient("<Your API Key Here>");
var client = MessageBusFactory.CreateMailingListClient("<Your API Key Here>");
(For more options please see “Advanced Usage”).
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.
.
.
.
}
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.
.
.
.
}
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.
.
.
.
}
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;
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 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.
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
If you have any questions or problems, please contact Message Bus (www.messagebus.com/contact)