Mail Extension

Commands

dbr.mail - Sends an email
dbr.mail.sender - Specifies the sender's address within the report, overriding global settings
dbr.mail.recipient - Adds additional recipients (CC, BCC, or TO) to the email
dbr.mail.attach - Attaches a file to the email
dbr.mail.notify_successful_mail - Suppresses the "Mail sent" confirmation message
dbr.mail.smtp.user - Specifies alternative SMTP credentials (username and password)
dbr.mail.smtp.server - Specifies an alternative SMTP server
dbr.mail.smtp.authentication.type - Selects the SMTP authentication method (defaults to LOGIN)
dbr.mail.encoding - Sets the email encoding (options: "8bit", "7bit", "binary", "base64", or "quoted-printable")
dbr.mail.debug - Enables verbose debug logging for troubleshooting (1=on, 0=off)
dbr.mail.log.proc - Defines a stored procedure to log email delivery actions
dbr.mail.nobr.html - Prevents automatic conversion of linefeeds to HTML line breaks (<br>) in HTML emails
dbr.mail.header_file - Overrides the default email header file with a custom one located in the user/ directory
dbr.mail.postprocess - Post-processes the email content using a command-line tool (defaults to Pandoc)
dbr.mail.ignore_invalid_email - Ignores invalid email addresses specified in dbr.mail.recipient
dbr.mail.smtp.ssl - Configures SSL context options for the SMTP connection

Syntax

select 'dbr.mail', [optional HTML flag: 1 for HTML mail]
select 'dbr.mail.sender', sender_email, [, sender_name, [replyto_email, [replyto_name ]]]
select 'dbr.mail.recipient', recipient_email, [, recipient_name, 'cc' | 'bcc']
select 'dbr.mail.attach',  'filename.ext', URL [, ignore_ssl]
select 'dbr.mail.notify_successful_mail',  0
select 'dbr.mail.smtp.user',  'user', 'password'
select 'dbr.mail.smtp.server',  'host', 'port', {'tls'|'ssl'}
select 'dbr.mail.smtp.authentication.type',  'LOGIN' | 'PLAIN' | 'NTLM' | 'CRAM-MD5'
select 'dbr.mail.encoding', 'base64'
select 'dbr.mail.debug',  1
select 'dbr.mail.log.proc', 'sp_mail_log';
select 'dbr.mail.nobr.html', 1;
select 'dbr.mail.header_file', filename;
select 'dbr.mail.postprocess', filetype;
select 'dbr.mail.ignore_invalid_email', 1;
select 'dbr.mail.smtp.ssl', 'option', 'value';

Syntax Tips

In dbr.mail.sender, if replyto_email is omitted, myDBR defaults to the sender_email. Similarly, if replyto_name is omitted, sender_name is used.

Configuration

Configuration is managed via Environment settings. Note that the legacy mail configuration in user/extension_init.php is deprecated.

Usage

Plain Text Email

select 'dbr.mail';

select 'John.Doe@example.com', 'John', 'This is a subject', 'Body of the mail';

HTML Email with Delivery Logging

/* Send HTML email */
select 'dbr.mail', 1; 
/* in_extra1 and in_extra2 are optional */
select 'dbr.mail.log.proc', 'sp_mail_log', 'in_extra1=extra1', 'in_extra2=extra2';

select email, name, subject, html_body, extra1, extra2
from mydb.mail_recipients;

The sp_mail_log procedure requires four fixed parameters. You can also include additional parameters to match your query's column references:

create procedure sp_mail_log ( 
in_msg varchar(255),
in_error text,
in_to_address varchar(255),
in_errornous_attachment_names varchar(255),
in_extra1 int,
in_extra2 int
)
begin

/* Handle delivery status and optional parameters */
insert into mail_log(sent_at, message, error, to_address, errornous_attachment_names)
values ( now(), in_msg, in_error, in_to_address , in_errornous_attachment_names );

end

Sending to Multiple Recipients

select 'dbr.mail'; 
select 'dbr.mail.recipient', 'john@company.com', 'John Doe', 'CC';
select 'dbr.mail.recipient', 'Jane@company.com', 'Jane Doe', 'BCC';
select 'dbr.mail.recipient', 'father@company.com', 'Father Doe', 'TO';

/* The recipient columns can be empty since they are defined above */
select '', '', 'Notification', 
    concat('Your report can be found in myDBR', char(10), 
        '-- ', char(10), 
        'Mary');

Custom Sender and Reply-To Addresses

select 'dbr.mail'; 
select 'dbr.mail.sender', 'mary@company.com', 'Mary Cotton';

select 'john@company.com', 'John Doe', 'Notification', 
    concat('Your report can be found in myDBR', char(10), 
        '-- ', char(10), 
        'Mary');

Mailing Report Output

To send full report elements via email, use the dbr.record command to capture the output. This command allows you to define a specific section of the report to be included in the message body. The dbr.record command is available in the Premium version.

When recording:

Report objects are included while preserving formatting.
Table elements (basic, cross-tabulation, pageview, etc.) are included.
Images (ChartDirector, Graphviz) are included as attachments.

Note: Elements requiring client-side JavaScript (such as Google Maps or interactive JavaScript components) are not supported in emails.

/* Start recording: everything between 'begin' and 'end' will be included in the email body */
select 'dbr.record', 'begin'; 

/* Include full reports */
call sp_DBR_MyReport();

/* Include additional report elements */
select data1, data2
from mydb.mydata;

select 'dbr.record', 'end'; 

/* Use HTML email to preserve formatting */
select 'dbr.mail', 1; 

/* Send the email to all recipients */
select email, name, 'This is the report'
from mydb.mail_recipients;

Attachments

You can add attachments to emails by providing a file URL or path. Attachments can be any server-accessible file, including PDF or Excel exports generated by myDBR.

select 'dbr.mail'; 
select 'dbr.mail.sender', 'mary@company.com', 'Mary Cotton';
select 'dbr.mail.attach', 'report.pdf', 'http://myserver.com/mydbr/report.php?r=184&h=ee5f3bfee6e1384ccf52e151bcc2081aa367adeb&export=pdf';

select 'john@company.com', 'John Doe', 'Notification', 
    concat('Here is the latest report', char(10), 
        '-- ', char(10), 
        'Mary');

Post-processing Email Content

Email content can be post-processed using external command-line tools. This is useful for converting HTML to other text-based formats. The default tool is Pandoc. To use it, Pandoc must be installed on the server. The post-processing command is configured via $defaults['mail']['postprocess_cmd'].

select 'dbr.record', 'begin';
select 'dbr.summary.options', 'skip_single_line_summary';

select film_id, title, release_year
from film
limit 2;
select 'dbr.record', 'end';

select 'dbr.mail'; 
select 'dbr.mail.postprocess', 'rst';

select 'john@company.com', 'John Doe', 'RST document';

The resulting email content will look like this:

.. container::

======= ======================== ============
film_id title                    release_year
======= ======================== ============
1       ACADEMY DINOSAUR'abc'abc 2 007
2       AMERICAN BACON'abc       2 008
======= ======================== ============

When sending HTML emails, post-processing is applied to the plain-text version of the message.

Bypassing Certificate Verification Errors

If email delivery fails due to certificate verification issues, we recommend verifying your server's SSL configuration. If you are using an internal mail server and wish to bypass these checks, you can configure the SSL context options accordingly.

select 'dbr.mail.smtp.ssl', 'verify_peer', 'false';
select 'dbr.mail.smtp.ssl', 'verify_peer_name', 'false';
select 'dbr.mail.smtp.ssl', 'allow_self_signed', 'true';

select 'dbr.mail';

select 'John.Doe@example.com', 'John', 'This is a subject', 'Body of the mail';

Commands​

Syntax​

Syntax Tips​

Configuration​

Usage​

Plain Text Email​

HTML Email with Delivery Logging​

Sending to Multiple Recipients​

Custom Sender and Reply-To Addresses​

Mailing Report Output​

Attachments​

Post-processing Email Content​

Bypassing Certificate Verification Errors​