Home

Awesome

CakeMail.RestClient

License Build status Coverage Status CodeFactor FOSSA Status

About

CakeMail.RestClient is a C# client for the CakeMail service through its RESTful API.

Nuget

CakeMailRestAPI is available as a Nuget package.

NuGet Version

Pre-release packages are available on my MyGet feed:

MyGet Pre Release

Release Notes

var subject = "Special sale ends today";
var html = "<html><body>[IF `gender` = \"Male\"]Men's clothing is on sale[ELSE]Women's clothing is on sale[ENDIF]</body></html>";
var text = "[IF `gender` = \"Male\"]Men's clothing is on sale[ELSE]Women's clothing is on sale[ENDIF]";
var mergeData = new Dictionary<string, object>
{
    { "gender", "Male" }
};
var sent = await client.Relays.SendWithoutTrackingAsync(userKey, "recipient@example.com", subject, html, text, "you@yourcompany.com", "Your name", mergeData, null, null, clientId, cancellationToken).ConfigureAwait(false);

var subject = "Special sale ends today";
var html = "<html><body>Dear [firstname, friend], our annual sale ends <b>today</b> [TODAY | MMMM d].</body></html>";
var text = "[salutation] [lastname], our annual sale ends <b>today</b> [TODAY | MMMM d].";
var mergeData = new Dictionary<string, object>
{
    { "salutation", "Mr." },
    { "firstname", "Bob" },
    { "lastname", "Smith" }
};
var sent = await client.Relays.SendWithoutTrackingAsync(userKey, "recipient@example.com", subject, html, text, "you@yourcompany.com", "Your name", mergeData, null, null, clientId, cancellationToken).ConfigureAwait(false);

This means, for example, that the following v3.0 call:

var count = cakeMail.Campaigns.GetCount(userKey, MailingStatus.Ongoing);

Has been replaced with the following v4.0 call :

var count = await cakeMail.Campaigns.GetCountAsync(userKey, MailingStatus.Ongoing);

This means, for example, that the following v2.0 call:

var count = cakeMail.GetCampaignsCount(userKey, MailingStatus.Ongoing);

Has been replaced with the following v3.0 call :

var count = cakeMail.Campaigns.GetCount(userKey, MailingStatus.Ongoing);

Installation

The easiest way to include CakeMail.RestClient in your C# project is by grabing the nuget package:

PM> Install-Package CakeMail.RestClient

Once you have the CakeMail.RestClient library properly referenced in your project, add the following namespace:

using CakeMail.RestClient;

Usage

Login

var apiKey = "... your api key ...";
var userName = "youremail@whatever.com";
var password = "yourpassword";

var cakeMail = new CakeMailRestClient(apiKey);

var loginInfo = await cakeMail.Users.LoginAsync(userName, password);
var userKey = loginInfo.UserKey;

Quick note regarding the user key: this value is valid for several days (I don't know exactly how long though) and therefore can be cached for a reasonable period of time. There is no need to repeatedly invoke the 'Login' method to get this value.

Campaigns

A campaign is simply a way to logically group mailings toghether. You can think of campaigns as 'folders'. In fact, the CakeMail UI has a "Manage folders" button under the "Campaigns" tab where you will see all the campaigns. A word of caution: the word 'Campaign' is used in the CakeMail UI to refer to mailings which is really confusing!

var campaigns = await cakeMail.Campaigns.GetCampaignsAsync(userKey, status: MailingStatus.Ongoing, sortBy: MailingSortBy.Name, sortDirection: SortDirection.Ascending, limit: 50, offset: 0);
var campaignsCount = await cakeMail.Campaigns.GetCountAsync(userKey, MailingStatus.Ongoing);

var campaignId = await cakeMail.Campaigns.CreateAsync(userKey, "2015 User Conference");
var campaign = await cakeMail.Campaigns.GetAsync(userKey, campaignId);
var deleted = await cakeMail.Campaigns.DeleteAsync(userKey, campaignId);

Lists

A List is a collection of subscribers (or List Members, or Records). Each subscriber or List Member is uniquely identified by their email address, and may include an limited amount of Fields containing demographic information associated to each email address.


var lists = await cakeMail.Lists.GetListsAsync(userKey, sortBy: ListSortBy.Name, sortDirection: SortDirection.Descending, limit: 50, offset: 0);
var listsCount = await cakeMail.Lists.GetCountAsync(userKey);

var listId = await cakeMail.Lists.CreateAsync(userKey, "Customers and Prospects", "The XYZ Marketing Group", "marketing@yourcompany.com", true);
await cakeMail.Lists.AddFieldAsync(userKey, listId, "first_name", "text");
await cakeMail.Lists.AddFieldAsync(userKey, listId, "last_name", "text");
await cakeMail.Lists.AddFieldAsync(userKey, listId, "customer_since", "datetime");

You can add members to your list like so:


await cakeMail.Lists.SubscribeAsync(userKey, listId, "bob_the_customer@hotmail.com", true, true, new[]
{
    new KeyValuePair<string, object>("first_name", "Bob"), 
    new KeyValuePair<string, object>("last_name", "Smith"), 
    new KeyValuePair<string, object>("customer_since", DateTime.UtcNow) 
});
await cakeMail.Lists.SubscribeAsync(userKey, listId, "jane_the_prospect@hotmail.com", true, true, new[]
{
    new KeyValuePair<string, object>("first_name", "Jane"), 
    new KeyValuePair<string, object>("last_name", "Doe")
});

or you can import a group of members:

var member1 = new ListMember()
{
    Email = "bob_the_customer@hotmail.com",
    CustomFields = new Dictionary<string, object>()
    {
        { "first_name", "Bob" },
        { "last_name", "Smith" },
        { "customer_since", DateTime.UtcNow }
    }
};

var member2 = new ListMember()
{
    Email = "jane_the_prospect@hotmail.com",
    CustomFields = new Dictionary<string, object>()
    {
        { "first_name", "Jane" },
        { "last_name", "Doe" }
    }
};

var importResult = await cakeMail.Lists.ImportAsync(userKey, listId, new[] { member1, member2 });

Mailings

A mailing is an email campaign. It can be used to send standard email campaigns, A/B split campaigns or recurring campaigns.

var invitationMailingId = await cakeMail.Mailings.CreateAsync(userKey, "2015 User Conference invitation", campaignId);
await cakeMail.Mailings.UpdateAsync(userKey, invitationMailingId, listId: listId, htmlContent: "<html><body>You are invited to attend our annual user conference</body></html>", textContent: "You are invited to attend our annual user conference", subject: "Invitation to our 2015 user conference");
await cakeMail.Mailings.SheduleAsync(userKey, invitationMailingId);

var reminderMailingId = await cakeMail.Mailings.CreateAsync(userKey, "2015 User Conference reminder", campaignId);
await cakeMail.Mailings.UpdateAsync(userKey, reminderMailingId, listId: listId, htmlContent: "<html><body>Don't forget our upcoming annual user conference</body></html>", textContent: "Don't forget our upcoming annual user conference", subject: "Reminder about our 2015 user conference");
await cakeMail.Mailings.SheduleAsync(userKey, reminderMailingId, DateTime.UtcNow.AddDays(2));

License

FOSSA Status