{"size": 5413, "ext": "scrbl", "max_stars_repo_path": "scribblings/smtp.scrbl", "max_stars_repo_name": "eafit-201620030010/smtp", "max_stars_repo_stars_event_min_datetime": null, "max_stars_repo_stars_event_max_datetime": null, "max_issues_repo_path": "scribblings/smtp.scrbl", "max_issues_repo_name": "eafit-201620030010/smtp", "max_issues_repo_issues_event_min_datetime": null, "max_issues_repo_issues_event_max_datetime": null, "max_forks_repo_path": "scribblings/smtp.scrbl", "max_forks_repo_name": "eafit-201620030010/smtp", "max_forks_repo_forks_event_min_datetime": null, "max_forks_repo_forks_event_max_datetime": null}
{"max_stars_count": null, "max_issues_count": null, "max_forks_count": null, "avg_line_length": 26.2766990291, "max_line_length": 120, "alphanum_fraction": 0.6041012378}
#lang scribble/manual
@require[@for-label[smtp
                    racket/base]]

@title{smtp}
@author[(author+email "Yanying Wang" "yanyingwang1@gmail.com")]


@defmodule[smtp]

A practical library to send emails using SMTP protocol, @hyperlink["https://github.com/yanyingwang/smtp" "Source Code"].

@[table-of-contents]




@section{Example}


1. Sending email with authenticattion by parameters:
@codeblock[#:keep-lang-line? #f]|{
(current-smtp-host "smtp.qq.com")
(current-smtp-port 587)
(current-smtp-username "sender1")
(current-smtp-password "password1")
(current-smtp-debug-mode #t)

(define a-mail
  (make-mail "a test email"
             "this is the message body of the test mail"
             #:from "sender1@qq.com"
             #:to '("recipient1@qq.com")
             #:cc '("recipient2@qq.com")
             #:bcc '("recipient3@qq.com" "recipient4@qq.com")
             #:attached-files '("~/abc.txt")))

(define b-mail
  (make-mail "a test1 email"
             "this is the message body of the test1 mail"
             #:from "sender1@qq.com"
             #:to '("recipient1@qq.com")))

(define c-mail
  (make-mail "a test2 email"
             "this is the message body of the test2 mail"
             #:from "sender2@qq.com"
             #:to '("recipient1@qq.com")))

(send-smtp-mail a-mail)
(send-smtp-mail b-mail)
}|


2. Sending and auth email with resetting some parameters dynamically:
(parameterize ([current-smtp-username "sender2"]
               [current-smtp-password "password2"])
  (send-smtp-mail c-mail))


3. Sending and auth email through function arguments:
@codeblock[#:keep-lang-line? #f]|{
(send-smtp-mail c-mail
                #:host "smtp.qq.com"
                #:port 25
                #:username "sender2"
                #:password "password2")

4. Sending html message:
(current-smtp-body-content-type "text/html")
(define c-mail
  (make-mail "a test of html email"
             "<html><body> <h1>a test of html email</h1> <p>hello world!</p>"
             #:from "sender2@qq.com"
             #:to '("recipient1@qq.com")))

(send-smtp-mail c-mail
                #:host "smtp.qq.com"
                #:port 25
                #:username "sender2"
                #:password "password2")
}|



@section{Reference}

@defparam[current-smtp-debug-mode v boolean?
          #:value #f]{
show status of the smtp auth debug mode or set to show or not show the smtp auth log.
}

@defparam[current-smtp-host v string?
          #:value ""]{
set global smtp auth host.
}

@defparam[current-smtp-port v integer?
          #:value 25]{
set global smtp auth port number.
}

@defparam[current-smtp-username v string?
          #:value ""]{
set global smtp auth username.
}

@defparam[current-smtp-password v string?
          #:value ""]{
set global smtp auth password.
}

@defparam[current-smtp-body-content-type v string?
          #:value "text/plain"]{
set smtp mail body's content type.
}


@defproc[(make-mail [subject string?]
                    [message-body string?]
                    [#:from from string? (current-smtp-username)]
                    [#:to to (listof string?)]
                    [#:cc cc (listof string?) '()]
                    [#:bcc bcc (listof string?) '()]
                    [#:attached-files attached-files (listof (or/c path? string?)) '()]
                    [#:body-content-type body-content-type string? (current-smtp-body-content-type)])

mail?]{
make a @racket[mail] struct instance.
}


@defproc[(send-smtp-mail [email mail?]
                    [#:host host string? (current-smtp-host)]
                    [#:port port integer? (current-smtp-port)]
                    [#:user username string? (current-smtp-username)]
                    [#:password password string? (current-smtp-password)])

                    void?]{
commit the @italic{email} sending action.
}


@defstruct*[mail ([sender string?]
                  [recipients list?]
                  [cc-recipients list?]
                  [bcc-recipients list?]
                  [subject string?]
                  [message-body string?]
                  [attached-files list?])]{
  A structure type for smtp mails.
}

@defproc[(mail? [email mail]) boolean?]{
check if @italic{email} is an instance of struct @racket[mail] or not.
}

@defproc[(mail-sender [email mail?]) string?]{
returns info about who the @italic{email} was sent from.
}

@defproc[(mail-recipients [email mail?]) list?]{
returns info about who this @italic{email} was sent to.
}

@defproc[(mail-subject [email mail?]) string?]{
returns the @italic{email} subject.
}

@defproc[(mail-message-body [email mail?]) string?]{
returns the @italic{email} content.
}

@defproc[(mail-attached-files [email mail?]) list?]{
returns a list of the @italic{email} attachment file paths.
}

@defproc[(mail-header/info [email mail?]) string?]{
returns sender, recipients, subject infos of the @italic{email}.
}

@defproc[(mail-header/message-body [email mail?]) string?]{
returns message body of the @italic{email}.
}

@defproc[(mail-header/attachment [email mail?]) string?]{
returns encoded attachment content of the @italic{email}.
}

@defproc[(mail-header [email mail?]) string?]{
returns header of the @italic{email}.
}




@section{Bug Report}

Please go to @url{https://github.com/yanyingwang/smtp/issues}.


@section{TODO}

@itemlist[@item{cc bcc}
          @item{message body type: html, plain-text ...}]
