rust/lettre
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(all): Move doc to website and test it

Browse Source
This commit is contained in:
Alexis Mousset
2018-01-27 13:46:13 +01:00
parent 5face8614b
commit f10e4e81d0
43 changed files with 1903 additions and 723 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
website/content/creating-messages/_index.md
View File

@@ -8,5 +8,4 @@ weight = 2
### Creating messages
The documentation for the `lettre_email` is available on https://docs.rs/lettre_email/0.7.0/lettre_email/ for now.
This section explains how to create emails.

69
website/content/creating-messages/email.md Normal file
View File

@@ -0,0 +1,69 @@
+++
date = "2018-01-21T23:46:17+02:00"
title = "Email creation"
toc = true
weight = 4
+++
#### Simple example
The `email` part builds email messages. For now, it does not support attachments.
An email is built using an `EmailBuilder`. The simplest email could be:
```rust
extern crate lettre_email;
use lettre_email::EmailBuilder;
fn main() {
// Create an email
let email = EmailBuilder::new()
// Addresses can be specified by the tuple (email, alias)
.to(("user@example.org", "Firstname Lastname"))
// ... or by an address only
.from("user@example.com")
.subject("Hi, Hello world")
.text("Hello world.")
.build();
assert!(email.is_ok());
}
```
When the `build` method is called, the `EmailBuilder` will add the missing headers (like
`Message-ID` or `Date`) and check for missing necessary ones (like `From` or `To`). It will
then generate an `Email` that can be sent.
The `text()` method will create a plain text email, while the `html()` method will create an
HTML email. You can use the `alternative()` method to provide both versions, using plain text
as fallback for the HTML version.
#### Complete example
Below is a more complete example, not using method chaining:
```rust
extern crate lettre_email;
use lettre_email::EmailBuilder;
fn main() {
let mut builder = EmailBuilder::new();
builder.add_to(("user@example.org", "Alias name"));
builder.add_cc(("user@example.net", "Alias name"));
builder.add_from("no-reply@example.com");
builder.add_from("no-reply@example.eu");
builder.set_sender("no-reply@example.com");
builder.set_subject("Hello world");
builder.set_alternative("<h2>Hi, Hello world.</h2>", "Hi, Hello world.");
builder.add_reply_to("contact@example.com");
builder.add_header(("X-Custom-Header", "my header"));
let email = builder.build();
assert!(email.is_ok());
}
```
See the `EmailBuilder` documentation for a complete list of methods.

26
website/content/sending-messages/file.md
View File

@@ -11,22 +11,26 @@ The file transport writes the emails to the given directory. The name of the fil
It can be useful for testing purposes, or if you want to keep track of sent messages.
```rust
extern crate lettre;
use std::env::temp_dir;
use lettre::file::FileEmailTransport;
use lettre::{SimpleSendableEmail, EmailTransport, EmailAddress};
// Write to the local temp directory
let mut sender = FileEmailTransport::new(temp_dir());
let email = SimpleSendableEmail::new(
EmailAddress::new("user@localhost".to_string()),
vec![EmailAddress::new("root@localhost".to_string())],
"message_id".to_string(),
"Hello world".to_string(),
);
let result = sender.send(&email);
assert!(result.is_ok());
fn main() {
// Write to the local temp directory
let mut sender = FileEmailTransport::new(temp_dir());
let email = SimpleSendableEmail::new(
EmailAddress::new("user@localhost".to_string()),
vec![EmailAddress::new("root@localhost".to_string())],
"message_id".to_string(),
"Hello world".to_string(),
);
let result = sender.send(&email);
assert!(result.is_ok());
}
```
Example result in `/tmp/b7c211bc-9811-45ce-8cd9-68eab575d695.txt`:

2
website/content/sending-messages/intro.md
View File

@@ -12,7 +12,7 @@ emails have to implement `SendableEmail`, which is the case for emails created w
The following transports are available:
* The `SmtpTransport` uses the SMTP protocol to send the message over the network. It is
the prefered way of sending emails.
the preferred way of sending emails.
* The `SendmailTransport` uses the sendmail command to send messages. It is an alternative to
the SMTP transport.
* The `FileTransport` creates a file containing the email content to be sent. It can be used

26
website/content/sending-messages/sendmail.md
View File

@@ -8,18 +8,22 @@ weight = 3
The sendmail transport sends the email using the local sendmail command.
``` rust
```rust,no_run
extern crate lettre;
use lettre::sendmail::SendmailTransport;
use lettre::{SimpleSendableEmail, EmailTransport, EmailAddress};
let email = SimpleSendableEmail::new(
EmailAddress::new("user@localhost".to_string()),
vec![EmailAddress::new("root@localhost".to_string())],
"message_id".to_string(),
"Hello world".to_string(),
);
let mut sender = SendmailTransport::new();
let result = sender.send(&email);
assert!(result.is_ok());
fn main() {
let email = SimpleSendableEmail::new(
EmailAddress::new("user@localhost".to_string()),
vec![EmailAddress::new("root@localhost".to_string())],
"message_id".to_string(),
"Hello world".to_string(),
);
let mut sender = SendmailTransport::new();
let result = sender.send(&email);
assert!(result.is_ok());
}
```

134
website/content/sending-messages/smtp.md
View File

@@ -8,10 +8,10 @@ weight = 2
This transport uses the SMTP protocol to send emails over the network (locally or remotely).
It is desinged to be:
It is designed to be:
* Secured: email are encrypted by default
* Modern: Unicode support for email content and sender/recipient adresses when compatible
* Modern: Unicode support for email content and sender/recipient addresses when compatible
* Fast: supports tcp connection reuse
This client is designed to send emails to a relay server, and should *not* be used to send
@@ -23,64 +23,70 @@ The relay server can be the local email server, a specific host or a third-party
This is the most basic example of usage:
``` rust
```rust,no_run
extern crate lettre;
use lettre::{SimpleSendableEmail, EmailTransport, EmailAddress, SmtpTransport};
let email = SimpleSendableEmail::new(
EmailAddress::new("user@localhost".to_string()),
vec![EmailAddress::new("root@localhost".to_string())],
"message_id".to_string(),
"Hello world".to_string(),
);
// Open a local connection on port 25
let mut mailer =
SmtpTransport::builder_unencrypted_localhost().unwrap().build();
// Send the email
let result = mailer.send(&email);
assert!(result.is_ok());
fn main() {
let email = SimpleSendableEmail::new(
EmailAddress::new("user@localhost".to_string()),
vec![EmailAddress::new("root@localhost".to_string())],
"message_id".to_string(),
"Hello world".to_string(),
);
// Open a local connection on port 25
let mut mailer =
SmtpTransport::builder_unencrypted_localhost().unwrap().build();
// Send the email
let result = mailer.send(&email);
assert!(result.is_ok());
}
```
#### Complete example
``` rust
```rust,no_run
extern crate lettre;
use lettre::smtp::authentication::{Credentials, Mechanism};
use lettre::smtp::SUBMISSION_PORT;
use lettre::{SimpleSendableEmail, EmailTransport, EmailAddress, SmtpTransport};
use lettre::smtp::extension::ClientId;
use lettre::smtp::ConnectionReuseParameters;
let email = SimpleSendableEmail::new(
EmailAddress::new("user@localhost".to_string()),
vec![EmailAddress::new("root@localhost".to_string())],
"message_id".to_string(),
"Hello world".to_string(),
);
// Connect to a remote server on a custom port
let mut mailer = SmtpTransport::simple_builder("server.tld".to_string()).unwrap()
// Set the name sent during EHLO/HELO, default is `localhost`
.hello_name(ClientId::Domain("my.hostname.tld".to_string()))
// Add credentials for authentication
.credentials(Credentials::new("username".to_string(), "password".to_string()))
// Enable SMTPUTF8 if the server supports it
.smtp_utf8(true)
// Configure expected authentication mechanism
.authentication_mechanism(Mechanism::Plain)
// Enable connection reuse
.connection_reuse(ConnectionReuseParameters::ReuseUnlimited).build();
let result_1 = mailer.send(&email);
assert!(result_1.is_ok());
// The second email will use the same connection
let result_2 = mailer.send(&email);
assert!(result_2.is_ok());
// Explicitly close the SMTP transaction as we enabled connection reuse
mailer.close();
fn main() {
let email = SimpleSendableEmail::new(
EmailAddress::new("user@localhost".to_string()),
vec![EmailAddress::new("root@localhost".to_string())],
"message_id".to_string(),
"Hello world".to_string(),
);
// Connect to a remote server on a custom port
let mut mailer = SmtpTransport::simple_builder("server.tld").unwrap()
// Set the name sent during EHLO/HELO, default is `localhost`
.hello_name(ClientId::Domain("my.hostname.tld".to_string()))
// Add credentials for authentication
.credentials(Credentials::new("username".to_string(), "password".to_string()))
// Enable SMTPUTF8 if the server supports it
.smtp_utf8(true)
// Configure expected authentication mechanism
.authentication_mechanism(Mechanism::Plain)
// Enable connection reuse
.connection_reuse(ConnectionReuseParameters::ReuseUnlimited).build();
let result_1 = mailer.send(&email);
assert!(result_1.is_ok());
// The second email will use the same connection
let result_2 = mailer.send(&email);
assert!(result_2.is_ok());
// Explicitly close the SMTP transaction as we enabled connection reuse
mailer.close();
}
```
#### Lower level
@@ -88,7 +94,9 @@ mailer.close();
You can also send commands, here is a simple email transaction without
error handling:
``` rust
```rust,no_run
extern crate lettre;
use lettre::EmailAddress;
use lettre::smtp::SMTP_PORT;
use lettre::smtp::client::Client;
@@ -96,17 +104,19 @@ use lettre::smtp::client::net::NetworkStream;
use lettre::smtp::extension::ClientId;
use lettre::smtp::commands::*;
let mut email_client: Client<NetworkStream> = Client::new();
let _ = email_client.connect(&("localhost", SMTP_PORT), None);
let _ = email_client.command(EhloCommand::new(ClientId::new("my_hostname".to_string())));
let _ = email_client.command(
MailCommand::new(Some(EmailAddress::new("user@example.com".to_string())), vec![])
);
let _ = email_client.command(
RcptCommand::new(EmailAddress::new("user@example.org".to_string()), vec![])
);
let _ = email_client.command(DataCommand);
let _ = email_client.message(Box::new("Test email".as_bytes()));
let _ = email_client.command(QuitCommand);
fn main() {
let mut email_client: Client<NetworkStream> = Client::new();
let _ = email_client.connect(&("localhost", SMTP_PORT), None);
let _ = email_client.command(EhloCommand::new(ClientId::new("my_hostname".to_string())));
let _ = email_client.command(
MailCommand::new(Some(EmailAddress::new("user@example.com".to_string())), vec![])
);
let _ = email_client.command(
RcptCommand::new(EmailAddress::new("user@example.org".to_string()), vec![])
);
let _ = email_client.command(DataCommand);
let _ = email_client.message(Box::new("Test email".as_bytes()));
let _ = email_client.command(QuitCommand);
}
```

26
website/content/sending-messages/stub.md
View File

@@ -9,20 +9,24 @@ weight = 5
The stub transport only logs message envelope and drops the content. It can be useful for
testing purposes.
``` rust
```rust
extern crate lettre;
use lettre::stub::StubEmailTransport;
use lettre::{SimpleSendableEmail, EmailTransport, EmailAddress};
let email = SimpleSendableEmail::new(
EmailAddress::new("user@localhost".to_string()),
vec![EmailAddress::new("root@localhost".to_string())],
"message_id".to_string(),
"Hello world".to_string(),
);
let mut sender = StubEmailTransport::new_positive();
let result = sender.send(&email);
assert!(result.is_ok());
fn main() {
let email = SimpleSendableEmail::new(
EmailAddress::new("user@localhost".to_string()),
vec![EmailAddress::new("root@localhost".to_string())],
"message_id".to_string(),
"Hello world".to_string(),
);
let mut sender = StubEmailTransport::new_positive();
let result = sender.send(&email);
assert!(result.is_ok());
}
```
Will log (when using a logger like `env_logger`):