1Mail::IMAPClient::BodySUtsreurctCuornet(r3i)buted Perl DMoaciulm:e:nItMaAtPiColnient::BodyStructure(3)
2
6 Mail::IMAPClient::BodyStructure - parse fetched results
7
9 use Mail::IMAPClient;
10 use Mail::IMAPClient::BodyStructure;
11 my $imap = Mail::IMAPClient->new(
13 Server => $server, User => $login, Password => $pass
14 );
15 $imap->select("INBOX") or die "Could not select INBOX: $@\n";
17 my @recent = $imap->search("recent") or die "No recent msgs in INBOX\n";
19 foreach my $id (@recent) {
21 my $bsdat = $imap->fetch( $id, "bodystructure" );
22 my $bso = Mail::IMAPClient::BodyStructure->new( join("", $imap->History) );
23 my $mime = $bso->bodytype . "/" . $bso->bodysubtype;
24 my $parts = map( "\n\t" . $_, $bso->parts );
25 print "Msg $id (Content-type: $mime) contains these parts:$parts\n";
26 }
27
29 This extension will parse the result of an IMAP FETCH BODYSTRUCTURE
30 command into a perl data structure. It also provides helper methods to
31 help pull information out of the data structure.
32 This module requires Parse::RecDescent.
34
36 The following class method is available:
37 new
39 This class method is the constructor method for instantiating new
40 Mail::IMAPClient::BodyStructure objects. The new method accepts one
41 argument, a string containing a server response to a FETCH
42 BODYSTRUCTURE directive.
43 The module Mail::IMAPClient provides the get_bodystructure convenience
45 method to simplify use of this module when starting with just a
46 messages sequence number or unique ID (UID).
47
49 The following object methods are available:
50 bodytype
52 The bodytype object method requires no arguments. It returns the
53 bodytype for the message whose structure is described by the calling
54 Mail::IMAPClient::Bodystructure object.
55 bodysubtype
57 The bodysubtype object method requires no arguments. It returns the
58 bodysubtype for the message whose structure is described by the calling
59 Mail::IMAPClient::Bodystructure object.
60 bodyparms
62 The bodyparms object method requires no arguments. It returns the
63 bodyparms for the message whose structure is described by the calling
64 Mail::IMAPClient::Bodystructure object.
65 bodydisp
67 The bodydisp object method requires no arguments. It returns the
68 bodydisp for the message whose structure is described by the calling
69 Mail::IMAPClient::Bodystructure object.
70 bodyid
72 The bodyid object method requires no arguments. It returns the bodyid
73 for the message whose structure is described by the calling
74 Mail::IMAPClient::Bodystructure object.
75 bodydesc
77 The bodydesc object method requires no arguments. It returns the
78 bodydesc for the message whose structure is described by the calling
79 Mail::IMAPClient::Bodystructure object.
80 bodyenc
82 The bodyenc object method requires no arguments. It returns the
83 bodyenc for the message whose structure is described by the calling
84 Mail::IMAPClient::Bodystructure object.
85 bodysize
87 The bodysize object method requires no arguments. It returns the
88 bodysize for the message whose structure is described by the calling
89 Mail::IMAPClient::Bodystructure object.
90 bodylang
92 The bodylang object method requires no arguments. It returns the
93 bodylang for the message whose structure is described by the calling
94 Mail::IMAPClient::Bodystructure object.
95 bodystructure
97 The bodystructure object method requires no arguments. It returns the
98 bodystructure for the message whose structure is described by the
99 calling Mail::IMAPClient::Bodystructure object.
100 envelopestruct
102 The envelopestruct object method requires no arguments. It returns a
103 Mail::IMAPClient::BodyStructure::Envelope object for the message from
104 the calling Mail::IMAPClient::Bodystructure object.
105 textlines
107 The textlines object method requires no arguments. It returns the
108 textlines for the message whose structure is described by the calling
109 Mail::IMAPClient::Bodystructure object.
110
112 The IMAP standard specifies that output from the IMAP FETCH ENVELOPE
113 command will be an RFC2060 envelope structure. It further specifies
114 that output from the FETCH BODYSTRUCTURE command may also contain
115 embedded envelope structures (if, for example, a message's subparts
116 contain one or more included messages). Objects belonging to
117 Mail::IMAPClient::BodyStructure::Envelope are Perl representations of
118 these envelope structures, which is to say the nested parenthetical
119 lists of RFC2060 translated into a Perl datastructure.
120 Note that all of the fields relate to the specific part to which they
122 belong. In other words, output from a FETCH nnnn ENVELOPE command (or,
123 in Mail::IMAPClient, "$imap-"fetch($msgid,"ENVELOPE")> or "my $env =
124 $imap-"get_envelope($msgid)>) are for the message, but fields from
125 within a bodystructure relate to the message subpart and not the parent
126 message.
127 An envelope structure's Mail::IMAPClient::BodyStructure::Envelope
129 representation is a hash of thingies that looks like this:
130 {
132 subject => "subject",
133 inreplyto => "reference_message_id",
134 from => [ addressStruct1 ],
135 messageid => "message_id",
136 bcc => [ addressStruct1, addressStruct2 ],
137 date => "Tue, 09 Jul 2002 14:15:53 -0400",
138 replyto => [ adressStruct1, addressStruct2 ],
139 to => [ adressStruct1, addressStruct2 ],
140 sender => [ adressStruct1 ],
141 cc => [ adressStruct1, addressStruct2 ],
142 }
143 The ...::Envelope object also has methods for accessing data in the
145 structure. They are:
146 date
148 Returns the date of the message.
149 inreplyto
151 Returns the message id of the message to which this message is a
152 reply.
153 subject
155 Returns the subject of the message.
156 messageid
158 Returns the message id of the message.
159 You can also use the following methods to get addressing information.
161 Each of these methods returns an array of
162 Mail::IMAPClient::BodyStructure::Address objects, which are perl data
163 structures representing RFC2060 address structures. Some of these
164 arrays would naturally contain one element (such as from, which
165 normally contains a single "From:" address); others will often contain
166 more than one address. However, because RFC2060 defines all of these
167 as "lists of address structures", they are all translated into arrays
168 of ...::Address objects.
169 See the section on Mail::IMAPClient::BodyStructure::Address, below, for
171 alternate (and preferred) ways of accessing these data.
172 The methods available are:
174 bcc Returns an array of blind cc'ed recipients' address structures.
176 (Don't expect much in here unless the message was sent from the
177 mailbox you're poking around in, by the way.)
178 cc Returns an array of cc'ed recipients' address structures.
180 from
182 Returns an array of "From:" address structures--usually just one.
183 replyto
185 Returns an array of "Reply-to:" address structures. Once again
186 there is usually just one address in the list.
187 sender
189 Returns an array of senders' address structures--usually just one
190 and usually the same as from.
191 to Returns an array of recipients' address structures.
193 Each of the methods that returns a list of address structures (i.e. a
195 list of Mail::IMAPClient::BodyStructure::Address arrays) also has an
196 analogous method that will return a list of E-Mail addresses instead.
197 The addresses are in the format "personalname <mailboxname@hostname>"
198 (see the section on Mail::IMAPClient::BodyStructure::Address, below)
199 However, if the personal name is 'NIL' then it is omitted from the
200 address.
201 These methods are:
203 bcc_addresses
205 Returns a list (or an array reference if called in scalar context)
206 of blind cc'ed recipients' email addresses. (Don't expect much in
207 here unless the message was sent from the mailbox you're poking
208 around in, by the way.)
209 cc_addresses
211 Returns a list of cc'ed recipients' email addresses. If called in
212 a scalar context it returns a reference to an array of email
213 addresses.
214 from_addresses
216 Returns a list of "From:" email addresses. If called in a scalar
217 context it returns the first email address in the list. (It's
218 usually a list of just one anyway.)
219 replyto_addresses
221 Returns a list of "Reply-to:" email addresses. If called in a
222 scalar context it returns the first email address in the list.
223 sender_addresses
225 Returns a list of senders' email addresses. If called in a scalar
226 context it returns the first email address in the list.
227 to_addresses
229 Returns a list of recipients' email addresses. If called in a
230 scalar context it returns a reference to an array of email
231 addresses.
232 Note that context affects the behavior of all of the above methods.
234 Those fields that will commonly contain multiple entries (i.e. they are
236 recipients) will return an array reference when called in scalar
237 context. You can use this behavior to optimize performance.
238 Those fields that will commonly contain just one address (the sender's)
240 will return the first (and usually only) address. You can use this
241 behavior to optimize your development time.
242
244 Several components of an envelope structure are address structures.
245 They are each parsed into their own object,
246 Mail::IMAPClient::BodyStructure::Address, which looks like this:
247 {
249 mailboxname => 'somebody.special',
250 hostname => 'somplace.weird.com'
251 personalname => 'Somebody Special
252 sourceroute => 'NIL'
253 }
254 RFC2060 specifies that each address component of a bodystructure is a
256 list of address structures, so Mail::IMAPClient::BodyStructure parses
257 each of these into an array of Mail::IMAPClient::BodyStructure::Address
258 objects.
259 Each of these objects has the following methods available to it:
261 mailboxname
263 Returns the "mailboxname" portion of the address, which is the part
264 to the left of the '@' sign.
265 hostname
267 Returns the "hostname" portion of the address, which is the part to
268 the right of the '@' sign.
269 personalname
271 Returns the "personalname" portion of the address, which is the
272 part of the address that's treated like a comment.
273 sourceroute
275 Returns the "sourceroute" portion of the address, which is
276 typically "NIL".
277 Taken together, the parts of an address structure form an address that
279 will look something like this:
280 "personalname <mailboxname@hostname>"
282 Note that because the Mail::IMAPClient::BodyStructure::Address objects
284 come in arrays, it's generally easier to use the methods available to
285 Mail::IMAPClient::BodyStructure::Envelope to obtain all of the
286 addresses in a particular array in one operation. These methods are
287 provided, however, in case you'd rather do things the hard way. (And
288 also because the aforementioned methods from
289 Mail::IMAPClient::BodyStructure::Envelope need them anyway.)
290
292 Original author: David J. Kernen; Reworked by: Mark Overmeer;
293 Maintained by Phil Pearl.
294
296 perl(1), Mail::IMAPClient, Parse::RecDescent, and RFC2060.
297perl v5.34.0 2022-01-21Mail::IMAPClient::BodyStructure(3)