SetBody (Email subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (Created page with "This callable method allows you to add content to the body of an SMTP message. ==SetBody syntax== <p class="pre"> %email:SetBody(content, [options]) </p> ===Syntax terms=== <ta...")
mNo edit summary
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Template:Email:SetBody subtitle}}
{{Template:Email:SetBody subtitle}}


This callable method allows you to add content to the body of an SMTP message.
==Syntax==
==Syntax==
{{Template:Email:SetBody syntax}}
{{Template:Email:SetBody syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%email</th>
<tr><th>email</th>
<td>A previously declared <var>Email</var> object.
<td>An <var>Email</var> object.</td></tr>
</td></tr>
 
<tr><th>content</th>
<tr><th>content</th>
<td>A <var>Stringlist</var> or <var>Longstring</var> that contains the actual e-mail body.
<td>A <var>Stringlist</var> or <var>Longstring</var> that contains the actual e-mail body.
Line 18: Line 18:
In this case, no delimiter is added at the end of an item.
In this case, no delimiter is added at the end of an item.
   
   
If a longstring is passed, no delimiters are added to the content.
If a longstring is passed, no delimiters are added to the content. </td></tr>
</td></tr>
 
<tr><th>options</th>
<tr><th><var>Type</var></th>
<td>Any combination of the following options. Each may be specified only once.
<td>This [[Notation conventions for methods#Name required|name required]] parameter specifies the MIME type of the content.
<dl>
MIME content-type strings consist of a primary type and a subtype delimited by a forward slash ( / ) character, for example, <code>text/xml</code>.
<dt><b>Type</b>
<dd>This [[Notation conventions for methods#Name required|name required]] parameter
specifies the MIME type of the content.
MIME content type strings consist
of a primary type and a subtype delimited by a forward slash ( / ) character,
for example, <code>text/xml</code>.
   
   
<var>SetBody</var> performs no validity checking, but it does distinguish
<var>SetBody</var> performs no validity checking, but it does distinguish between text MIME types ("text"; is the primary type) and non-text types.
between text MIME types (&amp;ldquo;text&amp;rdquo; is the primary type) and non-text types.
If non-text, <var>SetBody</var> encodes the content in base64 format to ensure correct translation at SMTP gateways.
If non-text, <var>SetBody</var> encodes the content in base64 format
You can override this encoding by specifying the <var>Encoding</var> option set to the value <code>none</code>. </td></tr>
to ensure correct translation at SMTP gateways.
 
You can override this encoding by specifying
<tr><th><var>Name</var></th>
the <var>Encoding</var> option set to the value <code>none</code>.
<td>This name required parameter provides a name for the message body or a message part. This option is rarely used for the mail body, and it is usually ignored by the mail client. It is most often used for attachments, which are added with <var>[[AddPart (Email subroutine)|AddPart]]</var>. </td></tr>
<dt><b>Encoding</b>
 
<dd>This [[Notation conventions for methods#Name required|name required]] parameter
<tr><th><var>Encoding</var>
forces or suppresses encoding for the attachment.
<td>This name required parameter forces or suppresses encoding for the attachment.
Since base64 encoding is automatically enabled for any non-text content,
Since base64 encoding is automatically enabled for any non-text content, the <var>Encoding</var> option is usually unnecessary.
the <var>Encoding</var> option is usually unnecessary.
To enable base64 encoding for text content, specify <code>encoding=base64</code>. To disable encoding for non-text content, specify <code>encoding=none</code>.
To enable base64 encoding for text content, specify <code>encoding=base64</code>.
To disable encoding for non-text content, specify <code>encoding=none</code>.
Specifying <code>encoding=none</code> for non-text content is
not recommended: the likely result is that the recipient receives corrupt data,
or otherwise the SMTP gateway may simply discard the message.
<dt><b>Name</b>
<dd>This name required parameter provides a name for the
message body or a message part.
This option is rarely used for the mail body, and it is usually ignored
by the mail client.
It is most often used for attachments, which are added with <var>[[AddPart (Email subroutine)|AddPart]]</var>.
</dl>
</td></tr></table>
   
   
Specifying <code>encoding=none</code> for non-text content is ''not'' recommended: the likely result is that the recipient receives corrupt data, or otherwise the SMTP gateway may simply discard the message.</td></tr>
</table>
==Usage notes==
==Usage notes==
<ul>
Subsequent invocations of the <var>SetBody</var> method completely replace any
<li>The <var>Type</var>, <var>Name</var>, and <var>Encoding</var> options may be specified in any combination, but each may be specified only once.
existing content.
<li>Subsequent invocations of the <var>SetBody</var> method completely replace any existing content.
<br>
</ul>
 
==Examples==
==Examples==
<ul>
<ul>
<li>The following code fragment adds HTML text to the to the body of an
<li>The following code fragment adds HTML text to the to the body of an
SMTP message:
SMTP message:
<p class="code"> ...
<p class="code"> ...
%greet is object Email
%greet is object Email
%sl is object Stringlist
%sl is object Stringlist
html to %sl
html to %sl
  <html>
<html>
  <h1>
<nowiki><h1>
  Hello world!
  Hello world!
  </h1>
</h1></nowiki>
  </html>
</html>
end html
end html
%greet:SetBody(%sl, type='text/html')
%greet:SetBody(%sl, type='text/html')
  ...
...
</p>
</p>
<li>For <var>SetBody</var> method examples, see [[SMTP Helper#Basic e-mail|"Basic e-mail"]] and
<li>For more <var>SetBody</var> method examples, see [[Email class#Basic e-mail example|"Basic e-mail example"]] and
[[SMTP Helper#E-mail with attachment|"E-mail with attachment"]].
[[Email class#E-mail with attachment|"E-mail with attachment"]].
</ul>
</ul>
==See also==
==See also==
{{Template:Email:SetBody footer}}
{{Template:Email:SetBody footer}}

Latest revision as of 21:54, 14 August 2012

Add body content to the message (Email class)


Syntax

email:SetBody( content, [Type= string], [Name= string], [Encoding= string])

Syntax terms

email An Email object.
content A Stringlist or Longstring that contains the actual e-mail body.

If a Stringlist is passed, each item in the Stringlist is delimited with a carriage-return/line-feed (CR/LF) character pair. To override this line-ending, you can specify a non-text content type as the value of the Type optional argument. In this case, no delimiter is added at the end of an item.

If a longstring is passed, no delimiters are added to the content.
Type This name required parameter specifies the MIME type of the content.

MIME content-type strings consist of a primary type and a subtype delimited by a forward slash ( / ) character, for example, text/xml.

SetBody performs no validity checking, but it does distinguish between text MIME types ("text"; is the primary type) and non-text types. If non-text, SetBody encodes the content in base64 format to ensure correct translation at SMTP gateways.

You can override this encoding by specifying the Encoding option set to the value none.
Name This name required parameter provides a name for the message body or a message part. This option is rarely used for the mail body, and it is usually ignored by the mail client. It is most often used for attachments, which are added with AddPart.
Encoding This name required parameter forces or suppresses encoding for the attachment.

Since base64 encoding is automatically enabled for any non-text content, the Encoding option is usually unnecessary. To enable base64 encoding for text content, specify encoding=base64. To disable encoding for non-text content, specify encoding=none.

Specifying encoding=none for non-text content is not recommended: the likely result is that the recipient receives corrupt data, or otherwise the SMTP gateway may simply discard the message.

Usage notes

  • The Type, Name, and Encoding options may be specified in any combination, but each may be specified only once.
  • Subsequent invocations of the SetBody method completely replace any existing content.

Examples

  • The following code fragment adds HTML text to the to the body of an SMTP message:

    ... %greet is object Email %sl is object Stringlist html to %sl <html> <h1> Hello world! </h1> </html> end html %greet:SetBody(%sl, type='text/html') ...

  • For more SetBody method examples, see "Basic e-mail example" and "E-mail with attachment".

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=SetBody_(Email_subroutine)&oldid=47276"