archived-doc-es/reference/mail/functions/mail.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: ecfc4c394dc12dbf8d09680429f5d89fb62702e3 Maintainer: seros Status: ready -->
<!-- Reviewed: yes Maintainer: seros -->
<refentry xml:id="function.mail" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>mail</refname>
  <refpurpose>Enviar correo</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>mail</methodname>
   <methodparam><type>string</type><parameter>to</parameter></methodparam>
   <methodparam><type>string</type><parameter>subject</parameter></methodparam>
   <methodparam><type>string</type><parameter>message</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>additional_headers</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>additional_parameters</parameter></methodparam>
  </methodsynopsis>
  <para>
   Envía un correo electrónico.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>to</parameter></term>
     <listitem>
      <para>
       Destinatario/s del correo.
      </para>
      <para>
       El formato de este string debe cumplir con la
       <link xlink:href="&url.rfc;2822">RFC 2822</link>. Algunos ejemplos son:
       <simplelist>
        <member>usuario@example.com</member>
        <member>usuario@example.com, otrousuario@example.com</member>
        <member>Usuario &lt;usuario@example.com&gt;</member>
        <member>Usuario &lt;usuario@example.com&gt;, Otro usuario &lt;otrousuario@example.com&gt;</member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       Título del correo electrónico a enviar.
      </para>
      <caution>
       <para>
        El título debe cumplir con la <link xlink:href="&url.rfc;2047">RFC 2047</link>.
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>message</parameter></term>
     <listitem>
      <para>
       Mensaje a enviar.
      </para>
      <para>
       Cada línea debería separarse con un CRLF (\r\n). Las líneas no deberían
       ocupar más de 70 caracteres.
      </para>
      <caution>
       <para>
        (Sólo en Windows) Cuando PHP se comunica directamente con un servidor SMTP,
        si encuentra un punto al principio de la línea, éste se elimina. Para
        evitar esto es necesario reemplazar estas apariciones con un doble punto.
        <programlisting role="php">
<![CDATA[
<?php
$texto = str_replace("\n.", "\n..", $texto);
?>
]]>
        </programlisting>
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_headers</parameter> (opcional)</term>
     <listitem>
      <para>
       String a insertar al final de la cabecera del correo.
      </para>
      <para>
       Se usa normalmente para añadir cabeceras extra (From, Cc y Bcc).
       Las cabeceras múltiples adicionales deberían separarse con un CRLF(\r\n).
       Si se usan datos externos para componer esta cabecera, los datos deberían ser saneados
       para que no se inyecten cabeceras no deseadas. 
      </para>
      <note>
       <para>
        <parameter>additional_headers</parameter> no posee protección de inyección de cabeceras
        de correo. Por tanto, los usuarios deben asegurarse de que las cabeceras especificadas
        son seguras y contienen solamente cabeceras. Es decir, nunca iniciar el cuerpo del correo
        con varias nuevas líneas.
       </para>
      </note>
      <note>
       <para>
        Cuando se envía un correo, este <emphasis>debe</emphasis> contener
        una cabecera <literal>From</literal>. Puede establecerse con el
        parámetro <parameter>additional_headers</parameter>, o puede definirse
        un valor predeterminaro en &php.ini;.
       </para>
       <para>
        Si no se realiza esta acción se obtendrá un mensaje de
        error similar a <literal>Warning: mail(): "sendmail_from" not
        set in php.ini or custom "From:" header missing (Advertencia: mail(): "sendmail_from" no establecido en php.ini o falta la cabecera personalizada "From:")</literal>.
        La cabecera <literal>From</literal> también establece
        <literal>Return-Path</literal> bajo Windows.
       </para>
      </note>
      <note>
       <para>
        Si no se reciben los mensajes enviados, intente usar solamente LF (\n).
        Algunos agentes de transferencia de correo de Unix (como
        <link xlink:href="&url.qmail;">qmail</link>) reemplzan LF por CRLF
        automáticamente (lo que conlleva doblar CR si se usa CRLF).
        Esto debería ser el último recurso, pues no cumple con la
        <link xlink:href="&url.rfc;2822">RFC 2822</link>.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_parameters</parameter> (opcional)</term>
     <listitem>
      <para>
       El parámetro <parameter>additional_parameters</parameter> puede
       usarse para indicar opciones adicionales como opciones de línea de comandos
       al programa que está configurado para usarse cuando se envía correo, definido
       por la opción de configuración <literal>sendmail_path</literal>. Por
       ejemplo, puede usarse para establecer la dirección de correo del
       remitente usando sendmail con su opción <literal>-f</literal>.
      </para>
      <para>
       Este parámetro es escapado internamente por <function>escapeshellcmd</function>
       para prevenir la ejecución del comando. Aunque <function>escapeshellcmd</function>
       evita la ejecución del comando, permite añadir parámetros adicionales. Por razones de seguridad,
       se recomienda que el usuario sanee este parámetro para evitar que se añadan
       parámetros indeseados al comando.
      </para>
      <para>
       Ya que <function>escapeshellcmd</function> se aplica automáticamente, algunos caracteres
       que están permitidos como direcciones de correo electrónico por algún RFC no se pueden usar. 
       <function>mail</function> no puede permitir tales caracteres, por lo que en programas donde el uso
       de tales caracters sea necesario, se recomienda una vía alternativa de enviar correos
       (como usar un marco de trabajo o una biblioteca). 
      </para>
      <para>
       El usuario usado por el servidor web debería ser añadido como usuario de confianza
       en la configuración de sendmail para evitar que se añada la cabecera 'X-Warning'
       al mensaje cuando se añada la dirección de remitente (-f) usando este método.
       Para los usuarios de sendmail, este fichero es <filename>/etc/mail/trusted-users</filename>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve &true; si el correo ha sido aceptado para su envío, de lo contrario &false;.
  </para>
  <para>
   Es importante tener en cuenta que si el correo es aceptado para su envío, NO
   quiere decir que el correo haya alcanzado el destino indicado.
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4.2.3</entry>
       <entry>
        El parámetro <parameter>additional_parameters</parameter> es
        deshabilitado en <link linkend="ini.safe-mode">safe_mode</link> y la
        función <function>mail</function> mostrará un mensaje de advertencia,
        devolviendo &false; cuando se usa.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Enviar un correo.</title>
    <para>
     Usando <function>mail</function> para enviar un correo simple:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// El mensaje
$mensaje = "Línea 1\r\nLínea 2\r\nLínea 3";

// Si cualquier línea es más larga de 70 caracteres, se debería usar wordwrap()
$mensaje = wordwrap($mensaje, 70, "\r\n");

// Enviarlo
mail('caffeinated@example.com', 'Mi título', $mensaje);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Enviar un correo con cabeceras extra.</title>
    <para>
     Adición de cabeceras básicas, diciendo al MUA las direcciones From y
     Reply-To:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$para      = 'nobody@example.com';
$titulo    = 'El título';
$mensaje   = 'Hola';
$cabeceras = 'From: webmaster@example.com' . "\r\n" .
    'Reply-To: webmaster@example.com' . "\r\n" .
    'X-Mailer: PHP/' . phpversion();

mail($para, $titulo, $mensaje, $cabeceras);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Enviar un correo con parámetros de línea de comando adicionales.</title>
    <para>
     Se puede usar el parámetro <parameter>additional_parameters</parameter>
     para proporcionar parámetros adicicionales al programa configurado para
     usar en el envío de correo utilizando <literal>sendmail_path</literal>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
mail('nadie@example.com', 'El título', 'El mensaje', null, 
'-fwebmaster@example.com');
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Envío de un correo HTML</title>
    <para>
     Es posible también enviar correos HTML con <function>mail</function>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// Varios destinatarios
$para  = 'aidan@example.com' . ', '; // atención a la coma
$para .= 'wez@example.com';

// título
$título = 'Recordatorio de cumpleaños para Agosto';

// mensaje
$mensaje = '
<html>
<head>
  <title>Recordatorio de cumpleaños para Agosto</title>
</head>
<body>
  <p>¡Estos son los cumpleaños para Agosto!</p>
  <table>
    <tr>
      <th>Quien</th><th>Día</th><th>Mes</th><th>Año</th>
    </tr>
    <tr>
      <td>Joe</td><td>3</td><td>Agosto</td><td>1970</td>
    </tr>
    <tr>
      <td>Sally</td><td>17</td><td>Agosto</td><td>1973</td>
    </tr>
  </table>
</body>
</html>
';

// Para enviar un correo HTML, debe establecerse la cabecera Content-type
$cabeceras  = 'MIME-Version: 1.0' . "\r\n";
$cabeceras .= 'Content-type: text/html; charset=iso-8859-1' . "\r\n";

// Cabeceras adicionales
$cabeceras .= 'To: Mary <mary@example.com>, Kelly <kelly@example.com>' . "\r\n";
$cabeceras .= 'From: Recordatorio <cumples@example.com>' . "\r\n";
$cabeceras .= 'Cc: birthdayarchive@example.com' . "\r\n";
$cabeceras .= 'Bcc: birthdaycheck@example.com' . "\r\n";

// Enviarlo
mail($para, $título, $mensaje, $cabeceras);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <note>
    <para>
     Si la intención es enviar HTML u otro tipo de correo complejo, es recomendable usar
     el paquete PEAR <link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link>.
    </para>
   </note>
  </para>
 </refsect1>
 
 <refsect1 role="notes">    
  &reftitle.notes;
  <note>
   <para>
    La implementación en Windows de <function>mail</function> difiere bastante
    de la implementación en Unix. Primero, no usa un binario local para
    componer mensajes ya que sólo opera en sockets directos, lo que significa
    que es necesario un <literal>MTA</literal> escuchando en un socket de
    red (que puede estar tanto en localhost como en una máquina remota).
   </para>
   <para>
    Segundo, las cabeceras personalizadas como
    <literal>From:</literal>,
    <literal>Cc:</literal>,
    <literal>Bcc:</literal> y
    <literal>Date:</literal>, de entrada <emphasis role="strong">no</emphasis>
    son interpretadas por el <literal>MTA</literal>, aunque son
    analizadas por PHP.
   </para>
   <para>
    Por esto, el parámetro <parameter>to</parameter> no debería ser una
    dirección de correo de la forma &quot;Algo &lt;alguien@example.com&gt;&quot;.
    Es posible que el comando mail no analice esto correctamente mientrasz dialoga con
    el MTA.
   </para>
  </note>
  
  <note>
   <para>
    Es importante indicar que la función <function>mail</function> no es
    conveniente para grandes volúmenes de correo en bucle. Esta función abre y
    cierra un socket SMTP para cada correo, algo que no es muy eficiente.
   </para>
   <para>
    Para enviar una gran cantidad de correo, véanse los paquetes <link
    xlink:href="&url.pear.package;Mail">PEAR::Mail</link> y <link
    xlink:href="&url.pear.package;Mail_Queue">PEAR::Mail_Queue</link>.
   </para>
  </note>
  
  <note>
   <para>
    Las siguientes RFC pueden ser de utilidad:
    <link xlink:href="&url.rfc;1896">RFC 1896</link>,
    <link xlink:href="&url.rfc;2045">RFC 2045</link>,
    <link xlink:href="&url.rfc;2046">RFC 2046</link>,
    <link xlink:href="&url.rfc;2047">RFC 2047</link>,
    <link xlink:href="&url.rfc;2048">RFC 2048</link>,
    <link xlink:href="&url.rfc;2049">RFC 2049</link>, y
    <link xlink:href="&url.rfc;2822">RFC 2822</link>.
   </para>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>imap_mail</function></member>
    <member><link xlink:href="&url.pear.package;Mail">PEAR::Mail</link></member>
    <member><link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>


<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->