Skip to content

Getting started

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.

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.