mail::account::getSendFolder
Prev | mail::account Native API reference | Next

## Name

mail::account::getSendFolder — Create a folder object for sending mail

## Synopsis

#include <libmail/mail.H>
class myCallback : public mail::callback {
public:
void success(std::string msg);
void fail(std::string msg);
};

#include <libmail/smtpinfo.H>
#include <libmail/addmessage.H>
mail::account *account;
mail::smtpInfo info;
info.sender="nobody@example.com";
info.recipients.push_back("recipient@example.com");

`mail::folder *folder=account->getSendFolder(` | const mail::smtpInfo & | info,
| const mail::folder * | saveFolder,
| std::string | errmsg`)`;

myCallback sendCallback;
mail::addMessage *addMessage= folder->addMessage(sendCallback);
addMessage->saveMessageContents(std::string messageText);
addMessage->go();

## USAGE

This function creates a special folder object: copying a message to this folder will E-mail it to the designated recipient list. The mail::account object must be an account that's capable of creating this kind of a folder (such as `smtp` accounts created by mail::account::open(3x)). The message may be manually added to the folder with mail::folder::addmessage(3x), or by copying a message from another folder using mail::folder::copyMessagesTo(3x).

### Note

Multiple messages may be copied to this mail::folder. Each messages is E-mail separately, to all recipients. Excersize caution to prevent an accidental request to copy an entire folder, with thousand messages, to a thousand recipients.

### `saveFolder`

`saveFolder`, if not `NULL`, specifies that a copy of the message should also be saved in this folder. If this mail account uses the experimental SMAP protocol, a single copy of the message will be transmitted to the `SMAP` server, which will file the message in the folder, and send it to the designated recipients. Otherwise the message is manually saved to this folder using mail::folder::addMessage(3x), or mail::ACCOUNT::addMessage(3x).

### The mail::smtpInfo object

`info` specifies the following parameters which are used to deliver the message:

    class mail::smtpInfo {
    public:
            std::string sender;

            std::vector<std::string> recipients;

            std::map<std::string, std::string> options;
    } ;

`sender` specifies the sender's E-mail address, in the form of "`user`@`domain`". `recipients` is a list of recipients' E-mail addresses. At least one recipient must be specified.

`options` specifies additional parameters for sending E-mail, initialized as follows:

options.insert(make_pair("novalidate-cert", "1"))

  See mail::account::open(3x)) for a description of this option.

options.insert(make_pair("cram", "1"))

  See mail::account::open(3x)) for a description of this option.

options.insert(make_pair("DSN", "`list`"))

  Request a delivery status notification. `list` is a comma-separated list of the following keywords: "`never`" - do not request any receipts, not even non-delivery notices; "`success`" - request a delivery confirmation receipt; "`fail`" - request a non-delivery notice; "`delay`" - request a delayed delivery notice.

  ### Note

  An error will be reported if the mail server does not implement delivery status notifications.

options.insert(make_pair("RET", "hdrs"))

  Request that the delivery status notification should not include the entire original message, only its headers.

options.insert(make_pair("RET", "full"))

  Request that the delivery status notifications should include the entire original message.

options.insert(make_pair("NOPIPELINING", "1"))

  Do not use the `PIPELINING` `SMTP` extension even if the mail server claims to support it (workaround for buggy firewalls).

options.insert(make_pair("VERP", "1"))

  Use the `VERP` mailing list extension. If the `sender` address is "`sender`@`senddomain`", then a delivery status notification for "`recipient`@`recipientdomain`" will be sent to "`sender`-`recipient`=`recipientdomain`@`senddomain`" (with certain additional details). This option is currently implemented only by the Courier mail server.

options.insert(make_pair("SECURITY", "STARTTLS"))

  The message must be sent via TLS, and the recipient's server must present a certificate signed by a trusted, private, certificate authority. This option is currently implemented only by the Courier mail server.

  ### Note

  This is not the standard `STARTTLS` `ESMTP` extension. `STARTTLS` is always used automatically, if it's supported by the mail server.

## RETURN CODES AND CALLBACKS

`mail::account::getSendFolder` returns NULL if this mail::account object is not capable of sending mail. `errmsg` is initialized with an appropriate error message.

## SEE ALSO

mail::account::open(3x).

Prev | Up | Next
mail::account::getFolderKeywordInfo | Home | ToC | mail::account::hasCapability