There are many applications of WebWidgets where it is useful to send emails. For that reason, WWIO provides a simple technique you can use to do this. However, WWIO is not a platform for sending large-scale email blasts like MailChimp or ConstantContact, it is designed for highly targeted and useful messaging to a small set of recipients.

Important note: the API for sending emails through WWIO is contained in the core API, but the implementation is not. If you are running the open-source version on your own machines, you will need to build a implement a special mail interface to connect the core data structures to the mail system on your network.

To begin using the Email system, go to the MailRunner page in the Admin Console. This page has an option to create the mailbox Widget DB for you. The resulting DB will have exactly one table named outgoing, with the following definition:

CREATE TABLE outgoing (id int, sent_at_utc varchar(19), send_target_utc varchar(19), recipient varchar(100), 
 subject varchar(100), email_content varchar(1000), is_text smallint, primary key(id))

The meaning of these fields are as follows:

• sent_at_utc This field is populated automatically when the system sends the mail, with the sent-at timestamp. Important: User code should enter an empty string for this field. If you enter any other data here, the system will not send your mail.
• send_target_utc This is the target time when you want your mail to be sent. If you want it to be sent ASAP, just enter the current UTC timestamp.
• recipient Recipient's email address.
• subject Email subject line.
• email_content Body of the email message. This can be formatted as text or as HTML.
• is_text 0 or 1 flag indicating whether the message is in plain-text format or HTML (use 1 for plain text).

To send emails using WWIO, simply create records in the outgoing table. There is a sender daemon running on WWIO that will pick up the records and send them for you. The daemon runs every couple of minutes. When it finds a mailbox with emails that are ready to send, it picks a small number of them and sends them. This daemon also updates the sent_at_utc to indicate that the mail has been sent. You can see a log of your outgoing emails on the MailRunner console.

Email Rules

Due to the sensitive nature of email sending, there are a variety of special rules that govern how you use your mailbox Widget. These rules are to prevent abuse of the email system.

• Users cannot upload mailbox Widget DBs, only download them.
• The mailbox cannot have any other tables.
• Records with a non-empty sent_at_utc cannot be updated, only deleted. This is to ensure that the data in the DB matches what was actually sent.
• There is a sending limit of 20 emails per day.
• The email_content of your record must contain the string WWIO_FOOTER_HERE. The sender removes this tag and inserts a link to an email-control page on the server, that the recipient can use to opt-out of further emails.

Example Code

Here is an example of building a mail record. The idea here is to schedule lunch meetings with a list of contacts.

        // Get a name and email address from elsewhere
        const contactname = getContactName();
        const contactaddress = getContactAddress();

        // This will be something like "Friday, Oct 15th".
        const openslot = getOpenLunchSlot();

        const content = `
        Hey ${contactname},

        I've got an empty lunch slot on my calendar this ${openslot}. Can you make it?

        thanks,
        Dan

        WWIO_FOOTER_HERE
        `;

        // Get current UTC time for ASAP sending
        const sendtarget = exactMomentNow().asIsoLongBasic("UTC");

        const newrec = {
            "send_target_utc" : sendtarget,
            "sent_at_utc" : "",
            "recipient" : contactaddress,
            "subject" : "Let's Have Lunch"
            "is_text" : 0,
            "email_content" : content
        };

        const mailitem = W.buildItem("outgoing", newrec);
        mailitem.syncItem();