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-domain
   8 { $var-description "The name of the machine that is sending the email.  This variable will be filled in by the " { $link host-name } " word if not set by the user." } ;
   9
  10 HELP: smtp-server
  11 { $var-description "Holds an " { $link inet } " object with the address of an SMTP server." } ;
  12
  13 HELP: smtp-tls?
  14 { $var-description "If set to true, secure socket communication will be established after connecting to the SMTP server. The server must support the " { $snippet "STARTTLS" } " command. Off by default." } ;
  15
  16 HELP: smtp-read-timeout
  17 { $var-description "Holds a " { $link duration } " object that specifies how long to wait for a response from the SMTP server." } ;
  18
  19 HELP: smtp-auth
  20 { $var-description "Holds either " { $link no-auth } " or an instance of " { $link plain-auth } ", specifying how to authenticate with the SMTP server. Set to " { $link no-auth } " by default." } ;
  21
  22 HELP: no-auth
  23 { $class-description "If the " { $link smtp-auth } " variable is set to this value, no authentication will be performed." } ;
  24
  25 HELP: plain-auth
  26 { $class-description "If the " { $link smtp-auth } " variable 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." } ;
  27
  28 HELP: <plain-auth>
  29 { $values { "username" string } { "password" string } { "plain-auth" plain-auth } }
  30 { $description "Creates a new " { $link plain-auth } " instance." } ;
  31
  32 HELP: with-smtp-connection
  33 { $values { "quot" quotation } }
  34 { $description "Connects to an SMTP server stored in " { $link smtp-server } " and calls the quotation." }
  35 { $notes "This word is used to implement " { $link send-email } " and there is probably no reason to call it directly." } ;
  36
  37 HELP: email
  38 { $class-description "An e-mail. E-mails have the following slots:"
  39     { $table
  40         { { $slot "from" } "The sender of the e-mail. An e-mail address." }
  41         { { $slot "to" } "The recipients of the e-mail. A sequence of e-mail addresses." }
  42         { { $slot "cc" } "Carbon-copy. A sequence of e-mail addresses." }
  43         { { $slot "bcc" } "Blind carbon-copy. A sequence of e-mail addresses." }
  44         { { $slot "subject" } "The subject of the e-mail. A string." }
  45         { { $slot "content-type" } { "The MIME type of the body. A string, default is " { $snippet "text/plain" } "." } }
  46         { { $slot "encoding" } { "An encoding to send the body as. Default is " { $link utf8 } "." } }
  47         { { $slot "body" } " The body of the e-mail. A string." }
  48     }
  49 "The " { $slot "from" } " and " { $slot "to" } " slots are required; the rest are optional."
  50 $nl
  51 "An e-mail address is a string in one of the following two formats:"
  52 { $list
  53     { $snippet "joe@groff.com" }
  54     { $snippet "Joe Groff <joe@groff.com>" }
  55 } } ;
  56
  57 HELP: <email>
  58 { $values { "email" email } }
  59 { $description "Creates an empty " { $link email } " object." } ;
  60
  61 HELP: send-email
  62 { $values { "email" email } }
  63 { $description "Sends an e-mail." }
  64 { $examples
  65     { $code "USING: accessors smtp ;"
  66     "<email>"
  67     "    \"groucho@marx.bros\" >>from"
  68     "    { \"chico@marx.bros\" \"harpo@marx.bros\" } >>to"
  69     "    { \"gummo@marx.bros\" } >>cc"
  70     "    { \"zeppo@marx.bros\" } >>bcc"
  71     "    \"Pickup line\" >>subject"
  72     "    \"If I said you had a beautiful body, would you hold it against me?\" >>body"
  73     "send-email"
  74     ""
  75     }
  76 } ;
  77
  78 ARTICLE: "smtp-gmail" "Setting up SMTP with gmail"
  79 "If you plan to send all email from the same address, then setting variables 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
  80 "Several variables need to be set for sending outgoing mail through gmail. 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."
  81 { $code
  82     "USING: smtp namespaces io.sockets ;"
  83     ""
  84     "\"my.gmail.address@gmail.com\" \"secret-password\" <plain-auth> smtp-auth set-global"
  85     ""
  86     "\"smtp.gmail.com\" 587 <inet> smtp-server set-global"
  87     ""
  88     "t smtp-tls? set-global"
  89 } ;
  90
  91
  92 ARTICLE: "smtp" "SMTP client library"
  93 "The " { $vocab-link "smtp" } " vocabulary sends e-mail via an SMTP server."
  94 $nl
  95 "This library is configured by a set of dynamically-scoped variables:"
  96 { $subsections
  97     smtp-server
  98     smtp-tls?
  99     smtp-read-timeout
 100     smtp-domain
 101     smtp-auth
 102 }
 103 "The latter is set to an instance of one of the following:"
 104 { $subsections
 105     no-auth
 106     plain-auth
 107 }
 108 "Constructing an e-mail:"
 109 { $subsections
 110     email
 111     <email>
 112 }
 113 "Sending an email:"
 114 { $subsections send-email }
 115 "More topics:"
 116 { $subsections "smtp-gmail" } ;
 117
 118 ABOUT: "smtp"