/usr/share/doc/ruby-rubymail/guide/Intro.txt is in ruby-rubymail 1.0.0-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | = Introduction to RubyMail
This will get you started with the basics of using RubyMail.
== Turning Text into a Message Object
message = RMail::Parser.read(input)
The input can be a normal Ruby IO object or a string. The result is a
RMail::Message object. See RMail::Parser for more information.
== Turning a Message Object into Text
File.open('my-message', 'w') { |f|
RMail::Serialize.write(f, message)
}
or
string = RMail::Serialize.write('', message)
See RMail::Serialize for more information.
A convenient shortcut when you want the message as a string is
RMail::Message#to_s.
string = message.to_s
You can also use RMail::Message#each to process each line of the
serialized message in turn.
message.each { |line|
puts line
}
== Manipulating a Message
You use the methods of the RMail::Message and RMail::Header classes to
manipulate the message.
=== Retrieve the Body
You can retrieve the text of a single part message with
RMail::Message#body.
body = message.body
But beware that if the message is a MIME multipart message, +body+
will be an Array of RMail::Message objects. If you know you have a
MIME multipart message (easily tested with RMail::Message#multipart?),
then you can retrieve them individually with RMail::Message#part and
RMail::Message#each_part.
first_part = message.part(0)
message.each_part { |part|
# do something with part
}
See guide/MIME.txt for more tips on dealing with MIME messages.
=== Manipulate the Message Headers
The RMail::Message#header method retrieves the RMail::Header object
that every message contains. You can then use RMail::Header methods
to manipulate the message's header.
People often confuse a "message header" with "header fields." In
RubyMail a "header" always means the entire header of the message,
while "field" means an individual header field (e.g. "Subject").
To append new fields, simply access assign to them like an array:
message.header['To'] = 'bob@example.net'
message.header['From'] = 'sally@example.net'
Note that the above will <em>always</em> append a new header, so you
must delete existing headers if you want only one.
To retrieve fields, you can access the header like an array. This
will return the field value.
subject = message.header['Subject']
Of course, a header may have several fields with the same name. To
retrieve all the values you can use RMail::Header.match.
destinations = message.header.match(/^(to|cc|bcc)$/, nil)
See the RMail::Header documentation for many other useful functions.
== Dealing with Email Addresses
The address syntax for Internet email messages (as specified in
RFC2822) is complex. RubyMail contains the RMail::Address class that
can be used to parse and generate these addresses in a robust way.
For example, to retrieve all destination addresses from a
RMail::Header object:
recipients = RMail::Address.parse(header.match(/^(to|cc)/, nil))
Then print out just the address portion:
recipients.each { |r|
r.address
}
When creating an address from scratch, you typically do this:
address = RMail::Address.new("Bob Smith <bob@example.net>")
Then to get the text form of the address form back:
address.format
TODO: addresses can be keys of a hash, sorted, etc...
== More Topics
This is just the beginning. See guide/TableOfContents.txt for a list
of other things covered in this guide.
|