SMTP_AddHeader

Home

4D Internet Commands v16

SMTP_AddHeader


SMTP_AddHeader ( smtp_ID ; headerName ; headerText {; deleteOption} ) -> Function result

Parameter	Type	Description
smtp_ID	Longint	Message reference
headerName	String	Name of header
headerText	Text	Header text
deleteOption	Integer	0 = Add 1 = Replace all headers with 'headerName', 2 = Remove all headers named 'headerName'
Function result	Integer	Error Code

Description

The SMTP_AddHeader command allows users to add their own headers to the message referenced by smtp_ID. Beyond the various headers 4D Internet Commands have provided commands for, there are two additional categories of headers, these being 'user-defined' and 'extended' headers. The SMTP_AddHeader command permits the user to add both the new header tag and the data to associate with it.

Extended-Headers: These headers have been officially recognized by the NIC and were defined after the original SMTP specification. These headers often have a specific function to effect behavior in various software applications. Extended headers never begin with the letter "X".

User-Defined Headers: The SMTP protocol allows anyone to create their own header definitions. All user-defined headers should begin with the characters "X-" so there will be no possibility of conflict with a future Extended-Header. User-defined headers are tremendously useful when you have design control over both ends of the communications.

User defined headers allow the developer to store data which can easily be pulled out using the POP3 external command MSG_FindHeader. For example, you may create a header named "X-001001", which contains the value in field 01 of file 01. An unlimited number of headers may be added to a message. User-defined headers give the user the ability to add information that can easily be extracted without the need to parse through the body of the message to find the appropriate information.

smtp_ID is the long integer reference to the mail message created with the SMTP_New command.

headerName is a string which contains the name of the header to be added.

headerText is a text value containing the information to be assigned to the field identified by headerName.

Warning: The text should not contain a line feed (ascii=10). Doing so would signify the end of the header section and the beginning of the body. Subsequent header items could be pushed into the body and not recognized properly by the server or client software. For more information regarding the headers, please refer to RFC#822.

Note: The command does nothing if headerName or headerText is an empty string (no header is added).

deleteOption is an optional integer parameter which specifies whether to delete the current header. A value of zero will add headerName to the message. A value of 1 will replace all headers with headerName. In this case, if headerName is a null string, all headers will be removed. A value of 2 will remove all headers named headerName.

Note: Beginning with version 14 of 4D Internet Commands, when you want to send an HTML message, you no longer need to change the "Content-Type" header using SMTP_AddHeader. You can declare the use of the HTML format directly using the SMTP_Body command, in which case the "Content-Type" will be defined automatically as "text/html;charset=utf-8" (otherwise, the "Content-Type" is set by default as "text/plain;charset=utf-8"). However, for specific needs, you can always "force" the "Content-Type" field with SMTP_AddHeader. In this case, make sure to specify the charset (normally "charset=utf-8" since, by default, 4D IC always sends the body as UTF-8).