email Client API

1. email Client API What does it do? How do you make it work? 1-1

2. Email Client API WHAT IT IS: • Gives applications the ability to customize an e-mail client according to the application’s needs WHAT IT DOES: • Allows connection to a POP3 server and allows the application to take control when messages are received from the server • Allows connection to an SMTP server to be able to send e-mails 1-2

3. email Client API Functions #include <mailcapi.h> • MCCreate Function • A new email client is created by calling MCCreate: • Parameters specify port and IP addresses of POP3 and SMTP server. • Returns handle if successful, otherwise 0. • MCClose Function • Closes out the email client. • Closes associated sockets and reclaims memory. 1-3

4. POP3-oriented API Functions • MCReadLogin – log into POP3 server • MCReadLogout – log out of server • MCDele – delete a message from the server (DELE request) • MC_get_msg_count – get number of my messages on server • MCStat – get number of messages on server (STAT request) • MCList – request a list of messages from the server, or length of one message (LIST request) • MCRegisterLIST – register a callback function for data returned by server after a LIST request • MCNoop – sends the server NOOP • MCRetr – retrieve a specific message (by number – RETR request) • MCRegisterRETR – register callback function for data returned by server after RETR request 1-4

5. POP3-oriented API Functions (2) • MCRetrWithAttachments – retrieve a message by number and ≤ 3 attachments • MCRegisterRETRWithAttachments – register a user callback to process data retrieved with attachments • MCRset – undeletes all my messages (RSET request) All POP3-oriented functions return 0 for success and –1 for failure. 1-5

6. SMTP-Oriented API Functions • MCSendSimpleMail – send an ASCII mail message to the SMTP server • MCSendSimpleMailWithDomain – send an ASCII mail message preceded by HELO with domain name • MCSendMailWithAttachments – sends an email with ≤ 3 attachments All SMTP-oriented functions return 0 for success and –1 for failure. 1-6

7. Email APIs • Support non-blocking feature • Allow to send multiple mails simultaneously (No need to wait for mail to be completely sent before sending next mail) • User callback function is needed for file attachment (to send and receive data) 1-7

8. Email APIs • Header can be included in listing mail (slash ‘\’ is used to separate each header field) and retrieving mail • Old v5.1 email APIs become deprecated (except MCCreate and MCClose) • Should use these new v6.0 email APIs 1-8

9. Email APIS • int MCRegisterLogin(unsigned long handle, mc_client_callback_fn callback, unsigned long user_data) • int MCUserLogin(unsigned long handle, char * user, char * pass, int wait) • int MCUserLogout(unsigned long handle, int wait) • int MCRegisterSummary(unsigned long handle, mc_list_callback_fn callback, unsigned long user_data) • int MCSummary(unsigned long handle, int wait) • int MCRegisterListMail(unsigned long handle, mc_list_callback_fn callback, unsigned long user_data) • int MCListMail(unsigned long handle, int start_id, int end_id, char * buffer, int bufsize, BOOLEAN includeHeader, int wait) 1-9

10. Email APIs • int MCSetDomain(unsigned long handle, char * domain) • int MCSetSignature(unsigned long handle, char * signature) • int MCNewMail(unsigned long handle, unsigned long * mail_id) • int MCCancelMail(unsigned long handle, unsigned long mail_id) • int MCAdd_ToAddr(unsigned long handle, unsigned long mail_id, char * to_addr[]) • int MCAdd_CopyAddr(unsigned long handle, unsigned long mail_id, char * cc_addr[]) • int MCRegisterSend_File(unsigned long handle, unsigned long mail_id, mc_file_callback_fn callback, unsigned long user_data) • The callback function will be callback for each attachment. • int MCAdd_Attachment(unsigned long handle, unsigned long mail_id, char *filename[], int file_type, unsigned int access_code) • Filename will be passed to the mc_file_callback_fn callback function • int MCRegisterSend(unsigned long handle, unsigned long mail_id, send_mail_callback_fn callback, unsigned long user_data) • int MCSendMail(unsigned long handle, unsigned long mail_id, char * from_addr, char * to_addr, char * subject, char * bodybuf, int body_type, int wait) 1-10

11. Email APIs • int MCRegisterRetr_File(unsigned long handle, mc_file_callback_fn callback, unsigned long user_data) • Callback function will be indicated either the data is body message, or file attachment (“BODY-MESSAGE” or “FILE-ATTACHMENT”) • Callback function will be called continuously until it’s given a NULL data pointer& NULL size data pointer. It indicates end-of-file. • int MCRegisterRetr(unsigned long handle, retr_mail_callback_fn callback, unsigned long user_data) • int MCRetrMail(unsigned long handle, int msgId, char * readBuffer, unsigned long * readLength, BOOLEAN includeHeader, int wait) • If readBuffer is NULL, body message will be treated as a file attachment. It means the callback function from MCRegisterRetr_File will be called with “BODY-MESSAGE”. • If readBuffer is not NULL, it will contain the body message. 1-11

12. Email APIs • int MCRegisterDel(unsigned long handle, mc_client_callback_fn callback, unsigned long user_data) • int MCDeleteMail(unsigned long handle, int msgId, int wait) • int MCUndeleteAll(unsigned long handle, int wait) 1-12

13. Email (File System) • Send mail with file attachment from the file system. • Retrieve and save mail and file attachment in the file system. 1-13

14. Email (File System) • MCAdd_FileAttachment • Attach files in the file system 1-14

15. Email (File System) • MCRetrMail_Save • Save the mail message and file attachment in the file system. • Must not wait for mail to be saved if this function is initiated in Web Pages. • MCRetrMail_Read • Read mail message • Copy the mail message in the user’s buffer • Save any file attachment in the file system • Must not wait if this function is initiated in Web Pages 1-15