------------
$mail_agent:send_message(from,recipients,headers,body)
from: sender of the message
(this must be you or something you own; otherwise => E_PERM)
recipients: object or list of objects (must all be players or
$mail_recipient descendants)
headers: either a string (contents of the Subject: line)
or a list {subject,replytos} replytos is a list
of objects designated to receive replies.
Use {"",replytos} to have a Reply-to: without a Subject:
This is the canonical way to send a mail message from a program.
This calls $mail_agent:make_message to format the arguments into an actual message (see `help mail-format') and then $mail_agent:raw_send to do the actual sending which goes as follows:
(1) Call :mail_forward on all recipients add any new recipients thus obtained to final recipient list, keep calling mail:forward on the new recipients until we obtain no additional recipients. If one of the initial recipients is invalid, is not a player or $mail_recipient, or has its mail_forward return a string error, then we print the error message and abort at this point with no mail being sent. If one of the later recipients bombs similarly, error messages are printed, but in this case mail still goes out to the other recipients.
(2) Call :mail_notify on all recipients encountered in stage (1) to get a list of objects to notify.
(3) All final recipients receive the message (see `help receive-mail')
(4) All notifications are delivered (using :notify_mail())
We return {0, @failed_recipients} if we bombed out at step 1.
Otherwise return {1, @actual_rcpts} indicating what mail was sent.