Integration

The service expose several messages and events to track the creation and email status.

A EmailingClientModule is provided along with an IEmailManager that supplies a method SendEmail. The email Attachments are handled by the FileStorage service, you can find more information at:

• Backend Client

The module needs to be imported to the project references:

<ProjectReference Include="$(ServicesPath)Emailing/ITsynch.Suite.Emailing.ClientModule/ITsynch.Suite.Emailing.ClientModule.csproj" />

And update the application module by depending on the EmailingClientModule:

public override void SetupModule(IModuleBuilder builder)
{
    base.SetupModule(builder);

    builder.DependsOn<EmailingClientModule>();
}

Then to create and send an Email, simple inject the IEmailingManager and use the SendEmail method configuring the required fields of the EmailBuilder.

The SendEmail method handle:

• Email Log.
• Check and Upload Files to the FileStorage.
• Create Email.
• Publish of the CreateEmail message.

The EmailBuilder helps to configure the basic requirements to send an email. It allows in the creation to set the following properties:

• Subject: the subject of the email (required).
• Body: the body of the email (required).
• To: list of email addresses to send the email (required).
• Attachments: list of file stream to send with the email (optional).
• From: service or application of origin where the email comes from (optional). If not value is set, the API will use the one by default in settings.
• Ttl: time to live of the email, is expressed in days and indicates how long it will take to be deleted (optional). If not value is set, the API will use the one by default in settings.

public class MyClass
{
    private readonly IEmailManager emailManager;

    public MyClass(
        IEmailManager emailManager)
    {
        this.emailManager = emailManager;
    }

    public async Task MyMethodA() 
    {
        // This Method send an Email without Attachments.
        await this.emailManager.SendEmail(
            config => {
                c.Subject = "Email Subject...";
                c.Body = "Email Body";
                c.To = new string[] { "to@email.com" };  // List of Addresses to send the message.
            }
        );
    }
}

Configuration

The EmailingClientModule counts with an EmailingClientModuleOptions to configure different working aspects of it.

It allows to configure:

• From: this value is used as default email address when an Email is sent without setting the from parameter.
• Source: This is a required setting, it's part of the identity of the email, and is used to track from where the email was created.
• EmailsTTL: Sets the Emails time to live. This means after the set value the emails should be deleted. By default is 180 days, and has a minimum requirement of 1 day.
• AttachmentsOffsetTTL: This TTL offset is in addition to EmailsTTL, so attachments are always removed after the email. By default is 2 days, and has a minimum requirement of 0 days.

If we make use of the EmailingClientModule, we need to ensure these options are set.

Follow Email status

A sequence of messages about the status of an email can be tracked by the application or service.

By subscribing to any of these messages the application can give feedback to a user if it is required:

• EmailCreated: Sent when an email was successfully created.
• EmailRetryCountIncreased: When an email could not be sent, a series of retries is started which increments the attempts counter.
• EmailRetryCountReset: This message is sent when the counter is reset. It only happens when an email has exhausted all the instances to be sent and remains in the "failed to send" state, and the user/administrator starts the sending process again.
• EmailSendFailed: Sent when an email could not be sent.
• EmailSent: Sent when an email could be sent.
• EmailSentSuccessfully: Sent when an email was successfully sent.
• RetrySendEmail: Sent when the retry process is started.
• SendEmail: Sent when the send email process is started.

Every one of those events are published with a TimeStamp (DateTime) from when it was published.

Resend and Cancel emails

The API provides two methods to resend and cancel emails. It takes as parameter a list of GUID of the emails that we require to be resend or cancel.

• ResendEmails: accept a list of guid of the emails to resend.
• CancelEmails: accept a list of guid of the emails to cancel.

public class MyClass
{
    private readonly IEmailManager emailManager;

    public MyClass(
        IEmailManager emailManager)
    {
        this.emailManager = emailManager;
    }

    public async Task MyMethodA(IEnumerable<Guid> emailList) 
    {
        // This Method resend a list of Emails.
        await this.emailManager.ResendEmails(emailList);
    }

    public async Task MyMethodB(IEnumerable<Guid> emailList){
        // This Method cancel a list of Emails.
        await this.emailManager.CancelEmails(emailList);
    }
}