Sending Emails

Be it informing users about the failure of a workflow, or sending the generated outputs to the end users - there are many cases when we want to be able to send an email. To be able to send an email programmatically, we need to setup a SMTP server or use some SaaS tools, manage either the server or the tool, integrate it with the existing setup, etc - it can become very tedious.

But fear not, Peak SDK is here for you to handle all this. All you need to do is use an existing template or create a new one, and then just call the send_email function to send the email.

Let’s see how we can use the Peak SDK to send emails.

Templates

The email functionality uses Email templates to ensure that the email being sent out to customers are in a standardised format. Therefore, before sending an email a template has to be created.

Some standard templates are already available for all the tenants and can be used directly. We can get a list of the available templates by running the following command

peak alerts emails list-templates

This returns a JSON with details about all the available templates

{
    "pageCount": 1,
    "pageNumber": 1,
    "pageSize": 25,
    "templateCount": 4,
    "templates": [
        {
            "createdAt": "2024-05-17T11:25:04.249Z",
            "createdBy": "platform@peak.ai",
            "id": 34,
            "name": "workflow-watcher",
            "scope": "global"
        },
        {
            "createdAt": "2024-05-17T11:30:52.944Z",
            "createdBy": "platform@peak.ai",
            "id": 35,
            "name": "peak-base-template-v1",
            "scope": "global"
        },
        {
            "createdAt": "2024-06-06T06:11:32.503Z",
            "createdBy": "platform@peak.ai",
            "id": 67,
            "name": "resource_event_watcher",
            "scope": "global"
        },
        {
            "createdAt": "2024-09-25T06:44:23.617Z",
            "createdBy": "platform@peak.ai",
            "id": 134,
            "name": "feed_email_watchers_template",
            "scope": "global"
        }
    ]
}

If we want to check complete HTML content for the template, we can use the describe-template function passing the name of the template as an argument.
```
peak alerts emails describe-template feed_email_watchers_template
```
We need to raise a support ticket with the required HTML to add a new custom template.

Template Structure

A template consists of the HTML body that is sent over in the email. The awesome part is that it can be parameterised so that we can pass custom data in the template.

For example, let’s consider the following HTML template

<html>
    <head>
        <title>Peak Email</title>
    </head>
    <body>
        <h1>Hello {{name}}!</h1>
        <p>Thank you for your interest in {{company}}.</p>
        <p>Best regards,</p>
        <p>Your friends at Peak</p>
    </body>
</html>

It has two parameterised values - name and company. These values can be passed while sending the email thus allowing us to customise the template as required.

Attachments

The send_email function allows us to send a maximum of 3 attachments per email.
There are some limitations on the files though
- Each file can be a maximum of 10MB in size.
- Only the following file types are supported - .pdf, .docx, .doc, .csv, .txt, .xlsx, .xls, and .zip.
- For a .zip file, the total size after decompression must be a maximum of 25MB.
- The file must not contain any virus. We scan the files for viruses before sending the email and if any file is infected, the email is not sent.
We will see how attachments can be sent in the next section.

Sending Emails

In this section, let’s consider an email template called global_feedback. Here’s the HTML for the template

<h1>Hello {{userName}},</h1>
<p>
    We are always looking to improve our service. Please let us know your
    thoughts about <strong>{{productName}}</strong>.
</p>
<p>
    Regards,<br />
    Customer Service Team
</p>

Sending Emails 101

Sending email is as easy as calling the send_email function either from the SDK or the CLI with the required parameters.

Let’s use the CLI. Here’s the a file called payload.yml with the required values

body:
    recipients:
        - someone@peak.ai
    subject: Feedback Needed
    templateName: global_feedback
    templateParameters:
        userName: Saurabh
        productName: PeakAI Workflows

Now, we can send the email by just running the following command
```
peak alerts emails send payload.yml
```
This will return the following response, where id represents the email ID which can then be used to check the delivery status of the sent email
```
{
    "id": 2796
}
```

Checking Email Status

You can use the describe function in the SDK and CLI to check the status of a sent email. This will report whether the email was delivered or not. It will also return the error which caused the email to not be delivered (for example - wrong email).

Here’s how we can call the function

peak alerts emails describe 2796

The response looks like the following

{
    "createdAt": "2024-12-09T08:13:58.987Z",
    "createdBy": "platform@peak.ai",
    "deliveredAt": "2024-12-09T08:14:00.670Z",
    "id": 2796,
    "recipients": {
        "cc": [],
        "to": ["someone@peak.ai"],
        "bcc": []
    },
    "status": "Delivered",
    "statusDetails": [
        {
            "email": "someone@peak.ai",
            "status": "Delivered",
            "description": "The email was successfully delivered."
        }
    ],
    "subject": "Feedback Needed",
    "templateName": "global_feedback"
}

As we can see, the statusDetails contains the detailed information about the delivery of the mail. In our case, it has been successfully delivered 🥳

Adding Attachments

Now, the feedback email though was good, we also want to attach a PDF file in it with the details about the PeakAI Workflows. To do so, we just need to pass the path of the required files in a key called attachments.

body:
    recipients:
        - someoner@peak.ai
    subject: Feedback Needed
    templateName: global_feedback
    templateParameters:
        userName: Saurabh
        productName: PeakAI Workflows
attachments:
    - workflows.pdf

And then, we can run the send_email function to send the email
```
peak alerts emails send payload.yml
```

Now, what if I have a folder containing some files as well that I want to send. We can also pass the path to a folder to the attachments. Peak SDK will automatically create a .zip file from the folder and send it in the email.

body:
    recipients:
        - someoner@peak.ai
    subject: Feedback Needed
    templateName: global_feedback
    templateParameters:
        userName: Saurabh
        productName: PeakAI Workflows
attachments:
    - workflows.pdf
    - utilities/

Epilogue

As we can see, Peak SDK makes sending email extremely easy. But as someone great once said, “With great power, comes great responsibility”. Please ensure that the functionality is used with utmost care. Sending spam messages might affect the reputation of Peak’s email identity as a whole, so refrain from doing that.
There’s a limit of the number of emails that can be sent in a day for a tenant. In most cases, the default limit of 100 should be enough, but if you need to send more emails, please contact the support team.
There’s also a limit on the domains that you can send emails to. By default, you can only send emails to email ids on domain peak.ai. If you want to send emails to some other domains as well, please raise a support ticket to get the domains whitelisted.
By default, the emails are sent from no-reply@peak.ai email address. We also support using a custom email id for a tenant. If you wish to use a different email for a tenant, please reach out to the support team.