--- a/lib/Exim/Grey.pm	Sat Jun 04 22:07:30 2016 +0200
+++ b/lib/Exim/Grey.pm	Sat Jun 04 22:07:56 2016 +0200
@@ -220,11 +220,56 @@
 The I<key> is mandotory, the default I<delay> is 600 seconds and the default I<db>
 is called F<seen>.
 
-I<Key> may contain a suffix, separated with '/'. This suffix is used for
+I<Key> may contain a suffix, separated by "/". This suffix is used for
 automatic whitelisting.
 
+=item scalar B<seen>(I<key>, I<delay>, I<db>)
+
+The same as C<unseen()>, but with reversed result.
+
 =back
 
+=head1 EXAMPLES
+
+=head2 Greylisting
+
+First you have to include B<Exim::Grey> into your Exim. If Exim is built with Perl
+support, the configuration syntax allows for C<perl_startup>:
+
+    perl_startup = use Exim::Grey qw(unseen);
+
+In the ACL section of the configuration can check if a given key (sender, or combination
+of sender and recipient, or whatever) is new (unseen):
+
+    defer condition = ${perl{unseen}{<$sender_address>:$<local_part@$domain>}}
+
+If the same condition is checked more then I<delay> later, the C<unseen> function returns
+false.
+
+=head2 Greylisting + automatic whitelisting
+
+Greylisting gets annoying if you do it for senders that are already known to retry. Thus it might be
+good to maintain a whitelist. You may use a suffix to your key, separated by "/". Once the greylist
+filter is passed, the used suffixes are registered with the whitelist.
+
+  t
+  |
+  0  a->b/x  # a->b never seen, suffix never seen: greylist
+  1  a->b/y  # a->b again: accept AND put x and y to the whitelist,
+  |          # as they are known to retry
+  2  c->b/x  # c->b unknown, but x is already whitelisted: accept
+  3  d->b/y  # d->b unknown, but y is already whitelisted: accept
+  |
+  v
+
+This can be implemented in your ACL as:
+
+    defer condition = ${perl{unseen}{<$sender_address>:$<local_part@$domain>/$sender_host_address}}
+
+But, if I<a> and I<b> are the sender and the recipient address, and the
+subkey is the sender host address, a spammer might send a forged message
+after t0, to get whitelisted.
+
 =head1 INTERNALS
 
 =head2 Format of the database