Feature: Send formula-driven emails

Fully determine the bodies of emails you send using formulas. You can also use formulas to set text that appears before or after field values in reports.

Over the years, we have steadily added features that help you more fully customize the emails sent from your apps. When reports launched in 2016, there were very few report-related options in the inspector. We quickly added the ability to choose whether screen names and blank values should be part of reports, and whether sent fields should be reset afterwards. Towards the end of the year, we added PDF reports.

In early 2017, you got the ability to set the sender of emails, and in 2018 we made it possible to change the subject line, potentially using a formula. Finally, a grab bag of improvements landed in 2019, including the ability to set the Reply-To field and the ability to set the file names of attached files, possibly using a formula.

Setting the email body

It’s 2021, and the time has come to let you set the body of emails sent through your apps using formulas, making all email aspects fully customizable. With this feature, you can finally communicate with your users using plain English (or any other language), instead of sending dry field values in a table.

This feature is enabled by the new Body property of email reports buttons. Consider this formula:

"Dear " & Name & "," & NEWLINE() & NEWLINE() & "The weight is
" & FORMATNUMBER(Weight) & " lbs."
"Dear " & Name & "," & NEWLINE() & NEWLINE() & "The weight is
" & FORMATNUMBER(Weight) & " lbs."

The formula above sets the email body to something like the following:

Dear Sally,

The weight is 23.30 lbs.

The new NEWLINE function returns a line break character (and is fully equivalent to CHAR(10)CHAR(10)). It makes it easy to construct email bodies consisting of multiple lines, and multiple paragraphs.

If this property is not set, a default body is used. If the format of the email report button calls for a file to be attached (containing, say, a PDF document), the default body includes instructions in English on how to open the attached file. By setting a body explicitly through this property, you can fully determine the email body yourself.

There is one thing this new feature won’t enable you to do: send emails with images and formatted text. You also can’t send PDF documents containing images and formatted text. For the latter use case, there are lots of great third-party services you can integrate with your apps to realize this functionality. We wrote a blog post walking you through two such services last year.

Refer to our complete documentation to learn more and to access formula examples demonstrating how the new feature can be used.

Setting the text that appears before and after field values

The email body property sets the body of emails you send. If the format of the email is text, field values are included directly in the body, appearing directly after the text set through the Body property.

There is a new property, Prologue, which allows you to set the text that appears before the field values. It is pretty much equivalent to the Body property if the format is set to text (the prologue text appears after the body text). To set the text that appears after field values, use the Epilogue property.

If the format of the email calls for a file to be attached, containing CSV or PDF data, the Body property determines the body of the email itself, while the Prologue and Epilogue properties apply to the attached file. You can even ask Calcapp not to include any field values at all, meaning that you can fully determine the text contents of an attached PDF file using a formula.

The Prologue and Epilogue properties apply not just to email report buttons, but also to open report buttons (which enable files to be downloaded directly to a user’s device).

Refer to the our newly-revamped property documentation to learn more and to access examples demonstrating the new features. Here’s documentation for the Prologue property of email report buttons and open report buttons. Finally, here’s documentation for the Epilogue property of email report buttons and open report buttons.

Calcapp branding and reports

Prior to this release, generated reports differed somewhat depending on if your app was on a White Label plan or not. If your app was on a White Label plan, no mention was made of Calcapp, in any context.

If your app was not on a White Label plan and you sent reports by email, attached PDF files included a blurb before the field values stating the name of your app, the date and the fact that Calcapp had been used to generate the report. Attached CSV files, on the other hand, did not mention Calcapp. Finally, email bodies for apps not on a White Label plan mentioned Calcapp in the footer.

These rules also applied to reports downloaded directly to a user’s device. Downloaded plain text files, or HTML documents, did not mention Calcapp, regardless of what plan your app was on.

If you don’t make use of any of the new properties Body, Prologue and Epilogue and your app is not on a White Label plan, the only change you will see is that generated PDF files look a little different. Specifically, nothing appears before the field values. Rather, a short sentence (“Generated by Calcapp.”) now appears after the field values.

If you want your report to look mostly identical to the way it looked before, complete with the current date and time, associate a formula like the following with the Prologue property of the email report button or the open report button:

"This report has been sent from the ""[your app name]"" app on
" & FORMATDATE(TODAY()) & " " & FORMATTIME(NOW()) & ", courtesy of Calcapp."
"This report has been sent from the ""[your app name]"" app on
" & FORMATDATE(TODAY()) & " " & FORMATTIME(NOW()) & ", courtesy of Calcapp."

The formula above uses the new FORMATDATE and FORMATTIME functions to include the current date and time in the report. Writing """" inside of a text string in a formula generates a single quotation mark.

If you do make use of any of the properties Body, Prologue and Epilogue and your app is not on a White Label plan, you will find that the “Generated by Calcapp.” blurb is added to the epilogue — the text that appears after the field values — automatically.

In other words, nothing material changes in terms of branding if you don’t use the new properties. If you do, however, discreet Calcapp branding is added to your reports.

« Feature: Use a formula to determine what fields to include in a report Feature: Use SUMIF, SUMIFS and others like them »