class EmailAddress::Address

Implements the Email Address container, which hold the Local (EmailAddress::Local) and Host (EmailAddress::Host) parts.

Constants

CONVENTIONAL_REGEX
RELAXED_REGEX
STANDARD_REGEX

Attributes

config[RW]
error_message[R]
host[RW]
local[RW]
locale[RW]
original[RW]
reason[RW]

Public Class Methods

new(email_address, config = {}, locale = "en") click to toggle source

Given an email address of the form “local@hostname”, this sets up the instance, and initializes the address to the “normalized” format of the address. The original string is available in the original method.

# File lib/email_address/address.rb, line 26
def initialize(email_address, config = {}, locale = "en")
  @config = Config.new(config)
  @original = email_address
  @locale = locale
  email_address = (email_address || "").strip
  email_address = parse_rewritten(email_address) unless config[:skip_rewrite]
  local, host = Address.split_local_host(email_address)

  @host = Host.new(host, @config, locale)
  @local = Local.new(local, @config, @host, locale)
  @error = @error_message = nil
end
split_local_host(email) click to toggle source

Given an email address, this returns an array of [local, host] parts

# File lib/email_address/address.rb, line 40
def self.split_local_host(email)
  if (lh = email.match(/(.+)@(.+)/))
    lh.to_a[1, 2]
  else
    [email, ""]
  end
end

Public Instance Methods

<=>(other) click to toggle source

Return the <=> or CMP comparison operator result (-1, 0, +1) on the comparison of this addres with another, using the normalized form.

# File lib/email_address/address.rb, line 210
def <=>(other)
  to_s <=> other.to_s
end
==(other) click to toggle source

Equal matches the normalized version of each address. Use the Threequal to check for match on canonical or redacted versions of addresses

# File lib/email_address/address.rb, line 189
def ==(other)
  to_s == other.to_s
end
Also aliased as: eql?, equal?
base() click to toggle source

The base address is the mailbox, without tags, and host.

# File lib/email_address/address.rb, line 138
def base
  mailbox + "@" + hostname
end
canonical() click to toggle source

Returns the canonical email address according to the provider uniqueness rules. Usually, this downcases the address, removes spaves and comments and tags, and any extraneous part of the address not considered a unique account by the provider.

# File lib/email_address/address.rb, line 126
def canonical
  c = local.canonical
  c += "@" + host.canonical if host.canonical && host.canonical > " "
  c
end
canonical?() click to toggle source

True if the given address is already in it’s canonical form.

# File lib/email_address/address.rb, line 133
def canonical?
  canonical == to_s
end
comment() click to toggle source

Retuns any comments parsed from the local part of the email address. This is retained for inspection after construction, even if it is removed from the normalized email address.

# File lib/email_address/address.rb, line 76
def comment
  local.comment
end
connect() click to toggle source

Connects to host to test if user can receive email. This should NOT be performed as an email address check, but is provided to assist in problem resolution. If you abuse this, you could be blocked by the ESP.

NOTE: As of Ruby 3.1, Net::SMTP was moved from the standard library to the ‘net-smtp’ gem. In order to avoid adding that dependency for this experimental feature, please add the gem to your Gemfile and require it to use this feature.

# File lib/email_address/address.rb, line 265
def connect
  smtp = Net::SMTP.new(host_name || ip_address)
  smtp.start(@config[:smtp_helo_name] || "localhost")
  smtp.mailfrom @config[:smtp_mail_from] || "postmaster@localhost"
  smtp.rcptto to_s
  # p [:connect]
  smtp.finish
  true
rescue Net::SMTPUnknownError => e
  set_error(:address_unknown, e.to_s)
rescue Net::SMTPFatalError => e
  set_error(:address_unknown, e.to_s)
rescue SocketError => e
  set_error(:address_unknown, e.to_s)
ensure
  if smtp&.started?
    smtp.finish
  end
  !!@error
end
eql?(other)
Alias for: ==
equal?(other)
Alias for: ==
error() click to toggle source
# File lib/email_address/address.rb, line 295
def error
  valid? ? nil : @error_message
end
host_name() click to toggle source

Returns the host name, the part to the right of the @ sign.

# File lib/email_address/address.rb, line 88
def host_name
  @host.host_name
end
Also aliased as: right, hostname
hostname()
Alias for: host_name
include?(other_email)
Alias for: same_as?
inspect() click to toggle source
# File lib/email_address/address.rb, line 118
def inspect
  "#<#{self.class}:0x#{object_id.to_s(16)} address=\"#{self}\">"
end
left() click to toggle source

Everything to the left of the @ in the address, called the local part.

# File lib/email_address/address.rb, line 57
def left
  local.to_s
end
mailbox() click to toggle source

Returns the mailbox portion of the local port, with no tags. Usually, this can be considered the user account or role account names. Some systems employ dynamic email addresses which don’t have the same meaning.

# File lib/email_address/address.rb, line 64
def mailbox
  local.mailbox
end
matches?(*rules) click to toggle source

Address matches one of these Matcher rule patterns

# File lib/email_address/address.rb, line 215
def matches?(*rules)
  rules.flatten!
  match = local.matches?(rules)
  match ||= host.matches?(rules)
  return match if match

  # Does "root@*.com" match "root@example.com" domain name
  rules.each do |r|
    if /.+@.+/.match?(r)
      return r if File.fnmatch?(r, to_s)
    end
  end
  false
end
md5(form = :base)
Alias for: reference
munge() click to toggle source

Returns the munged form of the address, by default “mailbox@domain.tld” returns “ma*****@do*****”.

# File lib/email_address/address.rb, line 160
def munge
  [local.munge, host.munge].join("@")
end
normal() click to toggle source

Returns the string representation of the normalized email address.

# File lib/email_address/address.rb, line 105
def normal
  if !@original
    @original
  elsif local.to_s.size == 0
    ""
  elsif host.to_s.size == 0
    local.to_s
  else
    "#{local}@#{host}"
  end
end
Also aliased as: to_s
provider() click to toggle source

Returns the ESP (Email Service Provider) or ISP name derived using the provider configuration rules.

# File lib/email_address/address.rb, line 96
def provider
  @host.provider
end
redact(digest = :sha1) click to toggle source

Returns the redacted form of the address This format is defined by this libaray, and may change as usage increases. Takes either :sha1 (default) or :md5 as the argument

# File lib/email_address/address.rb, line 145
def redact(digest = :sha1)
  raise "Unknown Digest type: #{digest}" unless %i[sha1 md5].include?(digest)
  return to_s if local.redacted?
  r = %({#{send(digest)}})
  r += "@" + host.to_s if host.to_s && host.to_s > " "
  r
end
redacted?() click to toggle source

True if the address is already in the redacted state.

# File lib/email_address/address.rb, line 154
def redacted?
  local.redacted?
end
reference(form = :base) click to toggle source

Returns and MD5 of the base address form. Some cross-system systems use the email address MD5 instead of the actual address to refer to the same shared user identity without exposing the actual address when it is not known in common.

# File lib/email_address/address.rb, line 168
def reference(form = :base)
  Digest::MD5.hexdigest(send(form))
end
Also aliased as: md5
right()
Alias for: host_name
same_as?(other_email) click to toggle source

Return the <=> or CMP comparison operator result (-1, 0, +1) on the comparison of this addres with another, using the canonical or redacted forms.

# File lib/email_address/address.rb, line 197
def same_as?(other_email)
  if other_email.is_a?(String)
    other_email = Address.new(other_email)
  end

  canonical == other_email.canonical ||
    redact == other_email.canonical ||
    canonical == other_email.redact
end
Also aliased as: include?
set_error(err, reason = nil) click to toggle source
# File lib/email_address/address.rb, line 286
def set_error(err, reason = nil)
  @error = err
  @reason = reason
  @error_message = Config.error_message(err, locale)
  false
end
sha1(form = :base) click to toggle source

This returns the SHA1 digest (in a hex string) of the base email address. See md5 for more background.

# File lib/email_address/address.rb, line 175
def sha1(form = :base)
  Digest::SHA1.hexdigest((send(form) || "") + (@config[:sha1_secret] || ""))
end
sha256(form = :base) click to toggle source
# File lib/email_address/address.rb, line 179
def sha256(form = :base)
  Digest::SHA256.hexdigest((send(form) || "") + (@config[:sha256_secret] || ""))
end
tag() click to toggle source

Returns the tag part of the local address, or nil if not given.

# File lib/email_address/address.rb, line 69
def tag
  local.tag
end
to_s()
Alias for: normal
valid?(options = {}) click to toggle source

Returns true if this address is considered valid according to the format configured for its provider, It test the normalized form.

# File lib/email_address/address.rb, line 236
def valid?(options = {})
  @error = nil
  unless local.valid?
    return set_error local.error
  end
  unless host.valid?
    return set_error host.error_message
  end
  if @config[:address_size] && !@config[:address_size].include?(to_s.size)
    return set_error :exceeds_size
  end
  if @config[:address_validation].is_a?(Proc)
    unless @config[:address_validation].call(to_s)
      return set_error :not_allowed
    end
  else
    return false unless local.valid?
    return false unless host.valid?
  end
  true
end