Skip to content

Getting started

Setup Environment

The first thing to do is set up a local Bizzkit development environment. A detailed guide for doing this can be found here.

Docker

Bizzkit Mail can handle files in a local environment with Azurite, which is a blob storage emulation service. With the provided docker-compose setup this is configured for you, however, Azurite does not have full feature parity with Azure Blob Storage. In the case of Bizzkit Mail, this currently only means you are not able to upload attachments from a public URI, instead, you must point to a URI of the Azurite blob container itself.

Configuring Bizzkit Mail

Bizzkit Mail supports different operating modes which is relevant in a development environment. The following is configured for the Jobrunner environmental variables.

Production

As the name implies, this mode will not perform interceptions and will instead contact servers directly.

Example

MailSending__OperationMode=Production

Test

This mode works like Production but has the benefit of whitelisting domains such that no accidental emails would get sent to end users.

Example

MailSending__OperationMode=Test

MailSending__WhitelistedDomains__0=bizzkit.com

MailSending__WhitelistedDomains__1=mywebshop-devteam.xyz

Simulation

This mode will not contact any real servers and instead will populate the attached Blob Storage with a .eml file, i.e. an email as a file.

Example

MailSending__OperationMode=Simulation

MailSending__EnableStoringSimulationMails=true

The email files can be found via Azure Storage Explorer, under the folder simulation.

Admin permissions

By default, the admin role starts with all permissions needed for managing Bizzkit Mail.

Before you can send an email

Some setup is required before it is possible to send an email. This can be done using the SDK, plain HTTP, or simply using the Admin/Swagger UI. This guide interacts with the Swagger UI. See the full API reference here.

Info

You can choose to follow along by simply using the admin site instead of Swagger, this also eliminates keeping track of identifiers, etc. The concepts reside under https://<MAIL_ADMIN_DOMAIN>/settings.

  1. Go to https://<MAIL_API_DOMAIN>/swagger/index.html to access the Swagger site.
  2. Authorize.

Configuring an SMTP Server

The first step is to set up the information required to contact your SMTP server.

Request POST /api/mail-providers/smtp-servers with body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "name": "My First SMTP Server",
    "host": "<SMTP_SERVER_HOSTNAME_HERE>",
    "port": 587,
    "username": "<SMTP_SERVER_USERNAME_HERE>",
    "password": "<SMTP_SERVER_PASSWORD_HERE>",
    "connectionTimeoutInMilliseconds": 10000,
    "dispatchQuantity": 10000,
    "dispatchIntervalInMinutes": 1,
    "batchIntervalInSeconds": 1,
    "batchQuantity": 10000,
    "isActive": true,
    "disableSsl": false
}

Replace host, port, username, and password with appropriate values.

Note down the identifier from the API response, it will be used in the next step.

Info

If you don't have an SMTP server available for testing, some free alternatives are available: Ethereal, Mailtrap

Configuring a Mail Policy

Next up, we will create a Mail Policy. These define how to prioritize emails, their retention periods, and more.

Request POST /api/mail-policies with body:

1
2
3
4
5
6
7
8
{
    "name": "My First Policy",
    "priority": 1,
    "retentionPeriodInDays": 30,
    "maxNumberOfAttempts": 10,
    "mailProviderId": 1, 
    "mailCleanupAction": "Archive"
}

Ensure mailProviderId is correct.

Note down the identifier from the API response, it will be used when sending a mail.

(Optional) Create a Shared Attachment

Request POST /api/shared-attachments with:

  1. Query parameters: key=my-first-shared-attachment, and leave fileName empty.
  2. Choose a file for the body

The attachment can be referenced when sending a mail, simply by the key specified.

Sending your first email

With the previous steps completed, it is now possible to enqueue a mail for dispatch. This can be done using the SDK, plain HTTP, or simply using the Swagger UI. This guide interacts with the Swagger UI. See the full API reference here.

Important

Make sure you have configured Bizzkit Mail to use the operating mode you need.

Request POST /api/mails with body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
    "subject": "My first mail!",
    "htmlContent": "<html>\n<body>\n<h1>Hello world!</h1>\n<p>Some text</p>\n</body>\n</html>",
    "fromAddress": {
        "address": "<SENDER_EMAIL>",
        "name": "<SENDER_NAME>"
    },
    "toAddress": {
        "address": "<RECIPIENT_EMAIL>",
        "name": "<RECIPIENT_NAME>"
    },
    "sharedAttachments": ["my-first-shared-attachment"], 
    "mailPolicyId": 1
}

Replace fromAddress and toAddress with appropriate values. Omit sharedAttachments from the request if you did not create a shared attachment. Ensure mailPolicyId is correct.

Keeping track of emails

Go to https://<MAIL_ADMIN_DOMAIN>/ to access the admin site, which will give an overview of all stored emails and their statuses.

  1. Click the mail you just sent to view its details
  2. Here you can view its information, content and error history if anything went wrong.