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.


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.


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




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




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.




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.


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:

    "name": "My First SMTP Server",
    "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.


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:

    "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.

Request POST /api/mails with body:

    "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.