Plugins, Hooks, & External Modules
Developer methods for
Plugins, Hooks, & External Modules
Hook functions
REDCap Developer Tools:
Documentation for Plugins, Hooks, & External Modules
REDCap Version 14.9.1
REDCap::email
(REDCap >= 5.11.0)
REDCap::email
— Send an email to one or more receipients
Description
bool REDCap::email ( string $to, string $from, string $subject, string $message [, string $cc [, string $bcc [, string $fromName [, array $attachments ]]]] )
Provides a simple way to send emails to one or more recipients without having to format complicated headers, such as with PHP's mail() function. Since this method natively uses UTF-8 encoding, it is okay to use special non-Latin characters in either the email subject or message text. Under the hood, this method utilizes a third-party PHP library called PHPMailer.
Parameters
to
The recipient's email address. If using more than one email address, they must be separated by commas and/or semi-colons.
The recipient's email address. If using more than one email address, they must be separated by commas and/or semi-colons.
from
The sender's email address (i.e., from whom the email will appear to be sent). This will also be the "reply-to" address as it appears to the recipient.
The sender's email address (i.e., from whom the email will appear to be sent). This will also be the "reply-to" address as it appears to the recipient.
subject
The email subject.
The email subject.
message
The email message text. You may use HTML in the message, and if you wish to do so, you will need to wrap the entire message text in <html><body>...</body></html> tags.
The email message text. You may use HTML in the message, and if you wish to do so, you will need to wrap the entire message text in <html><body>...</body></html> tags.
cc
(optional) The email address of someone being CC'd on this email. If using more than one email address, they must be separated by commas and/or semi-colons.
(optional) The email address of someone being CC'd on this email. If using more than one email address, they must be separated by commas and/or semi-colons.
bcc
(optional) The email address of someone being BCC'd on this email. If using more than one email address, they must be separated by commas and/or semi-colons.
(optional) The email address of someone being BCC'd on this email. If using more than one email address, they must be separated by commas and/or semi-colons.
fromName
(optional) The sender's email display name that will be displayed in the recipient's email client next to the sender's email address (e.g., "Rob Taylor").
(optional) The sender's email display name that will be displayed in the recipient's email client next to the sender's email address (e.g., "Rob Taylor").
attachments
(optional) An array of one or more file attachments, in which the array keys will represent file name as seen in the email client and the corresponding array values will represent the full file path of the attachment file on the REDCap server.
(optional) An array of one or more file attachments, in which the array keys will represent file name as seen in the email client and the corresponding array values will represent the full file path of the attachment file on the REDCap server.
Return Values
TRUE is returned if the email has been sent successfully, else FALSE if not.
Examples
Example #1:
This example shows how to send a basic email.
// Set the text of the email first
$email_text = "A participant (record '$record') noted on the survey that they are suicidal. "
. "Please take appropriate actions immediately to contact them.";
// Send the email
REDCap::email('surveyadmin@mystudy.com', 'redcap@yoursite.edu', 'Suicide alert', $email_text);
Example #2:
This example illustrates how to send an HTML email with some styling.
// Set the text and HTML of the email first
$email_text = '<html><body style="font-family:arial,helvetica;">
You can use HTML to <b>bold</b> text in the email, or style it
with <span style="color:red;">red text</span>. You can also
add <a href="http://mysite.com">links</a> to your email text.
</body></html>';
// Send the HTML email
REDCap::email('recipient@mysite.com', 'sender@yoursite.edu', 'Suicide alert', $email_text);
Example #3:
This example shows how to send a basic email with error catching if the email does not send successfully.
// Send the email
$sentSuccessfully = REDCap::email('recipient@mysite.com', 'redcap@yoursite.edu',
'My custom subject', 'My email generic text to recipient.');
// If not sent successfully, display an error message to user
if (!$sentSuccessfully) {
print "<div class='red'>ERROR: The email could not be sent!</div>";
}
Example #4:
This example shows how to add a display name for the sender and also how to add file attachments.
// Set array of attachment files that exist on the server
$attachments = array(
"MySurveyResponse.pdf"=>"/app001/www/redcap/temp/20190816170154_Azg3gb.pdf",
"Study-Document4.docx"=>"/app001/www/redcap/edocs/20190904100930_pid35_Q5t8Dj.docx"
);
// Send the email
REDCap::email('recipient@email.com', 'redcap.admin@yoursite.edu', 'This is the subject', 'This is the email body.',
'', '', 'REDCap Administrator', $attachments);
REDCap 14.9.1 - © 2024 Vanderbilt University