SMTP/POP3/IMAP Email Engine
Reference Library
(SEE_REF)
Version 5.0
April 8, 2008
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2008
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815 USA
Voice : 1.256.881.4630
Email : info@marshallsoft.com
Web : www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 General Remarks2 SEE Functions
1.2 Documentation Set
1.3 Declaration Files
1.4 Language Notes
2.1 seeAbort3 SEE Error Return Code List 0
2.2 seeAttach
2.3 seeAttachmentParams
2.4 seeByteToShort
2.5 seeClose
2.6 seeCommand
2.7 seeDebug
2.8 seeDecodeBuffer
2.9 seeDecodeUTF8
2.10 seeDecodeUU
2.11 seeDeleteEmail
2.12 seeDriver
2.13 seeEncodeBuffer
2.14 seeEncodeUTF8
2.15 seeErrorText
2.16 seeExtractLine
2.17 seeExtractText
2.18 seeForwardEmail
2.19 seeGetEmailCount
2.20 seeGetEmailFile
2.21 seeGetEmailLines
2.22 seeGetEmailSize
2.23 seeGetEmailUID
2.24 seeImapConnect
2.25 seeImapCopyMBmail
2.26 seeImapCreateMB
2.27 seeImapDeleteMB
2.28 seeImapFlags
2.29 seeImapListMB
2.30 seeImapMsgNumber
2.31 seeImapRenameMB
2.32 seeImapSearch
2.33 seeImapSelectMB
2.34 seeImapSource
2.35 seeIntegerParam
2.36 seePop3Connect
2.37 seePop3Source
2.38 seeQuoteBuffer
2.39 seeRelease
2.40 seeSendEmail
2.41 seeSendHTML
2.42 seeShortToByte
2.43 seeSmtpConnect 3
2.44 seeStatistics 4
2.45 seeStringParam 6
2.46 seeVerifyFormat 8
2.47 seeVerifyUser 9
The SMTP/POP3/IMAP Email Engine (SEE) is a component library of functions providing easy control of the SMTP (Simple Mail Transport Protocol), POP3 (Post Office 3), and IMAP 4 (Internet Message Access Protocol) protocols. A simple interface allows sending and receiving mail, including multiple MIME base64 and quoted-printable encoded attachments from within an application. Knowledge of Winsock and TCP/IP is not needed. We have versions of the SMTP/POP3/IMAP Email Engine SDK for C/C++ (SEE4C), Delphi (SEE4D), Visual Basic (SEE4VB), PowerBASIC (SEE4PB), Visual FoxPro (SEE4FP), Visual dBase (SEE4DB), Alaska Xbase++ (SEE4XB), COBOL (SEE4CB), and Fortran (SEE4F). All versions of SEE use the same DLL (SEE32.DLL) and can be called from any program or compiler that can call the Windows API.
The latest version of our SMTP/POP3/IMAP Email component software and complete technical documentation can be found online at
http://www.marshallsoft.com/email-component-library.htm
This SMTP/POP3/IMAP Email Reference Manual (SEE_REF) contains details on each individual SEE function.
All functions return an integer code. Negative values are always errors. Refer to Section 3.0 below, "SEE Error Return Code List"). The file, ERRORS.TXT, contains a list of all error codes and their corresponding numeric value.
Non-negative return codes are never errors. Note that the seeErrorText function is used to get the text message associated with any error code.
Each function argument is marked as:
(I) : 4-byte integer.
(L) : 4-byte integer.
(P) : 4-byte pointer.
Refer to the declaration files (see Section 1.3 below) for the exact syntax of each SEE function. Also note that the example programs show exactly how SEE functions are called.
The complete set of documentation consists of three manuals in two formats. This is the third manual (SEE_REF) in the set.
Each manual comes in two formats:
The SEE_4x Programmer's Manual is the programming language dependent manual and provides information needed to compile your programs as well as the examples in the specified environment. The "x" in SEE_4x Programmer's Manual specifies the host language such as C for C/C++, VB for Visual Basic, etc.
The SEE User's Manual (SEE_USR) discusses language independent SMTP/POP3/IMAP email processing issues. License and purchase information is also provided.
The SEE Reference Manual (SEE_REF) contains details on each individual SEE function.
The exact syntax for calling SMTP/POP3/IMAP Email component (SEE) functions is specific to the host language (C/C++, Delphi, VB, etc.) and is defined for each language in the "SEE declaration files". Each SEE product comes with the appropriate declaration file for the supported language. For example,
SEE4C C/C++, .NET, C# SEE.H
SEE4D Borland Delphi SEE32.PAS
SEE4VB Visual Basic SEE32.BAS
VB.NET
VBA (EXCEL,ACCESS,etc.) SEE32.BAS
SEE4PB PowerBASIC SEE32.PBI
SEE4FP Visual FoxPro SEE32.FOX
SEE4DB Visual dBase SEE32.CC
SEE4XB Xbase++ SEE32.CH
SEE4CB Fujitsu COBOL SEE32.CBI
SEE4F Fortran SEE32ABS.INC and SEE32DEC.INC
If you are programming in a language that is capable of calling Windows API functions directly, then your application can also call SEE functions. Let us know if you need a declaration file such a language.
Most SEE functions are used in one or more of the example programs.
All language versions of the SMTP/POP3/IMAP Email component library include the example program SEEVER. Refer to this program and the declaration file as defined in Section 1.3 above to see how SEE functions are called. The SEEVER program is also the first program that should be compiled and run.
The best way to learn how a function is called is to find it used in one of the example programs.
If you will be using SEE with C/C++ and another language, order the C/C++ version.
SEE works with Visual C/C++, Borland C/C++, Borland C++ Builder, Watcom C/C++, LCC, Visual C++ .NET and Visual C# .NET through Visual Studio 2008.
Functions defined in the Delphi Unit SEEW.PAS begin with "f" rather than "see".
SEE works with all versions of Delphi.
SEE works with all version of Visual Basic including VB .NET and Visual Basic for Applications (VBA).
Constants defined for PowerBASIC (SEE32.PBI) begin with the character '%' symbol.
SEE works with PBCC, PBDLL, and PBWIN.
All strings passed to SEE functions must be prefixed with the '@' character.
SEE works with all versions of 32-bit Visual FoxPro as well as 16-bit FoxPro 2.5.
SEE works with all versions of Visual dBase.
Functions defined for Xbase++ begin with 'X'. All strings passed to SEE functions must be prefixed with the '@' character.
SEE works with all versions of Alaska Xbase++.
SEE4CB supports Fujitsu COBOL, but we also have a few example programs for other COBOL compilers such as ACUCOBOL, Micro Focus COBOL, Realia COBOL, and RM COBOL.
We have example programs for ABSOFT, Salford, Compaq Visual Fortran, and Digital Visual Fortran.
seeAbort(Chan)
Chan : (I) Channel number.
The seeAbort function is used to abort the SEE state driver. This is used when calling the SEE state driver (seeDriver) directly and it is necessary to abort.
After calling seeAbort, subsequent calls to seeDriver will return 0 (IDLE). Thus, SEE is ready for the next command.
This function is not required unless the state driver seeDriver is being called directly.
// Abort SEE
seeAbort(0);
BASIC Example
' Abort SEE
Code = seeAbort(0)
seeDriver
seeAttach(NbrChans,KeyCode)
NbrChans : (I) Number of channels or threads.
KeyCode : (L) Registration key code.
The seeAttach function must be the first SEE call made. Pass the maximum number of channels or threads that will be in use. Use NbrChans = 1 for non-threaded applications.
The 'Chan' parameter for subsequent calls to SEE functions must be in the range of 0 to NbrChans-1.
In Win32, up to 128 threads (numbered from 0 to 127) can be started, each of which can be connected to a different server and run independently.
When SEE is registered, you will receive a 'KeyCode' which matches the 'KeyCode' within the registered DLL. The keycode is 0 for the evaluation version. Refer to file KEYCODE.
All example programs call seeAttach.
// Initialize SEE (look in KEYCODE.H for SEE_KEY_CODE)
seeAttach(1, SEE_KEY_CODE);
BASIC Example
' Initialize SEE (look in KEYCODE.BAS for SEE_KEY_CODE)
Code = seeAttach(1, SEE_KEY_CODE)
seeSmtpConnect; seePop3Connect.
seeAttachmentParams(ContentType,Encoding,Disposition,Description)
ContentType : (P) Content-Type header.
Encoding : (P) Content-Transfer-Encoding header.
Disposition : (P) Content-Disposition header.
Description : (P) Content-Description header.
This function specifies the "Content-Type:" headers for up to the first 5 attachments. Additional attachments, if any, use the standard default headers. Passing a NULL or an empty string to any one of the four parameters sets that parameter to the default value "application/octet-stream."
The purpose of this function is to enable the creation of specific types of Multi-Part MIME parts. For example, specifying
Content-Type: audio/x-wav
sets the Content-Type of the attachment file to (audio) WAV which will allow some email clients to play the WAV file when the attachment is clicked.
The seeAttachmentParams is used with SMTP servers only.
// set content parameters for first attachment
LPSTR ContentType = "Content-Type: audio/x-wav";
LPSTR XferEncoding = "Content-Transfer-Encoding: base64 ";
LPSTR Disposition = "Content-Disposition: attachment; filename= myfile.wav;"
LPSTR Description = "Content-Description: This is an audio wave file"
Code = seeAttachmentParams(ContentType, XferEncoding, Disposition, Description)
BASIC Example
' set content parameters for first attachment
Dim ContentType, XferEncoding, Disposition, Description As String
ContentType = "Content-Type: audio/x-wav"
XferEncoding = "Content-Transfer-Encoding: base64 "
Disposition = "Content-Disposition: attachment; filename= myfile.wav"
Description = "Content-Description: This is an audio wave file"
Code = seeAttachmentParams(ContentType, XferEncoding, Disposition, Description)
seeSmtpConnect, seePop3Connect; MPARTS example program.
seeByteToShort(Buffer)
Buffer : (P) character buffer
The seeByteToShort function converts the (null terminated) character buffer 'Buffer' from 8-bit ASCII characters to 16-bit Unicode ASCII characters.
The buffer must be null terminated (last character is a hex 00) and the buffer must be at least twice the size (in bytes) of the character string (since 16-bit characters require twice the space as 8-bit characters).
This function is only necessary when working with 16-bit Unicode ASCII characters in C# and Delphi 2005.
See C example CODETEST
int Code;
char AsciiString[] = "MarshallSoft\0\0\0\0\0\0\0\0\0\0\0\0";
// Convert 8-bit ASCII string to 16-bit ASCII
Code = seeByteToShort((LPSTR)AsciiString);
seeShortToByte
seeClose(Chan)
Chan : (I) Channel number.
The seeClose function closes the connection created by calling seeSmtpConnect, seePop3Connect, or seeImapConnect. SeeSmtpConnect, seePop3Connect, or seeImapConnect can be called again to open a connection to another SMTP, POP3, or IMAP server if desired.
SEE can not be connected to both the SMTP server and the POP3 server at the same time (unless you are using threads). Call seeClose to terminate the connection before connecting again.
If seeSmtpConnect / seePop3Connect / seeImapConnect fails, do not call seeClose.since the connection is already closed.
// close connection to server
seeClose(0);
BASIC Example
' seeClose(0)
Code = seeClose(0)
seeSmtpConnect , seePop3Connect. All example programs call seeClose.
seeCommand(Chan, Text)
Chan : (I) Channel number.
Text : (I) Command.
The seeCommand function sends an arbitrary text command to the SMTP or POP3 server after connecting.
The seeCommand function is designed to allow the user to send commands that are specific to a particular SMTP or POP3 server. It can also be used to send SMTP or POP3 commands that are not implemented in the SEE library.
Call seeDebug with SEE_GET_LAST_RESPONSE in order to get the text of the server's response.
// send NOOP command to server
LPSTR X = "NOOP"
Code = seeCommand(0, X)
BASIC Example
' send NOOP command to server
X = "NOOP" + Chr$(0)
Code = seeCommand(0, X)
HELLO example program.
seeDebug(Chan, Index, Buffer, BufLen)
Chan : (I) Channel number.
Index : (I) Command index.
Buffer : (P) Buffer to place text into.
BufLen : (I) Length of above Buffer.
The seeDebug function returns (textual) debug information depending on the value of Index.
SEE_COPY_BUFFER : Copies internal buffer.
SEE_GET_ATTACH_NAMES : Gets list of attachment file names.
SEE_GET_LAST_RECIPIENT : Gets last recipient acknowledged by server.
SEE_GET_LAST_RESPONSE : Gets last server response.
SEE_GET_LOCAL_IP : Gets local IP address.
SEE_GET_REGISTRATION : Gets the SEE registration string.
SEE_GET_SERVER_IP : Get server IP address in dotted notation.
SEE_GET_ATTACH_TYPES : Get list of attachment types.
SEE_COPY_BUFFER is used to copy the internal SEE buffer created when calling
seeGetEmailLines with NULL passed for 'Buffer'. Refer to seeGetEmailLines for details.
SEE_GET_ATTACH_NAME gets the list of filenames received from downloading email from a POP3 server. Call only after all email has been read.
SEE_GET_LAST_RECIPIENT gets the last recipient acknowledged by the POP3 server. This is only useful when running in direct mode (calls seeDriver) when a list of email addresses is being used in one call to seeSendEmail.
SEE_GET_LAST_RESPONSE gets the text of the last server response.
SEE_GET_LOCAL_IP Gets the local IP address in dotted decimal notation. Use only after connecting to an SMTP or POP3 server.
SEE_GET_REGISTRATION gets the user's SEE registration string.
SEE_GET_SERVER_IP gets the server IP address in dotted decimal notation. Use only after connecting to an SMTP or POP3 server.
SEE_GET_ATTACH_TYPES gets a list of attachment types separated by semi-colons. Use only after completely downloading the email message.
// Get text of last server response
char Buffer[128];
Code = seeDebug(0, SEE_GET_LAST_RESPONSE, (LPSTR)Buffer, 128);
BASIC Example
' Get text of last server response
Dim Buffer As String * 128
Code = seeDebug(0, SEE_GET_LAST_RESPONSE, Buffer, 128)
seeStatistics; SEEVER and GETRAW example programs.
seeDecodeBuffer(CodedPtr, ClearPtr, Length)
CodedPtr : (P) Buffer of base-64 coded chars.
ClearPtr : (P) Buffer to put decoded bytes.
Length : (I) Length of above buffer.
The seeDecodeBuffer function decodes the buffer 'CodedPtr' of length 'Length' into 'ClearPtr', returning the length in 'ClearPtr'.
The buffer 'CodedPtr' MUST contain base-64 encoded text, as created by seeEncodeBuffer.
The buffer 'ClearPtr' will contain the ASCII or binary data that was encoded.
// BASE64 decode coded buffer
char CodedBuffer[] = "TWFyc2hhbGxTb2Z0";
char ClearBuffer[50];
CodedLength = strlen(CodedBuffer)
ClearLength = seeDecodeBuffer(CodedBuffer, ClearBuffer, CodedLength);
BASIC Example
' BASE64 decode coded buffer
CodedBuffer = "TWFyc2hhbGxTb2Z0"
ClearBuffer = Space$(50)
CodedLength = LEN(CodedBuffer)
ClearLength = seeDecodeBuffer(CodedBuffer, ClearBuffer, CodedLength)
seeEncodeBuffer; CODETEST example program.
seeDecodeUTF8(UTF8Buffer, UnicodeBuffer)
UTF8Buffer : (P) Buffer for UTF8 string.
UnicodeBuffer: (P) Pointer to buffer for 16-bit Unicode character.
The seeDecodeUTF8 function is used to decode a UTF8 string segment into a 16-bit Unicode value. Upon return, the first two bytes of 'UnicodeBuffer' will contain the two bytes that make up the 16-bit Unicode value in low byte, high byte order.
More information on Unicode can be found at http://www.unicode.org
See CODETEST.C
See CODETEST.FRM
seeDecodeBuffer; CODETEST example program.
seeDecodeUU (CodedBuf, ClearBuf)
CodedBuf : (P) Buffer containing UU encoded text.
ClearBuf : (P) Buffer into which to copy decoded text.
The seeDecodeUU function is used to decode a UU-encoded line passed in 'CodedBuf'. The line must be terminated with a carriage return (CR) character or by a NULL character.
For example, the following UU-encoded text contains the single line "MarshallSoft Computing.".
begin 666 test.txt
836%R<VAA;&Q3;V9T($-O;7!U=&EN9RX`
`
end
The leading byte (8) corresponds to the length of the line (24 characters) and is not passed to seeDecodeUU. Refer to the example below.
Unlike MIME encoded attachments, UU-encoded attachments cannot always be located algorithmically. For this reason, the programmer must write code to find any UU-encoded attachments, and decode one line at a time.
UU-encoding has been obsolete since the advent of MIME encoding. Nevertheless, some UU-encoded attachments are still being emailed, and therefore this function is provided.
// decode test UU-encoded string
lstrcpy((LPSTR)CodedBuff,(LPSTR)"36%R<VAA;&Q3;V9T($-O;7!U=&EN9RX`\r\n");
CodedLen = lstrlen((LPSTR)CodedBuff);
ClearLen = seeDecodeUU((LPSTR)CodedBuff,(LPSTR)ClearBuff);
ClearBuff[ClearLen] = '\0';
BASIC Example
' decode test UU-encoded string
CodedBuff = "36%R<VAA;&Q3;V9T($-O;7!U=&EN9RX`" + Chr$(13) + Chr$(10)
CodedLen = Len(CodedBuff)
ClearLen = seeDecodeUU(CodedBuff, ClearBuff)
ClearBuff = Left$(ClearBuff,ClearLen)
seeDecodeBuffer.
seeDeleteEmail(Chan, MsgNbr)
Chan : (I) Channel number.
MsgNbr : (I) Message number.
The seeDeleteEmail function deletes the email numbered 'MsgNbr' from the server.
The first message is always number 1. Call seeGetEmailCount first to get the number of email messages on the server. Email is not renumbered or physically deleted until you call seeClose.
Be careful! Once an email has been deleted from the server, it cannot be recovered.
The seeDeleteEmail function is used with POP3 and IMAP servers only.
Return < 0 : An error has occurred. See section 3 "SEE Error Return Code List".
// delete email message 1 (first email message) on server
seeDeleteEmail(0, 1)
BASIC Example
' delete email message 1 (first email message) on server
Code = seeDeleteEmail(0, 1)
seeGetEmailUID, seeGetEmailCount; READER example program.
seeDriver(Chan)
Chan : (I) Channel number.
The seeDriver function executes the next state in the SEE state engine. The purpose of this function is to allow the programmer to get control after the driver executes each state.
The seeDriver function is explicitly called only after the AUTO_DRIVER_CALL flag has been disabled (see function seeIntegerParam). If the AUTO_DRIVER_CALL flag has not been disabled (the default), then seeDriver does not need to be called.
Refer to the Section 4 "Theory of Operation" in the SMTP/POP3/IMAP Email Users Manual (SEE_USR) for more details on the operation of seeDriver.
C/C++ Example
// execute next state Code = seeDriver(0);BASIC Example
' execute next state Code = seeDriver(0)
seeIntegerParam, seeSmtpConnect, and seePop3Connect; READER example program.
seeEncodeBuffer(ClearBuf, CodedBuf, Length)
ClearBuf : (P) Buffer of characters to encode.
CodedBuf : (P) Buffer to put base-64 encoded.
Length : (I) Length of above.
The seeEncodeBuffer function encodes 'ClearBuf' into 'CodedBuf' using Base-64 encoding.
The 'ClearBuf' buffer may contain any ASCII or binary data.
The 'CodedBuf' buffer will contain 7-bit ASCII data broken into lines of 76 characters followed by a carriage return (hex 0D) and line feed (hex 0A). That is, 'CodedBuf' will contain multiple lines.
// BASE64 encode buffer
char ClearBuffer[] = "MarshallSoft";
char CodedBuffer[50];
ClearLength = strlen(CodedBuffer)
CodedLength = seeEncodeBuffer(ClearBuffer, CodedBuffer, ClearLength);
BASIC Example
' BASE64 encode buffer
ClearBuffer = "MarshallSoft\r\n"
CodedBuffer = Space$(50)
ClearLength = LEN(ClearBuffer)
CodedLength = seeEncodeBuffer(ClearBuffer, CodedBuffer, ClearLength)
seeQuoteBuffer and CODESTEST example program.
seeEncodeUTF8(UnicodeValue, UTF8Buffer)
UnicodeValue : (I) 16-bit unicode character.
UTF8Buffer : (P) Buffer for UTF8 string.
The seeEncodeUTF8 function encodes the 16-bit Unicode value 'UnicodeValue' into a UTF8 string.
Upon return, the 'UTF8Buffer' buffer will contain the UTF8 string corresponding to the Unicode value. The length of this string is returned.
More information on Unicode can be found at http://www.unicode.org
See CODETEST.C
See CODETEST.FRM
SeeDecodeUTF8 and CODESTEST example program.
seeErrorText(Chan, ErrCode, Buffer, BufLen)
Chan : (I) Channel number.
ErrCode: (I) Error code returned by SEE function.
Buffer : (P) Buffer to place error text into.
BufLen : (I) Length of above Buffer.
The seeErrorText function is used to get the error text associated with an error code as returned by one of the other SEE functions.
When an error occurs, seeErrorText can be used to get the error text so that it can be displayed for the user. See Section 3 "SEE Error Return Code List." The file, ERRORS.TXT, contains a list of all error codes and their corresponding numeric value.
// get text associated with ErrCode
char Buffer[80];
Code = seeErrorText(0, ErrCode, (LPSTR)Buffer, 80)
BASIC Example
' // get text associated with ErrCode
Dim Buffer As String * 80
Code = seeErrorText(0, ErrCode, Buffer, 80)
Most example programs call seeErrorText.
seeExtractLine(Src, Line, Buffer, BufSize)
Src : (P) Text buffer to search.
Line : (I) Line number (1,2,...) wanted.
Buffer : (P) Buffer for line if found.
BufSize : (I) Size of 'Buffer'.
The seeExtractLine function is used to extract line 'Line' from buffer 'Src'. If the specified line number is found, then the entire line, up to a maximum of 'BufSize' bytes, is copied to 'Buffer'. The primary purpose of seeExtractLine is to extract header lines (by line number) from the buffer after calling seeGetEmailLines. Recall that all lines returned by seeGetEmailLines are terminated by a carriage return, linefeed pair. Lines are numbered from 1 rather than 0.
The seeExtractLine does not require a connection to an SMTP or POP3 server.
// extract line # 4 from (multi-line) buffer ListBuffer
char LineBuffer[128];
seeExtractLine((LPSTR)ListBuffer, 4, (LPSTR)LineBuffer, 128);
BASIC Example
' extract line # 4 from (multi-line) buffer ListBuffer
Dim LineBuffer As String * 128
seeExtractLine(ListBuffer, 4, LineBuffer, 128)
seeGetEmailLines and seeExtractText.; STATUS example program.
seeExtractText(Src, Text, Buffer, BufSize)
Src : (P) Text buffer to search.
Text : (P) Text searching for.
Buffer : (P) Buffer for line if found.
BufSize : (I) Size of 'Buffer'.
The seeExtractText function is used to search the text buffer 'Src' for text 'Text'. If the specified text is found, then the entire line, up to a maximum of 'BufSize' bytes, is copied to 'Buffer'.
The primary purpose of seeExtractText is to extract header lines from the buffer after calling seeGetEmailLines. Recall that all lines returned by seeGetEmailLines are terminated by a carriage return, linefeed pair.
The seeExtractText does not require a connection to a SMTP or POP3 server.
// extract line from Buffer containing "Reply-To: "
char Buffer[255];
n = seeExtractText(Buffer, (LPSTR)"Reply-To: ", Buffer, 255)
BASIC Example
' extract line from Buffer containing "Reply-To: "
ExString = "Reply-To: "
Dim Buffer As String * 255
n = seeExtractText(Buffer, ExString, Buffer, 255)
seeGetEmailLines, seeExtractLine; STATUS and FROM example programs.
seeForward(Chan, To, CC, BCC, Subj, Msg, Forward)
Chan : (I) Channel number.
To : (P) Recipient, separated by semi-colons.
CC : (P) CC list, separated by semi-colons.
BCC : (P) BCC list, separated by semi-colons.
Subj : (P) Subject text.
Msg : (P) Message or message filename.
Forward: (P) Filename (of undecoded email) to forward.
The seeForward function is used to forward an email to a new recipient. The filename of the (undecoded) email to be forwarded must be attached as the last argument, and is encoded as a message/rfc822 MIME part.
For an explanation of how to download an undecoded copy of an email, see the
The seeForwardEmail function is used with SMTP servers only.
// forward (undecoded) email file Email2Forward to <info@yourisp.com>
Code = seeForwardEmail(0, (LPSTR)"<info@yourisp.com>",
(LPSTR)NULL, (LPSTR)NULL, (LPSTR)"Test",
(LPSTR)"Forwarding test", Email2Forward);
BASIC Example
' forward (undecoded) email file Email2Forward to <info@yourisp.com>
To = "<info@yourisp.com>"
CC = Chr$(0)
BCC = Chr$(0)
Subject = "Test"
Message = "Forwarding test"
Code = seeForwardEmail(0, To, CC, BCC, Subject, Message, Email2Forward)
Refer to the FORWARD example program.
seeGetEmailFile; FORWARD example program.
seeGetEmailCount(Chan)
Chan : (I) Channel number.
The seeGetEmailCount function returns the number of messages waiting on the server, independent of whether they have been previously read.
If you have disabled the driver AUTO_CALL capability, the message count must be found by calling
seeStatistics(0, SEE_GET_MSG_COUNT)
after calling seeDriver until it returns 0.
The seeGetEmailCount function is used with POP3 and IMAP servers only.
// get # messages waiting on server
NbrMsg = seeGetEmailCount(0);
BASIC Example
' get # messages waiting on server
NbrMsg = seeGetEmailCount(0)
seeGetEmailLines; STATUS example program.
seeGetEmailFile(Chan, MsgNbr, EmailName, EmailDir, AttachDir)
Chan : (I) Channel number.
MsgNbr : (I) Message #.
EmailName : (P) Email filename.
EmailDir : (P) Directory for email.
AttachDir : (P) Directory for attachments.
The seeGetEmailFile reads the email message 'MsgNbr', saving it to disk as filename 'EmailName' in directory 'EmailDir', and saving MIME attachments to directory 'AttachDir'. The current directory is specified as '.'.
Be sure that the specified directories exist before calling this function. Use '.' to specify the current directory. Also note that an older file of the same name as the newer file will be overwritten.
An undecoded copy of the email being downloaded can be saved to disk by calling
seeStringParam(Chan, SEE_SET_RAWFILE_PREFIX, prefix-char)
before calling seeGetEmailFile. For example, if the prefix character is the underscore '_' and the filename passed to seeGetEmailFile is "mail.txt", then the undecoded copy will be named "_mail.txt".
The seeGetEmailFile function is used with POP3 and IMAP servers only.
// read email message # 4
char FileName[] = "Email4.txt";
char EmailDir[] = "\\SEE4C\\APPS";
char AttachDir[] = "\\SEE4C\\APPS";
Code = seeGetEmailFile(0, 4, (LPSTR)FileName,(LPSTR)EmailDir,(LPSTR)AttachDir);
BASIC Example
' read email message # 4
Dim FileName, EmailDir, AttachDir As String
FileName = "Email4.txt"
EmailDir = "\SEE4C\APPS"
AttachDir = "\SEE4C\APPS"
Code = seeGetEmailFile(0, 4, FileName, EmailDir, AttachDir)
seeGetEmailLines and seePop3Source; READER example program.
seeGetEmailLines(Chan, MsgNbr, Lines, Buffer, Size)
Chan : (I) Channel number.
MsgNbr : (I) Message #.
Lines : (I) Number of body lines.
Buffer : (P) Pointer to (static) Buffer.
Size : (I) Size of buffer.
The seeGetEmailLines function reads all header lines plus the number of body lines specified by the 'Lines' argument into 'Buffer', up to a maximum of 'Size' bytes.
The primary purpose of this function is to read the header lines without having to read the entire message.
If you have disabled the driver AUTO_CALL capability, the size must be found by calling
seeStatistics(Chan, SEE_GET_BUFFER_COUNT)
after calling seeDriver until it returns 0.
If a 0 is passed as the 4th argument (Buffer), SEE will use an internal buffer, the contents of which can be accessed by subsequently calling seeDebug(Chan, SEE_COPY_BUFFER,...) or calling seeStringParam(Chan, SEE_WRITE_BUFFER,...). This technique is ONLY necessary in direct mode (calling seeDriver directly) from languages (such as Visual Basic, dBase 2000, etc.) that cannot statically allocate memory. Refer to the SMTP/POP3/IMAP Email Programmer's Manual.
The seeGetEmailLines function is used with POP3 and IMAP servers only.
// read email message 5 (headers only) w/o decoding
char Buffer[10000];
Code = seeGetEmailLines(0, 5, 0, (LPSTR)Buffer, 10000);
BASIC Example
' read email message 5 (headers only) w/o decoding
Dim Buffer As String * 10000
Code = seeGetEmailLines(0, 5, 0, Buffer, 10000)
seeGetEmailFile; STATUS example program.
seeGetEmailSize(Chan, MsgNbr)
Chan : (I) Channel number.
MsgNbr : (I) Message number
The seeGetEmailSize function returns the size in bytes of the specified message 'MsgNbr'.
seeGetEmailSize returns the size of the entire email message, including any attachments. Note that attachments will be encoded (MIME, UUENCODE, etc.), and thus take up more room than after they are decoded.
If you have disabled the driver AUTO_CALL capability, the size must be found by calling
seeStatistics(0, SEE_GET_MSG_SIZE)
after calling seeDriver until it returns 0.
The seeGetEmailSize function is used with POP3 and IMAP servers only.
// get the size of email message # 2
MsgSize = seeGetEmailSize(0, 2);
BASIC Example
' get the size of email message # 2
MsgSize = seeGetEmailSize(0, 2)
seeGetEmailCount.; STATUS and READER example programs
seeGetEmailUID(Chan, MsgNbr, Buffer, Size)
Chan : (I) Channel number.
MsgNbr : (I) Message (-1 for all) number.
Buffer : (P) Pointer to Buffer.
Size : (I) Size of buffer.
The seeGetEmailUID function is used to ask the POP3 server for the unique user ID string for a particular email message, or for all email messages on the server.
The UID string is always unique for a particular email message, regardless of the email message number or when it was received. The purpose of the UID is to allow the client to determine if a particular email has been seen by it previously. The UID is useful is situations in which mail is left on the server and is accessed by more than one email client program.
Most POP3 servers can provide such a unique ID string. A few POP3 servers do not provide ID strings.
The seeGetEmailUID function is used with POP3 and IMAP servers only.
// get UID string for email message # 1
char Buffer[256];
n = seeGetEmailUID(0, 1, (LPSTR)Buffer, 256);
BASIC Example
' get UID string for email message # 1
Dim Buffer As String * 256
n = seeGetEmailUID(0, 1, Buffer, 256)
seeGetEmailCount; STATUS example program.
SYNTAX
seeImapConnect(Chan, Pop3Ptr, UserPtr, PassPtr) Pop3Ptr : (P) IMAP server name UserPtr : (P) Sender's email address PassPtr : (P) Reply-To header
The seeImapConnect function is used to connect to an IMAP server. Note that seeImapConnect uses the same arguments as seePop3Connect.
The well-known IMAP (default) port is 143.
// connect to POP3 server "mail.yourisp.com"
char ImapHost[] = "mail.yourisp.com";
char ImapUser[] = "bill";
char ImapPass[] = "abc";
Code = seeImapConnect(0, (LPSTR)ImapHost, (LPSTR)ImapUser, (LPSTR)ImapPass);
BASIC Example
' connect to Imap server "mail.yourisp.com"
Dim ImapHost, ImapUser. ImapPass As String
ImapHost = "mail.yourisp.com"
ImapUser = "bill"
ImapPass = "abc"
Code = seeImapConnect(0, ImapHost, ImapUser, ImapPass)
ImapSearch example program.
SYNTAX
seeImapCopyMBmail(Chan, Message, Mailbox) Chan : (I) Channel (0, 1, 2, ...) Message : (I) Message number to copy Mailbox : (I) Name of destination mailbox Note: seeImapCopyMBmail() is a "copy to", not a "copy from".
The seeImapCopyMBmail function is used to copy messages from the selected mailbox to the specified mailbox. That is, an email message is copied from the currently selected mailbox to the mailbox specified by the argument "Mailbox".
The seeImapCopyMBmail function is used with IMAP servers only.
C/C++ Example
char SavedBox[128]; strcpy((char *)SavedBox, "SavedBox"); Code = seeImapSelectMB(0, 7, SavedBox);BASIC Example
Dim SavedBox As String SavedBox = "SavedBox" Code = seeImapSelectMB(0, 7, SavedBox)
seeImapCreateMB(Chan, Mailbox)
Chan : (I) Channel (0, 1, 2, ...)
Mailbox : (P) Name of mailbox to create
The seeImapCreateMB function is used to create a new mailbox (MB). Once created, mail can be transferred between the new mailbox, the InBox, and any other previously created mailbox.
The seeImapCreateMB function is used with IMAP servers only.
C/C++ Example
char SavedBox[128]; strcpy((char *)SavedBox, "SavedBox"); Code = seeImapSelectMB(0, SavedBox);BASIC Example
Dim SavedBox As String SavedBox = "SavedBox" Code = seeImapSelectMB(0, SavedBox)
seeImapDeleteMB(Chan, Mailbox)
Chan : (I) Channel (0, 1, 2, ...)
Mailbox : (P) Name of mailbox to delete
The seeImapDeleteMB function is used to delete a mailbox (MB) previously created. However, the InBox cannot be deleted.
The seeImapDeleteMB function is used with IMAP servers only.
C/C++ Example
char SavedBox[128]; strcpy((char *)SavedBox, "SavedBox"); Code = seeImapSelectMB(0, SavedBox);BASIC Example
Dim SavedBox As String SavedBox = "SavedBox" Code = seeImapSelectMB(0, SavedBox)
seeImapFlags( Chan, MsgNbr, Command, FlagsMask)
Chan : (I) Channel (0, 1, 2, ...)
MsgNbr : (I) Message Number (1, 2, 3, ...)
Command : (I) Command (see below)
FlagsMask : (I) Flag mask. May be combined. (see below)
Command Symbol : Value, Meaning
IMAP_GET_FLAGS : 1, Get message flags
IMAP_SET_FLAGS : 2, Set message flags
IMAP_DEL_FLAGS : 3, Delete message flags
FlagsMask Symbol : Value, Meaning
IMAP_FLAG_SEEN : 1, Message has been read
IMAP_FLAG_ANSWERED : 2, Message has been answered
IMAP_FLAG_FLAGGED : 4, Message is "flagged" for special attention
IMAP_FLAG_DELETED : 8, Message is "deleted" for removal
IMAP_FLAG_DRAFT : 16, Message has been marked as a draft
IMAP_FLAG_RECENT : 32, Message has arrived since the previous
time this mailbox was selected.
IMAP_FLAG_SEEN refers to "\Seen" flag.
IMAP_FLAG_ANSWERED refers to "\Answered" flag.
IMAP_FLAG_FLAGGED refers to "\Flagged" flag.
IMAP_FLAG_DELETED refers to "\Deleted" flag.
IMAP_FLAG_DRAFT refers to "\Draft" flag.
IMAP_FLAG_RECENT refers to "\Recent" flag.
Note "\Recent" may be fetched but not stored.
REMARKS
The seeImapFlags function is used to get, set, or delete message flags.
The seeImapFlags function is used with IMAP servers only.
Flags = IMAP_FLAG_ANSWERED | IMAP_FLAG_FLAGGED;
Code = seeImapFlags(0, 1, IMAP_SET_FLAGS, Flags);
Flags = IMAP_FLAG_ANSWERED + IMAP_FLAG_FLAGGED
Code = seeImapFlags(0, 1, IMAP_SET_FLAGS, Flags)
seeImapListMB(Chan, Buffer, BufLen)
Chan : (I) Channel (0, 1, 2, ...)
Buffer : (P) Buffer into which the list of mailboxes are copied.
BufLen : (I) Length of above buffer.
C/C++ Example
char Buffer[3000]; Code = seeImapSelectMB(0, (char *)Buffer, 3000);BASIC Example
Dim Buffer As String Buffer = SPACE(3000) Code = seeImapSelectMB(0, Buffer, 3000)
seeImapMsgNumber(Chan, Command)
Chan : (I) Channel (0, 1, 2, ...)
Command : (I) Command (see below)
Command Symbol : Value, Meaning
IMAP_SEARCH_MSG_COUNT : 1, Get # messages found by seeImapSearch
IMAP_SEARCH_FIRST_MSG : 2, Get first message of set found.
IMAP_SEARCH_NEXT_MSG : 3, Get next message of set found.
The seeImapMsgNumber function called immediately after seeImapSearch and is used to return:
See the ImapSearch example program.
The seeImapMsgNumber function is used with IMAP servers only.
NbrMsg = seeImapMsgNumber(0, IMAP_SEARCH_MSG_COUNT);
BASIC Example
NbrMsg = seeImapMsgNumber(0, IMAP_SEARCH_MSG_COUNT)
ImapSearch example program.
seeImapRenameMB(Chan, FromName, ToName)
Chan : (I) Channel (0, 1, 2, ...)
FromName : (P) Existing name of mailbox
ToName : (P) New name of mailbox
The seeImapRenameMB function is used to rename a new mailbox (MB).
The seeImapRenameMB function is used with IMAP servers only.
C/C++ Example
char SavedBox[128]; strcpy((char *)SavedBox, "SavedBox"); Code = seeImapSelectMB(0, SavedBox);BASIC Example
Dim SavedBox As String SavedBox = "SavedBox" Code = seeImapSelectMB(0, SavedBox)
seeImapSearch(Chan, SearchArgs, Buffer, BufLen)
Chan : (I) Channel (0, 1, 2, ...)
SearchArgs : (P) Search string.
Buffer : (P) Result buffer where message numbers are copied.
BufLen : (I) Size of result buffer.
The seeImapSearch function is used to search for messages with specified strings.
Example search strings as passed to seeImapSearch():
SEEN
SEEN NOT ANSWERED
FLAGGED SINCE 1-Feb-2008 NOT FROM "Smith"
LARGER 10000 NOT SEEN
Refer to ImapSearch.txt, RFC 1730, or http://www.marshallsoft.com/ImapSearch.htm for a complete list.
After calling seeImapSearch, the function seeImapMsgNumber must be called in order to get the message numbers that seeImapSearch found that match the search criteria.
The seeImapSearch function is used with IMAP servers only.
strcpy((char )SearchArgs, (char )"LARGER 10000 NOT SEEN" ); Code = seeImapSearch(0, SearchArgs, (char *)Buffer, 128);BASIC Example
DIM SearchArgs As String SearchArgs = "LARGER 10000 NOT SEEN" Code = seeImapSearch(0, SearchArgs, Buffer, 128)ALSO REFER TO
ImapSearch example program.
seeImapSelectMB(Chan, Mailbox)
Chan : Channel (0, 1, 2, ...)
Mailbox : Name of mailbox to select
The seeImapSelectMB function is used to select a mailbox (MB) for processing. The standard inbox is "InBox".
The seeImapSelectMB function is used with IMAP servers only.
char SavedBox[128];
strcpy((char *)SavedBox, "SavedBox");
Code = seeImapSelectMB(0, SavedBox);
BASIC Example
Dim SavedBox As String
SavedBox = "SavedBox"
Code = seeImapSelectMB(0, SavedBox)
SYNTAX
seeImapSource(Chan, ImapFilename) Chan : (I) Channel number. Filename : (P) IMAP filename.REMARKS
The seeImapSource function is used to specify the path to a file containing an undecoded email. After calling this function, seeGetEmailFile can be called to decode the email as if it were being downloaded from an IMAP server.
Note that there is no IMAP connection. The email is read directly from a file.
The seeImapSource function is used with IMAP servers only.
C/C++ Example
// decode email file char Source[] = "c:\\see4c\\apps\\raw_email.txt"; Code = seeImapSource(0, (LPSTR)Source);BASIC Example
'decode email file Dim Source As String Source = "c:\see4c\apps\raw_email.txt" Code = seeImapSource(0, Source)
seeImapConnect and the POP3PRD example program.
seeIntegerParam(Chan, ParamIndex, ParamValue)
Chan : (I) Channel number.
ParamIndex : (I) Parameter name (see below).
ParamValue : (L) Value of parameter to set.
The seeIntegerParam function is used to set an integer parameter that is passed to the SEE library to provide additional control of email processing. The numeric value for each of the integer parameters is defined in the SEE declaration files. Section 1.3 "Declaration Files" provides a list the "Declaration Files". All times are in milliseconds. Defaults values are as follows:
Parameter Name Value
SEE_ADDRESS_DELIMITER : ';' [semicolon]
SEE_ALLOW_8BITS : 0 [FALSE]
SEE_ATTACH_DELIMITER : ';' [semicolon]
SEE_AUTHENTICATE_PROTOCOL : 1 [CRAM-MD5 authentication]
SEE_AUTO_CALL_DRIVER : 1 [TRUE]
SEE_BLOCKING_MODE : 1
SEE_CONNECT_WAIT : 60000
SEE_DECODE_UNNAMED : 0 [FALSE]
SEE_ENABLE_APOP : 0 [FALSE]
SEE_ENABLE_ESMTP : 0 [FALSE]
SEE_ENABLE_IMAGE : 1 [TRUE]
SEE_FILE_PREFIX : 0 [FALSE]
SEE_FORCE_INLINE : 0
SEE_HIDE_HEADERS : 0 [FALSE]
SEE_HIDE_SAVED_MSG : 0 [FALSE]
SEE_HIDE_TO_ADDR : 0 [FALSE]
SEE_IGNORE_REJECTED : 0 [FALSE]
SEE_IMAP_PORT : 143
SEE_KEEP_RFC822_INTACT : 0 [FALSE]
SEE_MAX_LINE_LENGTH : 76
SEE_MAX_RESPONSE_WAIT : 25000
SEE_MIN_RESPONSE_WAIT : 250
SEE_PATH_DELIMITER : ';' [semicolon]
SEE_POP3_PORT : 110
SEE_QUOTED_PRINTABLE : 0 [FALSE]
SEE_RAW_MODE : 0 [FALSE]
SEE_REPLACE_WITH_COMMAS : 1 [TRUE]
SEE_SET_RAWFILE_PREFIX : NUL [FALSE]
SEE_SLEEP_TIME : 50
SEE_SMTP_PORT : 25
SEE_WSACLEANUP : 1 [TRUE]
SEE_WRITE_CONTENT_TYPE : 0 [FALSE]
SEE_ADDRESS_DELIMITER sets the delimiter to use for separating multiple email
addresses.
SEE_ALLOW_8BITS will allow 8-bit data inside an email message. Note that 7-bit ASCII is the RFC822 standard. Not recommended!
SEE_ATTACH_DELIMITER is the character that delimits attachment name from file name (used to specify an attachment name different from the filename). Eg, "FileName.txt|AttachName.txt".
SEE_AUTO_CALL_DRIVER controls whether seeDriver is called automatically (to completion) after a SEE function has been called.
SEE_BLOCKING_MODE allows connect attempts to block waiting for the server response.
SEE_CONNECT_WAIT is the maximum time allowed to complete a connection to the email server.
SEE_DECODE_UNNAMED will force (if non-zero) decoding of all base64 attachments which do not have names.
SEE_ENABLE_APOP directs that the APOP command will be used for authenticating POP3 connections rather than USER and PASS. Requires that POP3 server recognizes the APOP command.
SEE_ENABLE_IMAGE allows (if non-zero) files ending with ".GIF", ".BMP", ".JPG", or ".TIF" to be attached as image types so that they can be displayed by the recipient's email client.
SEE_FILE_PREFIX controls whether "1-", "2-", etc. is prefixed to the filename of each attachment. If two attachments are named FILEONE.ZIP and FILETWO.ZIP, they will be saved as 1-FILEONE.ZIP and 2-FILETWO.ZIP. This feature should always be used unless you are downloading to a directory specifically for downloaded attachments. Pass an integer >= 1 to specify the first prefix.
SEE_HIDE_SAVED_MSG is used to hide the "Attachment saved to " message in incoming email.
SEE_HIDE_TO_ADDR is used to hide the "To:" field in outgoing email.
SEE_IGNORE_REJECTED directs SEE to ignore error returned if recipient is rejected.
SEE_MAX_LINE_LENGTH specifies the maximum length of the lines sent to the SMTP server. Note that the RFC822 standard specifies 76 characters.
SEE_MAX_RESPONSE_WAIT is the time after which a "timeout" error occurs if the server has not responded.
SEE_MIN_RESPONSE_WAIT is the delay before looking for the server's response.
SEE_PATH_DELIMITER is the character that delimits multiple file paths.
SEE_POP3_PORT changes the POP3 port.
SEE_QUOTED_PRINTABLE controls whether messages are or are not encoded as quoted-printable. Use QUOTED_OFF (0) to disable quoting, QUOTED_PLAIN (1) to enable normal quoting, QUOTED_HTML (2) to enabled quoting of embedded HTML text, (3) QUOTED_RICH to enable rich text quoting, and 8859 to enable ISO 8859 character quoting.
SEE_SLEEP_TIME is the time SEE sleeps when waiting on a Winsock.
SEE_SMTP_PORT changes the SMTP port.
SEE_RAW_MODE disables all decoding of email when downloaded by seeGetEmailFile.
SEE_ENABLE_ESMTP enables ESMTP (rather than SMTP) connections when calling seeSmtpConnect.
SEE_WRITE_CONTENT_TYPE causes (if ParamValue not 0) the Content-Type header to be written to the output email file (POP3 connections). Normally, this header is not written.
SEE_AUTHENTICATE_PROTOCOL specifies the protocol to use in performing SMTP authentication. Values are AUTHENTICATE_CRAM (value 1), AUTHENTICATE_LOGIN (value 2), and AUTHENTICATE_PLAIN (value 4).
SEE_FORCE_INLINE specifies if text attachments are inline or not. Possible values are INLINE_TEXT_OFF (0, not forced inline), INLINE_TEXT_INLINE (1, text attachments coded inline), or INLINE_TEXT_ATTACHMENT (2, text attachments attached as file).
SEE_HIDE_HEADER causes headers (such as "From:", "Subject:", etc.) to not be written to the email output file. This flag overrides any conflicting flags.
SEE_REPLACE_WITH_COMMAS causes the replacement of address delimiters in TO, CC, and BCC headers with commas.
SEE_KEEP_RFC822_INTACT causes SEE to keep RFC822 messages intact (not decoded) when downloaded. The RFC822 message will be saved to disk as a text attachment.
SEE_SET_RAWFILE_PREFIX causes an undecoded copy of an email downloaded by seeGetEmailFile to be saved with the same name as the decoded copy except prefixed by the specified prefix character.
SEE_IMAP_PORT changes the IMAP port.
//enable Extended SMTP (needed for SMTP authentication)
Code = seeIntegerParam(0, SEE_ENABLE_ESMTP, 1);
BASIC Example
' enable Extended SMTP (needed for SMTP authentication)
Code = seeIntegerParam(0, SEE_ENABLE_ESMTP, 1)
seePop3Connect(Chan, Pop3Ptr, UserPtr, PassPtr)
Chan : (I) Channel number.
Pop3Ptr : (P) POP3 server name.
UserPtr : (P) POP3 user name.
PassPtr : (P) POP3 password.
The seePop3Connect function establishes a connection with the POP3 server as specified by the Server argument.
The POP3 server name will typically be named "mail.XXX.com" where XXX is your email address, such as name@XXX.com. Your POP3 server name can also be found in the setup information for your normal email client, such as Eudora or Microsoft Outlook.
The POP3 server name can also be specified in dotted decimal notation. For example, "10.23.231.1".
SEE can not be connected to both the SMTP server and the POP3 server at the same time. Call seeClose to terminate the connection before connecting again
// connect to POP3 server "mail.yourisp.com"
char Pop3Host[] = "mail.yourisp.com";
char Pop3User[] = "bill";
char Pop3Pass[] = "abc";
Code = seePop3Connect(0, (LPSTR)Pop3Host, (LPSTR)Pop3User, (LPSTR)Pop3Pass);
BASIC Example
' connect to POP3 server "mail.yourisp.com"
Dim Pop3Host, Pop3User. Pop3Pass As String
Pop3Host = "mail.yourisp.com"
Pop3User = "bill"
Pop3Pass = "abc"
Code = seePop3Connect(0, Pop3Host, Pop3User, Pop3Pass)
seeSmtpConnect and seeClose; STATUS and READER example programs.
seePop3Source(Chan, Pop3Filename)
Chan : (I) Channel number.
Pop3Filename : (P) POP3 filename.
The seePop3Source function is used to specify the path to a file containing an undecoded email. After calling this function, seeGetEmailFile can be called to decode the email as if it were being downloaded from a POP3 server.
Note that there is no POP3 connection.
// decode email file
char Source[] = "c:\\see4c\\apps\\raw_email.txt";
Code = seePop3Source(0, (LPSTR)Source);
BASIC Example
'decode email file
Dim Source As String
Source = "c:\see4c\apps\raw_email.txt"
Code = seePop3Source(0, Source)
seePop3Connect; POP3RD example program.
seeQuoteBuffer(String, Buffer, BufLen)
String : (P) ISO 8859 text.
Buffer : (P) Buffer for ISO-8859 encoded string.
BufLen : (I) Size of above buffer.
The seeQuoteBuffer function creates an ISO-8859 encoded string in 'Buffer' from the ISO-8859 (8-bit character) ISO 8859 text in 'String'. The buffer length (3rd parameter) should be twice the size of the length of the string (1st parameter).
The primary use for the seeQuoteBuffer function is in constructing ISO-8859 compliant "Subject:" headers.
The default delimiter used to separate email addresses and path names was changed from a comma to a semi-colon in Version 3.6 of SEE.
// construct quoted subject string, identifying it as quoted iso-8859-1
char Text[] = "See attached file";
char Buffer[128];
Code = seeQuoteBuffer((LPSTR)Text, (LPSTR)Buffer, 128)
BASIC Example
' construct quoted subject string, identifying it as quoted iso-8859-1
Dim Text As String
Dim Buffer As Buffer * 128
Text = "See attached file";
Code = seeQuoteBuffer(Text, Buffer, 128)
seeEncodeBuffer; ISO8859 example program.
seeRelease
The seeRelease function releases the SEE system. SeeRelease is called only once and should be the very last SEE function called.
seeClose should be called for all channels before calling seeRelease.
// release SEE
seeRelease();
BASIC Example
' release SEE
Code = seeRelease()
Most of the example programs call seeRelease.
seeAttach.
seeSendEmail(Chan, To, CC, BCC, Subj, Msg, Attach)
Chan : (I) Channel number.
To : (P) Recipient, separated by semi-colons.
CC : (P) CC list, separated by semi-colons.
BCC : (P) BCC list, separated by semi-colons.
Subj : (P) Subject text.
Msg : (P) Message or message filename.
Attach : (P) File attachment list.
The seeSendEmail function is used to send email once a connection has been made to your SMTP server after calling seeSmtpConnect. Note that all email addresses (in To, CC, and BCC strings) must be bracketed, and the CC and BCC strings may contain multiple email addresses, separated by semi-colons. For example:
<info@marshallsoft.com>
"Billy Bob<bbob@isp.com>;Buster<bm@isp.com>"
If the first character of the message (fifth argument) is a '@', then it is considered as the filename which contains the message to send.
'Attach' may contain one or more attachments, separated by semi-colons, with no embedded spaces. For example,
"file1.zip;file2.doc;file3.bmp"
The default delimiter used to separate email addresses and path names was changed from a comma to a semi-colon in Version 3.6 of SEE. The semi-colon delimiter can be changed to any character with:
seeIntegerParam(Chan, SEE_ATTACH_DELIMITER, new-character)
If the function
seeIntegerParam(Chan, SEE_ENABLE_IMAGE, 1)
has been called previously, attachment files ending with ".GIF", ".BMP", or ".TIF" are attached as image types rather than regular images. This allows some email clients to display the images.
The seeSendEmail function is used with SMTP servers only.
// email file Message.txt to info@yourisp.com
char To[] = "<info@yourisp.com>"
char CC[] = "";
char BCC[] = "";
char Subject[] = "Test"
char Message[] = "@Message.txt"
char Attach[] = "";
Code = seeSendEmail(0, (LPSTR)To, (LPSTR)CC, (LPSTR)BCC,
(LPSTR)Subject, (LPSTR)Message, (LPSTR)Attach);
BASIC Example
' email file Message.txt to info@yourisp.com
Dim To, CC, BCC, Subject, Message, Attach
To = "<info@yourisp.com>"
CC = Chr$(0)
BCC = Chr$(0)
Subject = "Test"
Message = "@Message.txt"
Attach = Chr$(0)
Code = seeForwardEmail(0, To, CC, BCC, Subject, Message, Attach)
seeSendHTML; MAILER example program.
seeSendHTML(Chan, To, CC, BCC, Subject, Message,
Images, AltText, Attach)
Chan : (I) Channel number.
To : (P) Recipient, separated by semi-colons.
CC : (P) CC list, separated by semi-colons.
BCC : (P) BCC list, separated by semi-colons.
Subject: (P) Subject text.
Message: (P) Message or message filename.
Images : (P) List of embedded images
AltText: (P) Alternate text
Attach : (P) File attachment list.
The seeSendHTML function is used to send HTML encoded email. See the entry for 'seeSendEmail' for an explanation of the To, CC, and BCC fields.
If the first character of the message (6th argument) or alternate text (8th argument) is a '@', then it is considered as the filename which contains the message to send.
The 'Images' field contains the filenames of images that are to be embedded in the email message. The first image must be referenced in the text of the HTML encode email message as
<IMG SRC="cid:message-root.1">
The second image (if any) must be referenced as
<IMG SRC="cid:message-root.2">
Continue in this way for all embedded images.
'AltText' is used to provide a plain ASCII text equivalent of the message for those email clients that cannot decode HTML.
'Attach' may contain one or more attachments, separated by semicolons, with no embedded spaces. For example,
"file1.zip;file2.doc;file3.bmp"
The semi-colon delimiter used above can be changed to a new character with:
seeIntegerParam(Chan, SEE_PATH_DELIMITER, new-character)
The seeSendHTML function is used with SMTP servers only.
// email file Message.txt to <info@yourisp.com>
char To[] = "<info@yourisp.com>"
char CC[] = "";
char BCC[] = "";
char Subject[] = "HTML Test"
char Message[] = "@Message.htm"
char Images[] = "image1.gif;image2.gif"
char AltText[] = "@AltText.txt";
char Attach[] = "";
Code = seeSendEmail(0, (LPSTR)To, (LPSTR)CC, (LPSTR)BCC, (LPSTR)Subject,
(LPSTR)Message, (LPSTR)Images, (LPSTR)AltText, (LPSTR)Attach);
BASIC Example
' email file Message.txt to <info@yourisp.com>
Dim To, CC, BCC, Subject, Message, Images, AltText, Attach
To = "<info@yourisp.com>"
CC = Chr$(0)
BCC = Chr$(0)
Subject = "HTML Test"
Message = "@Message.htm"
Images = "image1.gif;image2.gif"
AltText = "@AltText.txt"
Attach = Chr$(0)
Code = seeForwardEmail(0, To, CC, BCC, Subject, Message, Attach)
SENDHTML (C/C++) or HTML example program.
seeShortToByte(Buffer)
Buffer : (P) character buffer
The seeShortToByte function converts the (null terminated) character buffer 'Buffer' from 16-bit Unicode ASCII characters to 8-bit ASCII characters.
The buffer must be null terminated (last character is a hex 00).
This function is only necessary when working with 16-bit Unicode ASCII characters in C# and Delphi 2005.
int Code;
// define 16-bit ASCII string
wchar_t UnicodeString[] = L"MarshallSoft";
// Convert 16-bit ASCII string to 8-bit ASCII
Code = seeShortToByte((LPSTR)UnicodeString);
seeByteToShort
seeSmtpConnect(Chan, Server, From, ReplyTo)
Chan : (I) Channel number.
Server : (P) SMTP server.
From : (P) Your email address in brackets.
ReplyTo : (P) Email address to reply to.
The seeSmtpConnect function establishes a connection with the SMTP server as specified by the 'Server' argument.
Your SMTP server name will typically be named "mail.XXX.com" where XXX is your email address, such as name@XXX.com. Your SMTP server name can also be found in the setup information for your normal email client, such as Eudora or Microsoft Outlook.
The SMTP server name can also be specified in dotted decimal notation. For example, "10.23.231.1".
The 'From' string is required and must be enclosed in "<>" brackets, such as <you@yourisp.com>.
The 'ReplyTo' string is optional and is used for the "Reply-To:" header line. If used, the email address must be enclosed in "<>" brackets.
SEE can not be connected to both the SMTP server and the POP3 server at the same time. Call seeClose to terminate the connection before connecting again.
// connect to SMTP server
char Server[] = "smtp.yourisp.com"
char From[] = "<you@yourisp.com>"
char Reply[] = ""
Code = seeSmtpConnect(0, (LPSTR)Server, (LPSTR)From, (LPSTR)Reply)
BASIC Example
' connect to SMTP server
Server = "smtp.yourisp.com"
From = "<you@yourisp.com>"
Reply = Chr$(0)
Code = seeSmtpConnect(0, Server, From, Reply)
seeClose; MAILER example program.
seeStatistics(Chan, Index)
Chan : (I) Channel number.
Index : (I) Specifies which statistic.
The seeStatistics function is used to return runtime statistics in the SEE DLL. The values of 'Index' are defined in the SEE declaration file (see Section 1.3 "Declaration Files") as follows.
SEE_GET_ATTACH_BYTES_READ : Gets attachment bytes read.
SEE_GET_ATTACH_BYTES_SENT : Gets attachment bytes sent.
SEE_GET_ATTACH_COUNT : Gets attachments received.
SEE_GET_BUFFER_COUNT : Gets bytes in buffer for
seeGetEmailLines.
SEE_GET_BUILD : Gets version build number.
SEE_GET_CONNECT_STATUS : Returns positive number if connected.
SEE_GET_COUNTER : Gets times driver called.
SEE_GET_LAST_RECIPIENT : Gets last recipient ack'd by server.
SEE_GET_MESSAGE_BYTES_READ : Gets message bytes read.
SEE_GET_MESSAGE_BYTES_SENT : Gets message bytes sent.
SEE_GET_MSG_COUNT : Gets emails waiting.
SEE_GET_MSG_SIZE : Gets size of email.
SEE_GET_RESPONSE : Gets last SMTP response code.
SEE_GET_SOCK_ERROR : Gets last socket error.
SEE_GET_SOCKET : Gets socket number.
SEE_GET_TOTAL_BYTES_READ : Gets total bytes read.
SEE_GET_TOTAL_BYTES_SENT : Gets total bytes sent.
SEE_GET_VERSION : Gets the SEE version number.
The number of message bytes sent will usually be larger than your message size because of SMTP protocol overhead.
The number of attachment bytes sent will be at least one-third larger than the actual attachment since every three (3) bytes are encoded as four (4) 7-bit ASCII bytes before being transmitted.
The purpose of "BYTES_READ" and "BYTES_SENT" is to provide the ability to track the transmission progress of large messages and attachments.
SEE_GET_ATTACH_BYTES_READ gets the number of attachment bytes read.
SEE_GET_ATTACH_BYTES_SENT gets the number of attachment bytes sent.
SEE_GET_ATTACH_COUNT gets the number of attachments received.
SEE_GET_BUFFER_COUNT gets the bytes in the buffer after calling seeGetEmailLines.
SEE_GET_BUILD gets the version build number.
SEE_GET_CONNECT_STATUS returns a positive number if currently connected.
SEE_GET_COUNTER gets the number of times that the driver has been called.
SEE_GET_LAST_RECIPIENT gets last recipient (1, 2,...) acknowledged by server.
SEE_GET_MESSAGE_BYTES_READ gets the number of message bytes read.
SEE_GET_MESSAGE_BYTES_SENT gets the number of message bytes sent.
SEE_GET_MSG_COUNT gets the number of emails waiting on the server.
SEE_GET_MSG_SIZE gets the size of an email message.
SEE_GET_RESPONSE gets the last SMTP response code.
SEE_GET_SOCK_ERROR gets the last socket error.
SEE_GET_SOCKET gets the socket number.
SEE_GET_TOTAL_BYTES_READ gets the total number of bytes read.
SEE_GET_TOTAL_BYTES_SENT gets the total number of bytes sent.
SEE_GET_VERSION gets the SEE version number (see SEEVER example).
The seeStatistics function is used with POP3 or IMAP servers only.
' get SEE version
Code = seeStatistics(0, SEE_GET_VERSION);
BASIC Example
' get SEE version
Code = seeStatistics(0, SEE_GET_VERSION)
seeDebug, seeIntegerParam, and seeStringParam; READER, MAILER, BCAST, STATUS examples.
seeStringParam(Chan, ParamName, ParamString)
Chan : (I) Channel number.
ParamName : (I) Parameter.
ParamString: (P) Parameter string.
The seeStringParam is used to set an integer parameter that is passed to the SEE library. The numeric value for each of the integer parameters is defined in the SEE declaration files. Section 1.3 "Declaration Files" provides a list the "Declaration Files".
SEE_ADD_HEADER : Adds header.
SEE_LOG_FILE : Specifies the log filename.
SEE_SET_CONTENT_TYPE : Sets user defined content.
SEE_SET_FROM : Sets "From:" header after connecting.
SEE_SET_HEADER : Sets header line.
SEE_SET_REPLY : Sets the "Reply To" string.
SEE_SET_SECRET : Sets password for SMTP authentication
SEE_SET_TRANSFER_ENCODING : Sets user defined transfer encoding.
SEE_SET_USER : Sets user for SMTP authentication.
SEE_WRITE_BUFFER : Writes internal buffer to disk.
SEE_WRITE_TO_LOG : Write string to LOG file.
SEE_SET_CONTENT_TYPE_PREFIX : Write prefix to Content-Type header.
SEE_SET_FILE_PREFIX : Specifies file prefix character.
SEE_ADD_HEADER is used to add a user specified header line.
SEE_LOG_FILE specifies the name of the LOG file to create. The log file is used to debug a SMTP or POP3 session. Be advised that log files can be quite large. Don't use them unless necessary.
SEE_SET_CONTENT_TYPE is used to specify the content type string to use when enabling quoting with seeIntegerParam(Chan, SEE_QUOTED_PRINTABLE, QUOTED_USER)
SEE_SET_FROM is used to specify the "From:" header line after connecting to the SMTP server.
SEE_SET_HEADER is used to set one or more header lines. Each header line except the last should end with a carriage return line feed pair.
Use SEE_SET_REPLY to change the "Reply-To:" header after connecting to the server, just
before sending an email.
SEE_SET_TRANSFER_ENCODING is used to specify the content transfer encoding to use when enabling quoting with SeeIntegerParam(Chan, SEE_QUOTED_PRINTABLE, QUOTED_USER)
SEE_WRITE_BUFFER is used to write the internal buffer (created by seeGetEmailLines) to disk. See the GETRAW example program.
SEE_WRITE_TO_LOG is used to write text to the LOG file.
SEE_SET_SECRET is used to specify the user's password for ESMTP authentication.
SEE_SET_USER is used to specify the user name for ESMTP authentication.
SEE_SET_CONTENT_TYPE_PREFIX specifies a string that is prefixed to the Content-Type header line that is written to the email output file (POP3 connection) provided that SEE_WRITE_CONTENT_TYPE is set to TRUE.
SEE_SET_FILE_PREFIX is used to specify the character (default value '@') that is used to specify (in the seeSendEmail function) that the message text is a filename rather than the actual text of the email message. Pass an empty string (null character) to disable (message text is never a filename).
' specify SEE log file name
char LogFile[] = "log.txt";
Code = seeStringParam(0, SEE_LOG_FILE, (LPSTR)LogFile)
BASIC Example
' specify SEE log file name
Dim LogFile As String
LogFile = "log.txt"
Code = seeStringParam(0, SEE_LOG_FILE, LogFile)
seeIntegerParam.
seeVerifyFormat(String)
String : (P) Email address to check.
The seeVerifyFormat function is used to test an individual email address for proper formatting. If this function returns 0 or greater, then the email address is properly formatted. But, if this function returns a negative value, then the email address is either badly formatted, or it uses characters (such as '%') that are not normally used as part of an email address.
Note that left and right brackets ('<' and '>') must surround the email address.
TRUE (non zero) if verified.
// verify email address format
char EmailAddr[] = "<you@yourisp.com>";
Code = seeVerifyFormat((LPSTR)EmailAddr);
BASIC Example
' verify email address format
//% Dim EmailAddr As String
EmailAddr = "<you@yourisp.com>"
Code = seeVerifyFormat(EmailAddr)
seeErrorText and seeVerifyUser; VERUSR example program.
seeVerifyUser(Chan, String)
Chan : (I) Channel number.
String : (P) Email address to verify.
The seeVerifyUser function is used to verify an individual email address with the email server which "owns" the email address.
seeVerify will connect to the specified server and request verification of the user. Some SMTP servers may refuse connection of any client not directly connected to them or may refuse all "verify user" requests. Web based email servers such as hotmail.com may refuse all SMTP connections.
Note that you connect to the remote SMTP server rather than the SMTP server that you use to send email.
The seeVerifyUser function is used with SMTP servers only.
TRUE (non zero) if verified by server.
// verify user "billy" on connected POP3 server "yourisp.com"
char User[] = "billy";
Code = seeVerifyUser(0, (LPSTR)User);
BASIC Example
' verify user "billy" on connected POP3 server "yourisp.com"
Dim User As String
User = "billy"
Code = seeVerifyUser(0, User)
seeErrorText and seeDebug; VERUSR example program.
The complete list of SEE error codes follows. These error messages can also be found by calling the seeErrorText function.
0 SEE_CANNOT_COMPLY Cannot comply. Not always an error. 1 SEE_NO_ERROR No error. -1 SEE_EOF End of file (socket has been closed). -4 SEE_IS_BLOCKING Socket is currently blocking. -7 SEE_INVALID_SOCKET Invalid socket -8 SEE_TIMED_OUT Socket timed out awaiting data. -9 SEE_NO_SOCK_ADDR No socket address. -12 SEE_NO_HOST No host name. -14 SEE_ABORTED The DLL has been corrupted. -18 SEE_CANNOT_CREATE_SOCK Cannot create socket. -30 SEE_ALREADY_CONNECTED Already connected to server. -31 SEE_BACK_OVERFLOW Response buffer has overflowed. -32 SEE_BAD_ADDRESS_CHAR Bad character in email address. -34 SEE_CANNOT_ATTACH Cannot access DLL. -35 SEE_CANNOT_OPEN Cannot open file (for read). -36 SEE_CONNECT_ERROR Error attempting to connect. -37 SEE_EMPTY_ADDRESS EMPTY email address. -38 SEE_FROM_NULL_ARG Required 'From:' argument is NULL. -39 SEE_MISSING_AT_CHAR Missing '@' character in email address. -40 SEE_MISSING_FROM Missing 'From:' email address. -41 SEE_MISSING_LEFT Missing '<' delimiter in email address. -43 SEE_MISSING_RIGHT Missing '>' terminating email address. -44 SEE_NOT_CONNECTED Not connected to server. -45 SEE_NO_RECIPIENTS Must have at least one recipient. -46 SEE_NO_SERVER Cannot find SMTP/POP3/IMAP server. -47 SEE_NULL_POINTER Unexpected NULL pointer. -49 SEE_SMTP_ERROR SMTP returned error. -50 SEE_EMAIL_NULL_ARG SMTP/POP3/IMAP server not specified. -51 SEE_SOCK_READ_ERROR Socket read error. -52 SEE_SOCK_WRITE_ERROR Socket write error. -53 SEE_TOO_MANY_AT_CHARS Too many '@' symbols in email address. -55 SEE_CANNOT_ALLOC Cannot allocate memory. -56 SEE_NOT_SERVER, Illegal chars in server name. -57 SEE_NO_APOP_TIMESTAMP POP3 server did not provide a timestamp. -58 SEE_SMTP_ONLY Must be connected to SMTP server. -59 SEE_POP3_ONLY Must be connected to POP3 server. -60 SEE_OBSOLETE_PARAMETER Parameter is obsolete. -61 SEE_USER_NULL_ARG Expected USER name not specified. -62 SEE_PASS_NULL_ARG Required POP3 password argument missing. -63 SEE_POP3_ERROR Error returned by POP3 server. -64 SEE_MSG_NBR_RANGE Message number out of range. -65 SEE_FILENAME_NULL_ARG Required filename is missing. -66 SEE_EMAIL_PATH_NULL_ARG Required file path is missing. -67 SEE_CANNOT_CREATE Cannot create file. -68 SEE_BUFFER_NULL_ARG Required buffer is missing. -69 SEE_BUFFER_SIZE_ARG Buffer size argument is not positive. -70 SEE_ATTACH_PATH_NULL_ARG Attachment argument is missing. -71 SEE_NOT_ATTACHED Must call seeAttach first. -72 SEE_ALREADY_ATTACHED seeAttach already called. -73 SEE_CHAN_OUT_OF_RANGE Channel number out of range. -74 SEE_BAD_KEY_CODE Bad keycode (2nd argument in seeAttach) -75 SEE_NO_SUCH_FILE No such file. -76 SEE_PATH_NOT_ALLOWED Filename only - path not allowed. -77 SEE_NO_SUCH_PATH No such path. -78 SEE_IMAP_ERROR, IMAP returned error. -79 SEE_IMAP_ONLY, IMAP function ONLY. -80 SEE_POP3_IMAP_ONLY, POP3 or IMAP function ONLY. -81 SEE_IMAP_FLAG_ERROR, IMAP flag error. -82 SEE_IMAP_SEARCH_ERROR, IMAP search error. -98 SEE_EXPIRED Evaluation version expired. -99 SEE_INTERNAL_ERROR Internal SEE error.