Qpsmtpd::Address(3pm)

💌 Qpsmtpd::Address — the perl manual page, but make it cute

okay bestie, so this is Qpsmtpd::Address(3pm), straight out of the User Contributed Perl Documentation section, and it's literally all about lightweight e-mail address objects. yes. tiny little address objects. they're adorable. let's get into it 🎀

---

✨ NAME ✨

Qpsmtpd::Address — Lightweight E-Mail address objects 💖

---

🌸 DESCRIPTION 🌸

so this whole thing started as a cut-and-paste job from Mail::Address (we love a humble origin story), and it's got every single jot and tittle from RFC-2821 / RFC-2822 about what actually counts as a legal e-mail address — specifically for use during the SMTP transaction. every. single. one. no crumbs left. 💅

---

🦋 USAGE 🦋

  my $rcpt = Qpsmtpd::Address->new('<email.address@example.com>');

and here's the slay part: the objects you make can just be used as-is, because they automatically stringify to a standard form, and they come with an overloaded comparison so testing values is easy-peasy. main character objects fr fr. ✨

---

👑 METHODS 👑

new()

you can call this icon two different ways:

• Qpsmtpd::Address->new('<full_address@example.com>') — this is the normal mode of operation, the everyday vibe. you pass the entire contents of the RCPT TO: command from the SMTP transaction, and the value gets fully parsed via the canonify method, using the full RFC 2821 rules.
• Qpsmtpd::Address->new("user", "host") — if you've already split the address from the domain/host yourself, this mode will not canonify the input values. and because of that, it's not recommended when the input is user-generated. but it IS perfect for generating Qpsmtpd::Address objects for accounts like <postmaster> or indeed for the bounce address <>. 🫶

the resulting objects can be stored in arrays, or used in plugins to test for equality (like in badmailfrom). cute and functional, the dream combo.

canonify()

primarily an internal method, bestie — it only gets used on the path portion of an e-mail message, as defined in RFC-2821. (that's the part inside the angle brackets, and it does not include the "human readable" portion of an address.) it returns a list of (local-part, domain). 💫

parse()

kept around as a compatibility method, and it is completely equivalent to calling new() with a single parameter. that's it. that's the whole thing. iconic minimalism. 🎀

address()

you can use this to reset the value of an existing Q::A object — in that case it takes a parameter with or without the angle brackets.

it returns the stringified representation of the address. but NOTE: it does not escape any of the characters that need escaping, and it does not include the surrounding angle brackets. for that purpose, go see format. k thanks bye 💅

format()

returns the canonical stringified representation of the address. it does escape any characters requiring it (per RFC-2821/2822) and it does include the surrounding angle brackets. it's also the default stringification operator, so these two lines are literally the same thing:

  print $rcpt->format();
  print $rcpt;

same energy. same output. periodt. ✨

user([$user])

returns the "localpart" of the address, per RFC-2821 — aka the portion before the @ sign.

if you call it with one parameter, the localpart gets set and the new value is returned. 🦋

host([$host])

returns the "domain" part of the address, per RFC-2821 — aka the portion after the @ sign.

if you call it with one parameter, the domain gets set and the new value is returned. 🌸

notes($key[,$value])

get or set a note on the address. it's a little piece of data you wanna attach to the address and then read somewhere else. for example, you can use this to pass data between plugins. it's giving sticky note energy and honestly? obsessed. 🍓

---

💖 COPYRIGHT 💖

Copyright 2004-2005 Peter J. Holzer. See the LICENSE file for more information.

---

and that's the whole page bestie!! now go forth and make some tiny address objects 🧚 no cap, you've got this 💜

---

this lil manual page came from perl v5.40.1 and it's dated 2025-03-21, so you know it's fresh-ish. it lives under the name Qpsmtpd::Address(3pm). mwah 💅