basis/smtp/smtp-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: accessors kernel quotations help.syntax help.markup
   4 io.sockets strings calendar io.encodings.utf8 ;
   5 IN: smtp
   6
   7 HELP: smtp-config
   8 { $class-description "An SMTP configuration object, with the following slots:"
   9     { $table
  10         { { $slot "domain" } { "Name of the machine sending the email, or " { $link host-name } " if empty." } }
  11         { { $slot "server" } { "An " { $link <inet> } " of the SMTP server." } }
  12         { { $slot "tls?" } { "Secure socket after connecting to server, server must support " { $snippet "STARTTLS" } } }
  13         { { $slot "read-timeout" } { "Length of time after which we give up waiting for a response." } }
  14         { { $slot "auth" } { "Either " { $link no-auth } " or an instance of " { $link plain-auth } } }
  15     }
  16 } ;
  17
  18 HELP: default-smtp-config
  19 { $values { "smtp-config" smtp-config } }
  20 { $description "Creates a new " { $link smtp-config } " with defaults of a one minute " { $snippet "read-timeout" } ", " { $link no-auth } " for authentication, and " { $snippet "localhost" } " port " { $snippet "25" } " as the server." } ;
  21
  22 { smtp-config default-smtp-config } related-words
  23
  24 HELP: no-auth
  25 { $class-description "If the " { $snippet "auth" } " slot is set to this value, no authentication will be performed." } ;
  26
  27 HELP: plain-auth
  28 { $class-description "If the " { $snippet "auth" } " slot is set to this value, plain authentication will be performed, with the username and password stored in the " { $slot "username" } " and " { $slot "password" } " slots of the tuple sent to the server as plain-text." } ;
  29
  30 HELP: <plain-auth>
  31 { $values { "username" string } { "password" string } { "plain-auth" plain-auth } }
  32 { $description "Creates a new " { $link plain-auth } " instance." } ;
  33
  34 HELP: with-smtp-config
  35 { $values { "quot" quotation } }
  36 { $description "Connects to an SMTP server using credentials and settings stored in " { $link smtp-config } " and calls the " { $link with-smtp-connection } " combinator." }
  37 { $notes "This word is used to implement " { $link send-email } " and there is probably no reason to call it directly." } ;
  38
  39 HELP: with-smtp-connection
  40 { $values { "quot" quotation } }
  41 { $description "Connects to an SMTP server using credentials and settings stored in " { $link smtp-config } " and calls the quotation." }
  42 { $notes "This word is used to implement " { $link send-email } " and there is probably no reason to call it directly." } ;
  43
  44 HELP: email
  45 { $class-description "An e-mail. E-mails have the following slots:"
  46     { $table
  47         { { $slot "from" } "The sender of the e-mail. An e-mail address." }
  48         { { $slot "to" } "The recipients of the e-mail. A sequence of e-mail addresses." }
  49         { { $slot "cc" } "Carbon-copy. A sequence of e-mail addresses." }
  50         { { $slot "bcc" } "Blind carbon-copy. A sequence of e-mail addresses." }
  51         { { $slot "subject" } "The subject of the e-mail. A string." }
  52         { { $slot "content-type" } { "The MIME type of the body. A string, default is " { $snippet "text/plain" } "." } }
  53         { { $slot "encoding" } { "An encoding to send the body as. Default is " { $link utf8 } "." } }
  54         { { $slot "body" } " The body of the e-mail. A string." }
  55     }
  56 "The " { $slot "from" } " and " { $slot "to" } " slots are required; the rest are optional."
  57 $nl
  58 "An e-mail address is a string in one of the following two formats:"
  59 { $list
  60     { $snippet "joe@groff.com" }
  61     { $snippet "Joe Groff <joe@groff.com>" }
  62 } } ;
  63
  64 HELP: <email>
  65 { $values { "email" email } }
  66 { $description "Creates an empty " { $link email } " object." } ;
  67
  68 HELP: send-email
  69 { $values { "email" email } }
  70 { $description "Sends an e-mail." }
  71 { $examples
  72     { $code "USING: accessors smtp ;"
  73     "<email>"
  74     "    \"groucho@marx.bros\" >>from"
  75     "    { \"chico@marx.bros\" \"harpo@marx.bros\" } >>to"
  76     "    { \"gummo@marx.bros\" } >>cc"
  77     "    { \"zeppo@marx.bros\" } >>bcc"
  78     "    \"Pickup line\" >>subject"
  79     "    \"If I said you had a beautiful body, would you hold it against me?\" >>body"
  80     "send-email"
  81     ""
  82     }
  83 } ;
  84
  85 ARTICLE: "smtp-gmail" "Setting up SMTP with gmail"
  86 "If you plan to send all email from the same address, then setting the config variable in the global namespace is the best option. The code example below does this approach and is meant to go in your " { $link ".factor-boot-rc" } "." $nl
  87 "First, we set the login and password to a " { $link <plain-auth> } " tuple with our login. Next, we set the gmail server address with an " { $link <inet> } " object. Finally, we tell the SMTP library to use a secure connection."
  88 { $notes "Gmail requires the use of application-specific passwords when accessed from anywhere but their website. Visit " { $url "https://support.google.com/accounts/answer/185833?hl=en" } " to create a password for use with Factor." }
  89 { $code
  90     "USING: smtp namespaces io.sockets ;"
  91     ""
  92     """default-smtp-config
  93     "smtp.gmail.com" 587 <inet> >>server
  94     t >>tls?
  95     "my.gmail.address@gmail.com" "qwertyuiasdfghjk" <plain-auth> >>auth
  96     \\ smtp-config set-global"""
  97 } ;
  98
  99
 100 ARTICLE: "smtp" "SMTP client library"
 101 "The " { $vocab-link "smtp" } " vocabulary sends e-mail via an SMTP server."
 102 $nl
 103 "This library is configured by a globally scoped config tuple:"
 104 { $subsections
 105     smtp-config
 106     default-smtp-config
 107 }
 108 "The auth slot is set to an instance of one of the following:"
 109 { $subsections
 110     no-auth
 111     plain-auth
 112 }
 113 "Constructing an e-mail:"
 114 { $subsections
 115     email
 116     <email>
 117 }
 118 "Sending an email:"
 119 { $subsections send-email }
 120 "More topics:"
 121 { $subsections "smtp-gmail" } ;
 122
 123 ABOUT: "smtp"