Learn Blog Pricing About Sign in

Learn

Blog

Pricing

About

Sign in

EMAILREPORT function

EMAILREPORT(IncludedFields, Recipients, ReplyTo?, SubjectLine?, Format?, SeparateScreens?, IncludeScreenLabels?, IncludeBlankValues?, IncludeHiddenFields?, ResetFields?, FileName?, Body?, Prologue?, Epilogue?, CarbonCopy?, BlindCarbonCopy?, Sender?) EMAILREPORT(IncludedFields; Recipients; ReplyTo?; SubjectLine?; Format?; SeparateScreens?; IncludeScreenLabels?; IncludeBlankValues?; IncludeHiddenFields?; ResetFields?; FileName?; Body?; Prologue?; Epilogue?; CarbonCopy?; BlindCarbonCopy?; Sender?)

IncludedFields

{ ? }

The fields that are included in the report. This parameter is equivalent to the IncludedFields property of email report buttons — refer to the property for in-depth documentation and more examples.

{ Field1, Field2 }{ Field1; Field2 } includes Field1 and Field2 in the report. Field1:Field100Field1:Field100 includes Field1, Field100 and all fields that appear between them. { App }{ App } includes all the fields of the app. { Field1, MainScreen, FormGroup1 }{ Field1; MainScreen; FormGroup1 } includes Field1, all the fields of the screen MainScreen and all the fields of the form group FormGroup1.

FILTER(Field1:Field5, (Field1:Field5).Visible)FILTER(Field1:Field5; (Field1:Field5),Visible)} potentially includes Field1, Field5 and all fields that appear between them, but ultimately only includes those that are visible. Similarly, FILTER(Field1:Field5, Field1:Field5 > 4)FILTER(Field1:Field5; Field1:Field5 > 4)} only includes those fields whose values are greater than 4.

Fields included in this array are not part of the report if they are hidden and the IncludeHiddenFields parameter is FALSE. Fields whose values are blank are not part of the report if the IncludeBlankValues parameter is FALSE.

Recipients

Text or { Text }

The primary recipients of the email. This parameter is equivalent to the Recipients property of email report buttons — refer to the property for in-depth documentation and more examples.

This parameter must consist of one or several email addresses, in the form of a text string or in the form of an array of text strings. A text string can contain multiple email addresses separated by spaces, commas or semicolons. Use & to join text strings together.

"user1@example.com;user2@example.com""user1@example.com;user2@example.com" sends the report to user1@example.com and to user2@example.com.

{ "user1@example.com", "user2@example.com" }{ "user1@example.com"; "user2@example.com" } has the same effect.

{ "office@example.com", EmailAddress}{ "office@example.com"; EmailAddress} sends the report to office@example.com and to the email address specified in the text field EmailAddress.

ReplyTo

Text (optional)

The Reply-To field of the email. This parameter is equivalent to the ReplyTo property of email report buttons — refer to the property for in-depth documentation and examples.

SubjectLine

Text (optional)

The subject line of the email. This parameter is equivalent to the SubjectLine property of email report buttons.

Format

EmailReportFormat (optional)

The format that is used for the report. This parameter is equivalent to the Format property of email report buttons. Refer to the property for in-depth documentation and examples.

The allowed values are EmailReportFormat.TextEmailReportFormat,Text (the field values are included in the email body itself), EmailReportFormat.PdfEmailReportFormat,Pdf (the field values are included in an attached PDF document) and EmailReportFormat.DsvEmailReportFormat,Dsv (the field values are included in an attached file containing delimiter-separated values, like CSV and TSV files).

Use EMAILREPORT.DSV, EMAILREPORT.CSV or EMAILREPORT.TSV instead to customize many aspects of the file containing delimiter-separated values.

If omitted, EmailReportFormat.TextEmailReportFormat,Text is assumed.

SeparateScreens

Logical (optional)

Whether field values belonging to different screens are separated from one another in the report. This parameter is equivalent to the SeparateScreens property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, TRUE is assumed.

IncludeScreenLabels

Logical (optional)

Whether screen labels are included in the report. This parameter is equivalent to the IncludeScreenLabels property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, TRUE is assumed.

IncludeBlankValues

Logical (optional)

Whether fields whose values are blank are included in the report. This parameter is equivalent to the IncludeBlankValues property of email report buttons. If omitted, FALSE is assumed.

IncludeHiddenFields

Logical (optional)

Whether hidden fields are included in the report. This parameter is equivalent to the IncludeHiddenFields property of email report buttons. If omitted, FALSE is assumed.

ResetFields

Logical (optional)

Whether the fields sent in the report are reset after the report has been successfully sent. This parameter is equivalent to the ResetFields property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, FALSE is assumed.

When a field is reset, its value is set to the initial value. The property documentation includes an example demonstrating how to set the value to a blank value instead.

FileName

Text (optional)

The name of the file that emailed attachments are saved to when the email is sent. This parameter is equivalent to the FileName property of email report buttons. If omitted, a default file name is used.

If no period appears in the returned file name, a file extension (such as ".pdf") is added, depending on the Format parameter.

Body

Text (optional)

The body of the sent email. This parameter is equivalent to the Body property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, a default body is used.

Prologue

Text (optional)

The text that appears before field values. This parameter is equivalent to the Prologue property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, no prologue is used.

Epilogue

Text (optional)

The text that appears after field values. This parameter is equivalent to the Epilogue property of email report buttons. Refer to the property for in-depth documentation and examples. If omitted, no epilogue is used.

CarbonCopy

Text or { Text } (optional)

The carbon copy ("CC") recipients of the email. This parameter is equivalent to the CarbonCopy property of email report buttons. Refer to the property for in-depth documentation and examples. The Recipients parameter is similar and its examples apply to this parameter as well. If omitted, no carbon copy recipients are used.

BlindCarbonCopy

Text or { Text } (optional)

The blind carbon copy ("BCC") recipients of the email. This parameter is equivalent to the BlindCarbonCopy property of email report buttons. Refer to the property for in-depth documentation and examples. The Recipients parameter is similar and its examples apply to this parameter as well. If omitted, no blind carbon copy recipients are used.

Sender

Text (optional)

The sender of the email. This parameter is equivalent to the Sender property of email report buttons. Refer to the property for in-depth documentation and examples.

If omitted, a default sender is used which uses the calcapp.net domain, which increases the odds that an email sent through an app is successfully delivered and is not classified as spam. Consider using the ReplyTo parameter instead to direct replies to your reports.

Returns

Promise

A promise, which succeeds with no value if the report is sent successfully and fails otherwise. Pass this promise as the first parameter to AWAIT (and related functions) to take action after the promise has succeeded or failed.

If the promise fails, the provided Error value provides an error message through Error.Message and an error origin through Error.Origin (often in the form of a function name or an operator symbol).

An error category is provided through the Error.Category value. These are the categories:

  • EmailReportErrorCategory.InvalidEmailAddressEmailReportErrorCategory,InvalidEmailAddress
    An email address — a recipient, a carbon copy ("CC") recipient, a blind carbon copy ("BCC") recipient, the sender address or the Reply-To address — was found to be invalid.
  • EmailReportErrorCategory.QuotaExceededEmailReportErrorCategory,QuotaExceeded
    Your plan does not allow additional reports to be sent.
  • EmailReportErrorCategory.TooManyRecipientsEmailReportErrorCategory,TooManyRecipients
    There are too many recipients.
  • EmailReportErrorCategory.ServiceErrorEmailReportErrorCategory,ServiceError
    Our email service provider could not deliver your report — please let us know.

Sends a report through email. EMAILREPORT({ App }, "test@example.com")EMAILREPORT({ App }; "test@example.com") sends a report containing all fields of the app to test@example.com.

This function can only be used from an action formula. It is typically invoked from a formula associated with the OnPress property of a formula button.

A report contains field labels and their values in a table, with the labels appearing in the first column and the values in the second column. A report can also omit fields and their values entirely and only include arbitrary text (see below).

The fields to include are given as the first parameter to this function, as an array. { Field1, Field2 }{ Field1; Field2 } includes the Field1 and Field2 fields, { Field1, MainScreen }{ Field1; MainScreen } includes Field1 and all the fields of the screen MainScreen, { App }{ App } includes all the fields of the app and {}{} includes no fields.

The recipients are given as the second parameter, and must be either a text string containing one or several email addresses, separated by spaces, commas or semicolons, or an array of such text strings.

The fields to include and the recipients are the only required parameters. However, there are a very large number of optional parameters, allowing you to customize the report. These are detailed above (press Details).

This function is mostly equivalent to email report buttons. No messages are displayed when a report is successfully sent or if an error occurs, though. Use functions like AWAIT, BANNER and ALERT to display equivalent messages. See below for an example.

Use OPENREPORT instead if a report should be opened directly on your user's device, instead of being emailed. Use EMAILREPORT.DSV, EMAILREPORT.CSV or EMAILREPORT.TSV if the included fields should be sent as an attached file with comma-separated or tab-separated values (CSV or TSV) and you need greater control over this file than afforded by this function.

Optional parameters

Format is one of the most commonly-used optional parameters. Set it to EmailReportFormat.TextEmailReportFormat,Text if the values should appear in the email body itself, EmailReportFormat.PdfEmailReportFormat,Pdf if the values should be included in an attached PDF document or EmailReportFormat.DsvEmailReportFormat,Dsv if the values should be included in an attached CSV or TSV file, suitable for use with spreadsheets or databases.

Arbitrary text can be included before and after the field values using the Prologue and Epilogue parameters, respectively. If a file is attached, its file name can be set using the FileName parameter. The email body is automatically generated if a file is attached with helpful suggestions on how to use the file — use the Body parameter to provide your own email body.

The IncludeBlankValues and IncludeHiddenFields parameters may be used to determine what fields referenced by the first parameter actually make it into the report. The ReplyTo, Sender, CarbonCopy and BlindCarbonCopy parameters may be used to customize other aspects of the email. The ResetFields parameter may be used to reset fields after they have been sent. Again, refer to the details above for more information.

Customizing the look

The SeparateScreens parameter determines if values belonging to different screens are separated from one another in a report. The IncludeScreenLabels parameter determines if screen labels are included in reports. IncludeScreenLabels has no effect unless SeparateScreens is TRUE.

PDF reports created by this function currently cannot be customized with a custom layout, formatted text or images. Learn how to generate custom-designed PDF documents by reading this tip.

These are examples of what reports look like, depending on what values are given to the SeparateScreens and IncludeScreenLabels parameters:

Without separated screens

Field1 1
Field2 2
Field3 3

With separated screens and screen labels

Screen1
Field1 1
 
Screen2
Field2 2
Field3 3

With separated screens and no screen labels

Field1 1
 
Field2 2
Field3 3

Named parameters

Parameters are typically provided in the order they are expected. By preceding a parameter with its name and a colon, it can be provided out-of-order and optional parameters normally expected prior to it can be omitted entirely.

As an example of named parameters, consider these two formulas. They both set the ResetFields parameter to TRUE and provide a custom subject line:

EMAILREPORT({ MainScreen, DetailsScreen }, "test@example.com", SubjectLine: "A report", ResetFields: TRUE)EMAILREPORT({ MainScreen; DetailsScreen }; "test@example.com"; SubjectLine: "A report"; ResetFields: TRUE)
EMAILREPORT({ MainScreen, DetailsScreen }, "test@example.com", BLANK(), "A report", EmailReportFormat.Text, TRUE, TRUE, FALSE, FALSE, TRUE)EMAILREPORT({ MainScreen; DetailsScreen }; "test@example.com"; BLANK(); "A report"; EmailReportFormat,Text; TRUE; TRUE; FALSE; FALSE; TRUE)

The first formula provides the two required parameters (the fields to include in the report and the recipients) and then provides two optional parameters by naming them explicitly.

The second formula explicitly provides values for all parameters, up to and including the ResetFields parameter.

We recommend the first version, with named parameters, as such formulas tend to be shorter and easier to understand.

Combining EMAILREPORT with IF

On its own, a formula button that uses EMAILREPORT can do everything that email report buttons can do, but nothing more. By combining it with other functions, you unlock many more possibilities.

This formula uses IF to only send a report if the value of the number field Result is a positive number:

IF(Result >= 0, EMAILREPORT({ App }, "test@example.com"))IF(Result >= 0; EMAILREPORT({ App }; "test@example.com"))

This formula sends a report only if Result is valid and displays an error message otherwise using the ALERT function:

IF(Result.Valid, EMAILREPORT({ App }, "test@example.com"), ALERT("Could not send report", "Error"))IF(Result,Valid; EMAILREPORT({ App }; "test@example.com"); ALERT("Could not send report"; "Error"))

Running other functions directly after EMAILREPORT

An action formula can run multiple functions by separating the invocations with ;;;.

This formula sends two reports, containing different fields:

EMAILREPORT({}, App.UserEmailAddress, Body: "This is your result: " & FORMATNUMBER(Result) & "."); EMAILREPORT({ Field1:Field20, Result }, "office@example.com")EMAILREPORT({}; App,UserEmailAddress; Body: "This is your result: " & FORMATNUMBER(Result) & ".");; EMAILREPORT({ Field1:Field20; Result }; "office@example.com")

The first report doesn't contain any fields in the traditional sense. Instead, it sends an email with a custom body, containing a result. It is sent to the user's email address, which is only available if the app is a private app.

The second report contains Field1, Field20 and all fields that appear between them, as well as Result, and sends it to office@example.com.

With ;;;, EMAILREPORT can be combined with RELAY to also invoke a third-party service. A report can be sent to a customer, for instance, while simultaneously posting a message to the internal Slack channel or adding a row to a Google Sheets spreadsheet.

Waiting for EMAILREPORT to finish

When another function invocation follows EMAILREPORT in a formula, separated by ;;;, it is run as soon as EMAILREPORT has sent its report.

If you instead need to wait for EMAILREPORT to finish before continuing, you need to use the AWAIT function (or a related function). AWAIT accepts an action (returning a promise) as its first parameter. It runs the formula fragment given as the second parameter if the action succeeds and runs the formula fragment given as the third parameter if the action fails.

This formula sends a report and shows a banner with BANNER if the report is sent successfully, and displays a message (which must be dismissed) with ALERT if the report could not be sent:

AWAIT(EMAILREPORT({ App }, "test@example.com"), BANNER("Your data has been sent"), ALERT("Could not send report: Error: " & Error.Message))AWAIT(EMAILREPORT({ App }; "test@example.com"); BANNER("Your data has been sent"); ALERT("Could not send report: Error: " & Error,Message))

Using PROMPT to collect parameters for EMAILREPORT

AWAIT can also be used to wait for other functions to complete their work. PROMPT is one such function, which asks the user to provide information with a window that pops up.

This function asks the user which email address to send the report to before invoking EMAILREPORT:

AWAIT(PROMPT(Body: "What email address should
the report be sent to?", Title: "Question", OkLabel: "Send report"), EMAILREPORT({ App }, Result))AWAIT(PROMPT(Body: "What email address should
the report be sent to?"; Title: "Question"; OkLabel: "Send report"); EMAILREPORT({ App }; Result))

AWAIT makes the result returned from PROMPT available as the Result value, which is the text string entered by the user.

Examples

EMAILREPORT({ Field1, Field2 }, "test@example.com")EMAILREPORT({ Field1; Field2 }; "test@example.com")

Sends a report containing Field1 and Field2 to test@example.com. { Field1, Field2 }{ Field1; Field2 } is an example of an array, that is, a list of values.

EMAILREPORT(Field1:Field100, { "user1@example.com", "user2@example.com" })EMAILREPORT(Field1:Field100; { "user1@example.com"; "user2@example.com" })

Sends a report containing Field1, Field100 and all fields that appear between them to user1@example.com and user2@example.com. The recipients can also be specified as an array.

EMAILREPORT({ App }, "user1@example.com, user2@example.com")EMAILREPORT({ App }; "user1@example.com, user2@example.com")

Sends a report containing all fields of the app to user1@example.com and user2@example.com. The first array can contain references to anything, including AppApp, which represents all fields of the app. The recipients can be specified as a single text string, where individual addresses are separated by spaces, commas or semicolons.

EMAILREPORT({ Field1, MainScreen, FormGroup1 }, "test@example.com")EMAILREPORT({ Field1; MainScreen; FormGroup1 }; "test@example.com")

Sends a report containing Field1, all fields of the screen MainScreen and all the fields of the form group FormGroup1 to test@example.com.

EMAILREPORT({ App }, "test@example.com", SubjectLine: "A report", Body: "These are the readings
taken on " & FORMATDATE(TODAY()) & ":")EMAILREPORT({ App }; "test@example.com"; SubjectLine: "A report"; Body: "These are the readings
taken on " & FORMATDATE(TODAY()) & ":")

Sends a report containing all fields of the app to test@example.com. The subject line is set to "A report" and the email body is set to a custom text string incorporating today's date. Named parameters are used to provide just two optional parameters (the subject line and email body), while leaving the rest of the optional parameters at their default values.

EMAILREPORT({ App }, "test@example.com", Format: EmailReportFormat.Pdf)EMAILREPORT({ App }; "test@example.com"; Format: EmailReportFormat,Pdf)

Sends a report containing all fields of the app to test@example.com. The field values are provided as an attached PDF document.

EMAILREPORT.CSV({ App }, "test@example.com", DecimalSeparator: DecimalSeparator.DecimalComma)EMAILREPORT.CSV({ App }; "test@example.com"; DecimalSeparator: DecimalSeparator,DecimalComma)

Sends a report containing all fields of the app to test@example.com. The field values are provided as an attached CSV file, containing comma-separated values. Numbers in the file use a decimal comma, as the DecimalSeparator parameter is provided. EMAILREPORT.CSV is used instead of this function in order to customize the resulting CSV file.

AWAIT(EMAILREPORT({ App }, "test@example.com"), BANNER("Done!"))AWAIT(EMAILREPORT({ App }; "test@example.com"); BANNER("Done!"))

Sends a report containing all fields of the app to test@example.com and displays a banner with the message "Done!" once the report has been sent.

AWAIT(PROMPT("Enter the recipients:"), Recipients -> EMAILREPORT.CSV({ App }, Recipients))AWAIT(PROMPT("Enter the recipients:"); Recipients -> EMAILREPORT.CSV({ App }; Recipients))

Asks the user to provide the recipients of the report. Once the user has done so, a CSV report is sent containing all fields of the app to test@example.com. -> is used to rename the value returned from the AWAIT function to Recipients, which in turn is the value provided from the PROMPT function to AWAIT, containing the recipients entered by the user.