Actions

Difference between revisions of "Sending email from extensions"

From Joomla! Documentation

(See also)
($send->message is a private property.)
 
(8 intermediate revisions by 5 users not shown)
Line 1: Line 1:
This is an example of how to send an email from a component. You would typically put this into your components controller.
+
{{version|2.5,3.1}}
 
+
This is an example of how to send an email from a component. You would typically put this into your component's controller.
=== Fetch the mail object ===
+
=== Fetch the Mail Object ===
 
A reference to the global mail object (JMail) is fetched through the JFactory object. This is the object creating our mail.
 
A reference to the global mail object (JMail) is fetched through the JFactory object. This is the object creating our mail.
  
 
<source lang="php">
 
<source lang="php">
$mailer =& JFactory::getMailer();
+
$mailer = JFactory::getMailer();
 
</source>
 
</source>
  
=== Set a sender ===
+
=== Set a Sender ===
The sender of an email is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSender setSender]. The function takes an array with an email address and a name as an argument. We fetch the sites email address and name from the global configuration. These are set in the administration back-end (Global Configuration -> Server -> Mail Settings).
+
The sender of an email is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSender setSender]. The function takes an array with an email address and a name as an argument. We fetch the site's email address and name from the global configuration. These are set in the administration back-end (Global Configuration -> Server -> Mail Settings).
  
 
<source lang="php">
 
<source lang="php">
$config =& JFactory::getConfig();
+
$config = JFactory::getConfig();
 
$sender = array(  
 
$sender = array(  
 
     $config->getValue( 'config.mailfrom' ),
 
     $config->getValue( 'config.mailfrom' ),
Line 19: Line 19:
 
$mailer->setSender($sender);
 
$mailer->setSender($sender);
 
</source>
 
</source>
 +
 +
In 3.1, $config->getValue() should be changed to $config->get()
  
 
=== Recipient ===
 
=== Recipient ===
Line 25: Line 27:
  
 
<source lang="php">
 
<source lang="php">
$user =& JFactory::getUser();
+
$user = JFactory::getUser();
 
$recipient = $user->email;
 
$recipient = $user->email;
  
Line 31: Line 33:
 
</source>
 
</source>
  
If we had multiple recipients we would put each recipients email address in an array.
+
If we had multiple recipients, we would put each recipient's email address in an array.
  
 
<source lang="php">
 
<source lang="php">
Line 39: Line 41:
 
</source>
 
</source>
  
=== Create the mail ===
+
=== Create the Mail ===
 
We need to set a subject line and create the text body. The subject is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSubject setSubject].  
 
We need to set a subject line and create the text body. The subject is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSubject setSubject].  
  
The easy way to create an email body is as a string with plain text. Use the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setBody setBody] to add a message to the mail body. You can also attach a file with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#addAttachment addAttachment]. It takes a single file name or an array of file names as argument.
+
The easy way to create an email body is as a string with plain text. Use the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setBody setBody] to add a message to the mail body. You can also attach a file with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#addAttachment addAttachment]. It takes a single file name or an array of file names as the argument.
  
 
<source lang="php">
 
<source lang="php">
Line 49: Line 51:
 
$mailer->setBody($body);
 
$mailer->setBody($body);
 
// Optional file attached
 
// Optional file attached
$mailer->addAttachment(JPATH_COMPONENT.DS.'assets'.DS.'document.pdf');
+
$mailer->addAttachment(JPATH_COMPONENT.'/assets/document.pdf');
 
</source>
 
</source>
  
Line 62: Line 64:
 
$mailer->setBody($body);
 
$mailer->setBody($body);
 
// Optionally add embedded image
 
// Optionally add embedded image
$mailer->AddEmbeddedImage( JPATH_COMPONENT.DS.'assets'.DS.'logo128.jpg', 'logo_id', 'logo.jpg', 'base64', 'image/jpeg' );
+
$mailer->AddEmbeddedImage( JPATH_COMPONENT.'/assets/logo128.jpg', 'logo_id', 'logo.jpg', 'base64', 'image/jpeg' );
 
</source>
 
</source>
  
 
Normally you would leave any images on your server and refer to them with an ordinary HTML image tag, to reduce size of the mail and the time sending it.
 
Normally you would leave any images on your server and refer to them with an ordinary HTML image tag, to reduce size of the mail and the time sending it.
  
=== Sending the mail ===
+
=== Sending the Mail ===
 
+
 
The mail is sent with the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#Send Send]. It returns '''true''' on success or a JError object.
 
The mail is sent with the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#Send Send]. It returns '''true''' on success or a JError object.
  
 
<source lang="php">
 
<source lang="php">
$send =& $mailer->Send();
+
$send = $mailer->Send();
 
if ( $send !== true ) {
 
if ( $send !== true ) {
     echo 'Error sending email: ' . $send->message;
+
     echo 'Error sending email: ' . $send->__toString();
 
} else {
 
} else {
 
     echo 'Mail sent';
 
     echo 'Mail sent';
Line 82: Line 83:
 
You would probably want to write your own error handler, if there is an error sending the mail.
 
You would probably want to write your own error handler, if there is an error sending the mail.
  
The JMail object is used for sending mail in Joomlas contact manager. See the file joomla/components/com_contact/controller.php
+
The JMail object is used for sending mail in Joomla's contact manager. See the file joomla/components/com_contact/controller.php
  
 
===See also===
 
===See also===
* [http://docs.joomla.org/JFactory/getMailer Docs on JFactory->getMailer]
+
* [http://api.joomla.org/Joomla-Platform/JFactory.html#getMailer JFactory->getMailer on api.joomla.org]
* [http://api.joomla.org/1.5/Joomla-Framework/JFactory.html#getMailer JFactory->getMailer on api.joomla.org]
+
  
 
[[Category:Development]]
 
[[Category:Development]]
 +
[[Category:Component Development]]

Latest revision as of 16:04, 10 March 2014

This is an example of how to send an email from a component. You would typically put this into your component's controller.

Contents

Fetch the Mail Object

A reference to the global mail object (JMail) is fetched through the JFactory object. This is the object creating our mail.

$mailer = JFactory::getMailer();

Set a Sender

The sender of an email is set with setSender. The function takes an array with an email address and a name as an argument. We fetch the site's email address and name from the global configuration. These are set in the administration back-end (Global Configuration -> Server -> Mail Settings).

$config = JFactory::getConfig();
$sender = array( 
    $config->getValue( 'config.mailfrom' ),
    $config->getValue( 'config.fromname' ) );
 
$mailer->setSender($sender);

In 3.1, $config->getValue() should be changed to $config->get()

Recipient

You set the recipient of an email with the function addRecipient. To set the email address to the currently logged in user, we fetch it from the user object.

$user = JFactory::getUser();
$recipient = $user->email;
 
$mailer->addRecipient($recipient);

If we had multiple recipients, we would put each recipient's email address in an array.

$recipient = array( 'person1@domain.com', 'person2@domain.com', 'person3@domain.com' );
 
$mailer->addRecipient($recipient);

Create the Mail

We need to set a subject line and create the text body. The subject is set with setSubject.

The easy way to create an email body is as a string with plain text. Use the function setBody to add a message to the mail body. You can also attach a file with addAttachment. It takes a single file name or an array of file names as the argument.

$body   = "Your body string\nin double quotes if you want to parse the \nnewlines etc";
$mailer->setSubject('Your subject string');
$mailer->setBody($body);
// Optional file attached
$mailer->addAttachment(JPATH_COMPONENT.'/assets/document.pdf');

If you prefer to format your email in HTML, you need to tell the mailer it is HTML. This is done with IsHTML. When sending HTML emails you should normally set the Encoding to base64 in order to avoid unwanted characters in the output. The subject line and any attachments are handled as above, with the exception of images embedded in the HTML. These are taken care of with the function AddEmbeddedImage.

$body   = '<h2>Our mail</h2>'
    . '<div>A message to our dear readers'
    . '<img src="cid:logo_id" alt="logo"/></div>';
$mailer->isHTML(true);
$mailer->Encoding = 'base64';
$mailer->setBody($body);
// Optionally add embedded image
$mailer->AddEmbeddedImage( JPATH_COMPONENT.'/assets/logo128.jpg', 'logo_id', 'logo.jpg', 'base64', 'image/jpeg' );

Normally you would leave any images on your server and refer to them with an ordinary HTML image tag, to reduce size of the mail and the time sending it.

Sending the Mail

The mail is sent with the function Send. It returns true on success or a JError object.

$send = $mailer->Send();
if ( $send !== true ) {
    echo 'Error sending email: ' . $send->__toString();
} else {
    echo 'Mail sent';
}

You would probably want to write your own error handler, if there is an error sending the mail.

The JMail object is used for sending mail in Joomla's contact manager. See the file joomla/components/com_contact/controller.php

See also