README.MD

Sitecore Send SDK (Unofficial)

Provides .NET wrapper around Sitecore Send API

Usage

var apiConfiguration = new ApiConfiguration
{
    ApiKey = "[YOUR API KEY]",
    Clients = new Dictionary<string, string>()
    {
        {"[YOUR CLIENT NAME / ALIAS]", "[YOUR CLIENT API KEY]"},
    },
};

ISendClient send = new SendClient(apiConfiguration);
var response = await send.Lists.GetAll();

// ensure response is not null and Success is true
if (response is {Success: true})
{
    IList<MailingList>? allLists = response.Data?.MailingLists;
    // handle allLists
}

// internal API
var internalApi = new InternalApi(InternalApiConfiguration.Create(apiConfiguration));
var allWebsites = await internalApi.Websites.GetAll();

Configuration with DI:

var apiConfiguration = new ApiConfiguration
{
    ApiKey = "[YOUR API KEY]",
    Clients = ...
};
serviceCollection.AddHttpClient("SitecoreSendClient",
    (client) => { client.BaseAddress = new Uri(apiConfiguration.BaseUri); });
serviceCollection.AddSingleton<ISendClient>(provider =>
{
    var factory = provider.GetRequiredService<IHttpClientFactory>();
    return new SendClient(apiConfiguration,
        () => factory.CreateClient("SitecoreSendClient"));
});

Transactional Campaigns

var request = EmailRequestBuilder.Start(campaign)
    .AddPersonalization(new Personalization(testEmail, "Igor Zharikov")
    {
        Substitutions = new Dictionary<string, string>()
        {
            {"orderNumber", "123456"},
            {"paymentMethod", "PayTest"},
            {"total", "123.00 USD"},
            {"complex", new
            {
               items = new List<string>() {"item1", "item2"},
            }},
        },
    })
    .AddAttachment(new EmailAttachment()
    {
        Content = AttachmentTool.StreamToBase64(File.OpenRead("icon.png")),
        Type = "image/png",
        FileName = "icon.png",
    })
    .Build();

var result = await _send.Transactional.Send(request);

Clients switcher

// 'Client1' should be added inside ApiConfiguration.Clients used in constructor
using (new ClientSwitcher("Client1"))
{
    var clientLists = await _send.Lists.GetAll();
    Assert.True(clientLists?.Success);
}

API Rate limit

Sitecore Send comes with API rate limits for subscribe/unsubscribe endpoints.

Handle within SDK

To check if rate limit occurred the following can be used:

var response = _send.Subscribers.Add(...);
// option 1:
if (response?.Code == KnownErrors.RATE_LIMITING) 
{
    ...
}
// option 2:
if (response?.RateLimitDetails != null)
{
    ...
}

Current library supports handling of them with 'Wrapping' limited methods with configured policies.

Polly

The following Polly policies configuration can be used: link.

Currently, applies only for SubscribersService:

new SendClient(
    apiConfiguration,
    httpClientFactory, 
    new RateLimiterConfiguration()
    {
        Subscribers = new SubscribersWrapper()
        {
            AddSubscriber = SendRateLimits.AddSubscriber.ExecuteAsync,
            AddMultipleSubscribers = SendRateLimits.AddMultipleSubscribers.ExecuteAsync,
            UnsubscribeFromAllLists = SendRateLimits.UnsubscribeFromAllLists.ExecuteAsync,
            UnsubscribeFromList = SendRateLimits.UnsubscribeFromList.ExecuteAsync,
            UnsubscribeFromListAndCampaign = SendRateLimits.UnsubscribeFromListAndCampaign.ExecuteAsync,
        },
    }
);

Avoid rate limit issues

Whenever possible use Get, Update methods of ISendClient.Subscribers.

E.g. if you need to ensure user exists in the list, use extension methods:

// check if subscriber exists => then update, if not => create
_send.Subscribers.CreateOrUpdate(listId, ...);

// check if user is subscribed to the list, if subscribeIfNotExists == true => subscribe to list
_send.Subscribers.EnsureSubscribed(listId, email, subscribeIfNotExists);

Integration tests

Overview

Integration tests are located in SitecoreSend.SDK.Tests project.

Running locally

Create file appsettings.local.jsonc based on appsettings.jsonc in SitecoreSend.SDK.Tests project and populate it with your own values.

Contribute / Bug / Help

You can contact me via email or in Sitecore Slack: zharikovigor97@gmail.com. Or please open an issue.

Roadmap

Documented API

• Mailing list service
• Subscribers service
• Campaigns service
• Segments service
• Transactional Campaigns Methods

Internal API

• Websites management (WIP)
• Automations
• Senders API
• Landing Pages

Tracking API

• Tracking API

SMTP API

• SMTP: use SmtpClient together with SitecoreSend.SDK.Extensions.SmtpExtensions