Sending Emails

SocialStack aims to have one way of rendering content which is going out to end users by default; i.e. if someone is visiting via the web they'll see React components. If they see an email it's the same - the server renders React components into the email for them. So, creating an email is somewhat similar to creating a page - the only notable difference is it's done in the "Email Templates" section of the admin panel, and the components used need to be email friendly. Most email clients don't currently support things like flexbox for example.

Email Key

Once you've created an email template, make sure you give it a key. This value is a textual ID for your template which you should avoid changing once created - that's because it is referenced from the codebase. It is typically in English, lowercase and contains underscores instead of spaces. This key is then what is used to send the email in the API, typically in an AfterCreate/ AfterUpdate/ time based event handler.

Sending a particular template

To send a template, use the EmailTemplateService.Send method:

User aUserObject; // The User you want to send the email to.

var recipients = new List<Recipient>();
recipients.Add(new Recipient(aUserObject)); // Add as many recipients as you'd like
				
await emails.SendAsync(
	recipients,
	"template_to_send" // The email template key goes here
);

Custom Data

Firstly, an email can use Loop, Content and more generally webRequest. When this happens it is in the context of the user receiving the email and the locale used is based on the LocaleId of the User object.

Often though when you send an email it will contain some dynamic information - i.e. information which is specific to "this" email. For example in a password reset request, the email contains a URL with a token which is unique to the reset request. This is done by passing "Custom data" which is set per recipient, allowing each recipient to vary too.

EmailTemplateService emails; // Either via Services.Get<EmailTemplateService>() or pulled in by your service constructor (dependency injection)

User aUserObject; // The User you want to send the email to.

var recipients = new List<Recipient>();
var recipient = new Recipient(aUserObject);

recipient.CustomData = new {       // This object must be JSON serialisable.
    Token = "SomeMagicTokenValue"
};

recipients.Add(recipient); // Add as many recipients as you'd like
				
await emails.SendAsync(
	recipients,
	"template_to_send" // The email template key goes here
);

The custom data acts like the primary object on the page. This then means there are a few ways of accessing the values - for example, via Content:

import Content from 'UI/Content';

..

<Content primary>
    {customData => {
        return customData.token + ' is the token!';
    }}
</Content>

Or, the more popular way in emails, with a token resolver:

import {useTokens} from 'UI/Token';


..

// Usually passed in as a prop allowing people to change or translate the sentence in the email editor
var inputTitle = 'The force is strong with tokens like ${customData.token}';

// useTokens will swap out the ${tokens} for their actual value.
var processedTitle = useTokens(inputTitle);

// We're inside a react render function:
return <h1>{processedTitle}</h1>;