AddHeader (Email subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (Created page with "This callable method lets you add an SMTP request header to the SMTP request that is sent to the server. ==AddHeader syntax== <p class="pre"> %email:AddHeader(header, value) </p>...")
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:Email:AddHeader subtitle}}
{{Template:Email:AddHeader subtitle}}


This callable method lets you add an SMTP request header
to the SMTP request that is sent to the server.
==Syntax==
==Syntax==
{{Template:Email:AddHeader syntax}}
{{Template:Email:AddHeader syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%email</th>
<tr><th>email</th>
<td>A previously declared Email object.
<td>An <var>Email</var> object.</td></tr>
</td></tr>
 
<tr><th>header</th>
<tr><th>header</th>
<td>A string expression that names an SMTP request
<td>A string expression that names an SMTP request header, such as "Reply-To:" or "In-Reply-To:". Header names are case insensitive, but they should have a trailing colon.
header, such as &amp;ldquo;Reply-To&amp;rdquo; or &amp;ldquo;In-Reply-To.&amp;rdquo;
<p>
Header names are case insensitive.
Passing multiple occurrences is allowed: if a like-named header is already present, an additional occurrence is added.</p></td></tr>
 
Passing multiple occurrences is allowed:
if a like-named header is already present, an additional
occurrence is added.
</td></tr>
<tr><th>value</th>
<tr><th>value</th>
<td>A string expression that yields a value for the
<td>A string expression that yields a value for the request header.</td></tr>
request header.
</table>
 
</td></tr></table>
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Do ''not'' set &amp;ldquo;To:&amp;rdquo; or &amp;ldquo;Cc:&amp;rdquo; headers using this method.
<li>Do ''not'' set "To:" or "CC:" headers using this method.
These headers
These headers require special handling and are set using the <var>[[AddRecipient (Email subroutine)|AddRecipient]]</var> and <var>[[AddCC (Email subroutine)|Add CC]]</var> methods, respectively.
require special handling and are set using the AddRecipient and AddCc
The <var>[[Mail (Email function)|Mail]]</var> method will not recognize recipients added with <var>AddHeader</var>.
methods, respectively.
 
The Mail method will not recognize recipients added with AddHeader.
<li>Do ''not'' set Content-Type headers using this method.
<li>Do ''not'' set Content-Type headers using this method.
These headers require special handling and are set using parameters on
These headers require special handling and are set using parameters on
the SetBody and AddPart methods.
the <var>[[SetBody (Email subroutine)|SetBody]]</var> and <var>[[AddPart (Email subroutine)|AddPart]]</var> methods.
Specifying a header that has a &amp;ldquo;Content-&amp;rdquo; prefix causes a request cancellation.
Specifying a header that has a "Content-" prefix causes a request cancellation.
<li>The SMTP Helper adds a &amp;ldquo;Date:&amp;rdquo; header to an Email object instance by default
 
if you do not explicitly add one with AddHeader.
<li>The SMTP Helper adds a "Date:" header to an <var>Email</var> object instance by default if you do not explicitly add one with <var>AddHeader</var>.
If a Date header is present at the time the mail method is invoked,
If a Date header is present at the time the mail method is invoked, it is left intact.
it is left intact.
The Date header generated by the SMTP Helper uses the system clock (usually GMT),
The Date header generated by the SMTP Helper uses the system clock (usually GMT),
adjusted by the GMT offset specified in the OS system parameters.
adjusted by the GMT offset specified in the OS system parameters.
<li>For an example that includes this method, see [[SMTP Helper#Basic e-mail|"Basic e-mail"]].
 
<li>For an example that includes this method, see [[Email class#Basic e-mail example|Basic e-mail example]].
</ul>
</ul>
==See also==
==See also==
{{Template:Email:AddHeader footer}}
{{Template:Email:AddHeader footer}}

Latest revision as of 20:57, 2 September 2014

Add an SMTP request header (Email class)


Syntax

email:AddHeader( header, value)

Syntax terms

email An Email object.
header A string expression that names an SMTP request header, such as "Reply-To:" or "In-Reply-To:". Header names are case insensitive, but they should have a trailing colon.

Passing multiple occurrences is allowed: if a like-named header is already present, an additional occurrence is added.

value A string expression that yields a value for the request header.

Usage notes

  • Do not set "To:" or "CC:" headers using this method. These headers require special handling and are set using the AddRecipient and Add CC methods, respectively. The Mail method will not recognize recipients added with AddHeader.
  • Do not set Content-Type headers using this method. These headers require special handling and are set using parameters on the SetBody and AddPart methods. Specifying a header that has a "Content-" prefix causes a request cancellation.
  • The SMTP Helper adds a "Date:" header to an Email object instance by default if you do not explicitly add one with AddHeader. If a Date header is present at the time the mail method is invoked, it is left intact. The Date header generated by the SMTP Helper uses the system clock (usually GMT), adjusted by the GMT offset specified in the OS system parameters.
  • For an example that includes this method, see Basic e-mail example.

See also