mail::ACCOUNT::send
Prev | mail::ACCOUNT Synchronous API reference | Next

## Name

mail::ACCOUNT::send — Send a message

## Synopsis

#include <libmail/sync.H>
#include <libmail/smtpinfo.H>
mail::ACCOUNT *mail;
class myAddMessagePull : public mail::addMessagePull {
public:
std::string getMessageContents();
};
myAddMessagePull message;
mail::smtpInfo info;
info.sender="nobody@example.com";
info.recipients.push_back("recipient@example.com");

`bool ok=mail->send(` |  | info,
| const mail::folder * | saveFolder,
|  | message`)`;

std::string errmsg=mail->getErrmsg();

## USAGE

This method sends a message via SMTP. The application should create a mail::ACCOUNT object, and invoke mail::ACCOUNT::login(3x) specifying a `smtp:`, `smtps:` or `sendmail:` `url`. The resulting mail::ACCOUNT's `send` method will be able to deliver the `message`.

`message`'s `getMessageContents` specifies the contents of the message, which should be a valid, MIME-formatted message. `getMessageContents` does not have to return the entire contents of the message at once. `addMessage` calls `getMessageContents` repeatedly. `getMessageContents` should return the next portion of the message with each call. `getMessageContents` should return an empty string, after providing the entire message contents are provided. `getMessageContents` will be called repeatedly until it returns an empty string.

### `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

This method returns `true` if it succeeds, or `false` if it fails. If the method fails, use `mail::ACCOUNT::getErrmsg()` to read a brief description of the error.

## SEE ALSO

mail::ACCOUNT::login(3x).

Prev | Up | Next
mail::ACCOUNT::searchMessages | Home | ToC | mail::ACCOUNT::setRights