tfSmtpUserSendRecipientInfo

Table of Contents >> Optional Protocols >> SMTP

#include <trsocket.h>

int tfSmtpUserSendRecipientInfo	(
	ttSmtpClientHandle smtpClientHandle,
	char * recipientNamePtr,
	char * recipientAddrPtr,
	char * recipientType
	);

Function Description

Send the recipient's name and address. The recipientNamePtr parameter can be NULL. tfSmtpUserSendRecipientInfo() could be called multiple times to send the same message to multiple recipients.

This API needs to be called in the right state, otherwise, TM_EPERM will be returned. If the session is blocking, it should be called after tfSmtpUserSendSenderInfo() or tfSmtpUserSendRecipientInfo() has returned TM_ENOERROR and no other API has been called. If the session is non-blocking, it should be called when the event TM_SMTP_EVENT_SENDER_ACK is received.

In non-blocking mode, a successful reply from the server will generate a TM_SMTP_EVENT_RECIPIENT_ACK event to your SMTP event callback function. An unsuccessful reply from the server results in a TM_SMTP_EVENT_SERVER_ERROR or TM_SMTP_EVENT_SERVER_RETRY event. If the client times out (see tfSmtpUserNewSession()) waiting for the server to respond, a TM_SMTP_EVENT_TIMEOUT event is reported.

Each recipient you supply will be sent to the server in a RCPT command and included in the TO: or CC: message headers (ahead of the message body). Recipient type TM_SMTP_RECIPIENT_TYPE_BCC is an exception -- it is sent in a separate RCPT command for message routing but will NOT appear in the message headers, as is the nature of a blind carbon copy.

Recipient rejection by the server

The tfSmtpUserSendRecipientInfo() state handling is unique in that a server rejection (e.g. 4xx or 5xx response code) does not require you to reset and restart the session from scratch. Servers returning such error codes should remain in the same state, ready for another RCPT command.

So, if you are supplying a long list of recipients that may include bad email addresses, you can safely ignore (and perhaps log) tfSmtpUserSendRecipientInfo() calls that result in TM_ESERVERPERM or TM_ESERVERTEMP return codes, or that generate TM_SMTP_EVENT_SERVER_ERROR or TM_SMTP_EVENT_SERVER_RETRY callback events.

Note that the server must accept at least one of your recipients to send a message. Also, recipient types TM_SMTP_RECIPIENT_TYPE_TO and TM_SMTP_RECIPIENT_TYPE_CC that have been rejected will still appear in the TO: or CC: header fields of the message.

Parameters

• smtpClientHandle

  The SMTP client session handle as returned by tfSmtpUserNewSession().

• recipientNamePtr

  A pointer to a string that holds the sender's name, e.g. "Bob Smith". This pointer can be NULL.

• recipientAddrPtr

  A pointer to a string that holds the sender's address, e.g. "bob@foo.com".

• recipientType

  One of the following:

• TM_SMTP_RECIPIENT_TYPE_TO
• TM_SMTP_RECIPIENT_TYPE_CC
• TM_SMTP_RECIPIENT_TYPE_BCC.

Returns

• TM_ENOERROR

  Success.

• TM_EINVAL

  Invalid SMTP client session handle or other input parameter.

• TM_EPERM

  The SMTP session is not connected.

• TM_ENOBUFS

  Insufficient resources to complete the operation.

• TM_EINPROGRESS

  The operation is in progress (non-blocking mode only). Call tfSmtpUserExecute() periodically until complete.

• TM_ESERVERPERM

  The server rejected the command with a permanent negative completion reply (5xx status code, see RFC 5321). The server and client state remain unchanged; the list of accepted recipients remains intact (i.e. all previous calls to tfSmtpUserSendRecipientInfo() during this session that were successful).

• TM_ESERVERTEMP

  The server rejected the command with a transient negative completion reply (4xx status code, see RFC 5321). The server and client state remain unchanged; the list of accepted recipients remains intact (i.e. all previous calls to tfSmtpUserSendRecipientInfo() during this session that were successful).

• TM_ESERVERSYNC

  The client and server are out of sync and cannot proceed; the session has been disconnected. This can occur, for example, if the server unexpectedly sends an intermediate reply (3xx status code, see RFC 5321) to a command that requires a completion code.

• TM_ETIMEDOUT

  The Treck SMTP client timed out and disconnected while waiting for a reply from the server. The time limit is set via tfSmtpUserNewSession().

• TM_ESHUTDOWN

  The server closed the connection, unexpectedly.

• other errors

  Some socket errors returned from the SMTP client's calls to send() and recv() are passed directly to the caller.

Table of Contents >> Optional Protocols >> SMTP