Check if an email address exists without sending any email, written in Rust. Comes with a ⚙️ HTTP backend.
Rust emailemail-validationemail-validation-apiemail-verificationemail-verification-apiemail-verifierhacktoberfest
use crate::misc::{MiscDetails, MiscError};
use crate::mx::{MxDetails, MxError};
use crate::smtp::verif_method::VerifMethod;
use crate::smtp::{SmtpDebug, SmtpDetails, SmtpError, SmtpErrorDesc};
use crate::syntax::SyntaxDetails;
use crate::util::ser_with_display::ser_with_display;
use async_smtp::EmailAddress as AsyncSmtpEmailAddress;
use chrono::{DateTime, Utc};
use derive_builder::Builder;
use serde::{ser::SerializeMap, Deserialize, Serialize, Serializer};
use std::fmt::Display;
use std::str::FromStr;
use std::time::{Duration, SystemTime};
/// Wrapper around the `EmailAddress` from `async_smtp` to allow for
/// serialization and deserialization.
#[derive(Debug, Eq, PartialEq, Clone)]
pub struct EmailAddress(AsyncSmtpEmailAddress);
impl Serialize for EmailAddress {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
ser_with_display(&self.0, serializer)
}
}
impl<'de> Deserialize<'de> for EmailAddress {
fn deserialize<D>(deserializer: D) -> Result<EmailAddress, D::Error>
where
D: serde::Deserializer<'de>,
{
let s = String::deserialize(deserializer)?;
Ok(EmailAddress(
AsyncSmtpEmailAddress::from_str(&s).map_err(serde::de::Error::custom)?,
))
}
}
impl Display for EmailAddress {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
self.0.fmt(f)
}
}
impl FromStr for EmailAddress {
type Err = anyhow::Error;
fn from_str(s: &str) -> Result<Self, Self::Err> {
Ok(EmailAddress(AsyncSmtpEmailAddress::from_str(s)?))
}
}
impl EmailAddress {
pub fn new(email: String) -> Result<Self, anyhow::Error> {
Ok(EmailAddress(AsyncSmtpEmailAddress::new(email)?))
}
pub fn into_inner(self) -> AsyncSmtpEmailAddress {
self.0
}
}
impl AsRef<AsyncSmtpEmailAddress> for EmailAddress {
fn as_ref(&self) -> &AsyncSmtpEmailAddress {
&self.0
}
}
impl AsRef<str> for EmailAddress {
fn as_ref(&self) -> &str {
self.0.as_ref()
}
}
/// Perform the email verification via a specified proxy. The usage of a proxy
/// is optional.
#[derive(Debug, Default, Clone, Deserialize, PartialEq, Serialize)]
pub struct CheckEmailInputProxy {
/// Use the specified SOCKS5 proxy host to perform email verification.
pub host: String,
/// Use the specified SOCKS5 proxy port to perform email verification.
pub port: u16,
/// Username to pass to proxy authentication.
pub username: Option<String>,
/// Password to pass to proxy authentication.
pub password: Option<String>,
/// The timeout for the connection to the proxy, in ms.
pub timeout_ms: Option<u64>,
}
/// Builder pattern for the input argument into the main `email_exists`
/// function.
#[derive(Builder, Debug, Clone, Deserialize, Serialize)]
#[builder(default)]
pub struct CheckEmailInput {
/// The email to validate.
pub to_email: String,
pub verif_method: VerifMethod,
/// Whether to check if a gravatar image is existing for the given email.
/// Adds a bit of latency to the verification process.
///
/// Defaults to false.
pub check_gravatar: bool,
/// Check if a the email address is present in HaveIBeenPwned API.
/// If the api_key is filled, HaveIBeenPwned API is checked
pub haveibeenpwned_api_key: Option<String>,
/// The WebDriver address to use for headless verifications.
///
/// Defaults to http://localhost:9515.
pub webdriver_addr: String,
/// The WebDriver configuration to use for headless verifications.
///
/// Defaults to the default WebdriverConfig.
pub webdriver_config: WebdriverConfig,
/// Identifier for the service currently running Reacher. We recommend
/// setting this to an unique identifier of the server where Reacher is
/// installed on.
///
/// Defaults to "backend-dev".
pub backend_name: String,
/// Sentry DSN to send errors to Sentry.
///
/// Defaults to None.
pub sentry_dsn: Option<String>,
}
impl Default for CheckEmailInput {
fn default() -> Self {
CheckEmailInput {
to_email: "".into(),
verif_method: VerifMethod::default(),
check_gravatar: false,
haveibeenpwned_api_key: None,
webdriver_addr: "http://localhost:9515".into(),
webdriver_config: WebdriverConfig::default(),
backend_name: "backend-dev".into(),
sentry_dsn: None,
}
}
}
/// An enum to describe how confident we are that the recipient address is
/// real.
#[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum Reachable {
/// The email is safe to send.
Safe,
/// The email address appears to exist, but has quality issues that may
/// result in low engagement or a bounce. Emails are classified as risky
/// when one of the following happens:
/// - catch-all email,
/// - disposable email,
/// - role-based address,
/// - full inbox.
Risky,
/// Emails that don't exist or are syntactically incorrect. Do not send to
/// these emails.
Invalid,
/// We're unable to get a valid response from the recipient's email server.
Unknown,
}
/// Details about the email verification used for debugging.
#[derive(Debug, Deserialize, Serialize)]
pub struct DebugDetails {
/// Identifier for the service currently running Reacher.
pub backend_name: String,
/// Version of Reacher that performed the verification.
#[serde(default)]
pub reacher_version: String,
/// The time when the email verification started.
pub start_time: DateTime<Utc>,
/// The time when the email verification ended.
pub end_time: DateTime<Utc>,
/// The duration of the email verification.
pub duration: Duration,
/// Details about the email verification used for debugging.
pub smtp: SmtpDebug,
}
impl Default for DebugDetails {
fn default() -> Self {
Self {
start_time: SystemTime::now().into(),
end_time: SystemTime::now().into(),
duration: Duration::default(),
smtp: SmtpDebug::default(),
backend_name: "backend-dev".into(),
reacher_version: crate::CARGO_PKG_VERSION.into(),
}
}
}
/// The result of the [check_email](check_email) function.
#[derive(Debug)]
pub struct CheckEmailOutput {
/// Input by the user.
pub input: String,
pub is_reachable: Reachable,
/// Misc details about the email address.
pub misc: Result<MiscDetails, MiscError>,
/// Details about the MX host.
pub mx: Result<MxDetails, MxError>,
/// Details about the SMTP responses of the email.
pub smtp: Result<SmtpDetails, SmtpError>,
/// Details about the email address.
pub syntax: SyntaxDetails,
/// Details about the email verification used for debugging.
pub debug: DebugDetails,
}
impl Default for CheckEmailOutput {
fn default() -> Self {
CheckEmailOutput {
input: String::default(),
is_reachable: Reachable::Unknown,
misc: Ok(MiscDetails::default()),
mx: Ok(MxDetails::default()),
smtp: Ok(SmtpDetails::default()),
syntax: SyntaxDetails::default(),
debug: DebugDetails::default(),
}
}
}
// Implement a custom serialize.
impl Serialize for CheckEmailOutput {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
// This is just used internally to get the nested error field.
#[derive(Serialize)]
struct MyError<E> {
error: E,
// We add an optional "description" field when relevant, given by
// the `get_description` on SmtpError.
#[serde(skip_serializing_if = "Option::is_none")]
description: Option<SmtpErrorDesc>,
}
let mut map = serializer.serialize_map(Some(1))?;
map.serialize_entry("input", &self.input)?;
map.serialize_entry("is_reachable", &self.is_reachable)?;
match &self.misc {
Ok(t) => map.serialize_entry("misc", &t)?,
Err(error) => map.serialize_entry(
"misc",
&MyError {
error,
description: None,
},
)?,
}
match &self.mx {
Ok(t) => map.serialize_entry("mx", &t)?,
Err(error) => map.serialize_entry(
"mx",
&MyError {
error,
description: None,
},
)?,
}
match &self.smtp {
Ok(t) => map.serialize_entry("smtp", &t)?,
Err(error) => map.serialize_entry(
"smtp",
&MyError {
error,
description: error.get_description(),
},
)?,
}
map.serialize_entry("syntax", &self.syntax)?;
map.serialize_entry("debug", &self.debug)?;
map.end()
}
}
#[derive(Builder, Clone, Debug, Deserialize, Serialize, Default)]
pub struct WebdriverConfig {
pub binary: Option<String>,
}
#[cfg(test)]
mod tests {
use super::{CheckEmailOutput, DebugDetails};
use async_smtp::response::{Category, Code, Detail, Response, Severity};
#[test]
fn should_serialize_correctly() {
// create a dummy CheckEmailOutput, with a given message as a transient
// SMTP error.
fn dummy_response_with_message(m: &str) -> CheckEmailOutput {
let r = Response::new(
Code {
severity: Severity::TransientNegativeCompletion,
category: Category::MailSystem,
detail: Detail::Zero,
},
vec![m.to_string(), "8BITMIME".to_string(), "SIZE 42".to_string()],
);
CheckEmailOutput {
input: "foo".to_string(),
is_reachable: super::Reachable::Unknown,
misc: Ok(super::MiscDetails::default()),
mx: Ok(super::MxDetails::default()),
syntax: super::SyntaxDetails::default(),
smtp: Err(super::SmtpError::AsyncSmtpError(r.into())),
debug: DebugDetails::default(),
}
}
let res = dummy_response_with_message("blacklist");
let actual = serde_json::to_string(&res).unwrap();
// Make sure the `description` is present with IpBlacklisted.
let expected = r#""smtp":{"error":{"type":"AsyncSmtpError","message":"transient: blacklist; 8BITMIME; SIZE 42"},"description":"IpBlacklisted"}"#;
assert!(actual.contains(expected));
let res =
dummy_response_with_message("Client host rejected: cannot find your reverse hostname");
let actual = serde_json::to_string(&res).unwrap();
// Make sure the `description` is present with NeedsRDNs.
let expected = r#"smtp":{"error":{"type":"AsyncSmtpError","message":"transient: Client host rejected: cannot find your reverse hostname; 8BITMIME; SIZE 42"},"description":"NeedsRDNS"}"#;
assert!(actual.contains(expected));
let res = dummy_response_with_message("foobar");
let actual = serde_json::to_string(&res).unwrap();
// Make sure the `description` is NOT present.
let expected = r#""smtp":{"error":{"type":"AsyncSmtpError","message":"transient: foobar; 8BITMIME; SIZE 42"}}"#;
assert!(actual.contains(expected));
}
#[test]
fn should_serialize_reacher_version() {
let actual = serde_json::to_value(DebugDetails::default()).unwrap();
assert_eq!(actual["reacher_version"], crate::CARGO_PKG_VERSION);
}
#[test]
fn should_deserialize_without_reacher_version() {
let mut value = serde_json::to_value(DebugDetails::default()).unwrap();
value.as_object_mut().unwrap().remove("reacher_version");
let debug: DebugDetails = serde_json::from_value(value).unwrap();
assert_eq!(debug.reacher_version, "");
}
}