
[![Travis Build Status](https://travis-ci.org/Corion/Mail-URLFor.svg?branch=master)](https://travis-ci.org/Corion/Mail-URLFor)
[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/Corion/Mail-URLFor?branch=master&svg=true)](https://ci.appveyor.com/project/Corion/Mail-URLFor)

# NAME

Mail::URLFor - Create deep links into mail clients

# SYNOPSIS

    my $links = Mail::URLFor->new();

    my $messageid = 'mail.abcdef.123456@example.com';

    my $urls = $links->urls_for($messageid);

    for my $client (keys %$urls) {
        print "$client: $urls->{$client}\n";
    };

    # Output:
    # Thunderlink: thunderlink://messageid=mail.abcdef.123456%40example.com
    # OSX: message:%3Cmail.abcdef.123456@example.com%3E
    # RFC2392: mid:mail.abcdef.123456@example.com
    # Gmail: https://mail.google.com/mail/#search/rfc822msgid%3Amail.abcdef.123456%40example.com

# ONLINE DEMO

There is an online demo of the functionality at [http://corion.net/mail-urlfor.psgi](http://corion.net/mail-urlfor.psgi) .

Paste a valid message id into the input field and click on the appropriate link
to open the email in that mail client if the mail exists in that mail client.

# DESCRIPTION

This module allows you to create (clickable) URLs to emails that
will open in the respective (native) client or Gmail.

This is useful if you have a web application but still want to connect
an object on the web page with an email in a local mail client.

# METHODS

## `Mail::URLFor->new`

    # Only link to mails on Gmail
    my $links = Mail::URLFor->new(
        clients => [Mail::URLFor::Plugin::Gmail->new],
    );

### Options

- **clients**

    Arrayref of the classes (or instances) of mail clients to
    render links for.

    Defaults to all `::Plugin` classes.

## `->url_for( $rfc822messageid, $client = 'Gmail' )`

    my $url = $links->url_for( '1234.abc@example.com', 'Gmail' );
    print "<a href="$url">See mail</a>"

Renders the URL using the moniker of the plugin.

Returns something that should mostly be treated as an opaque string.
Returns `undef`, if the moniker is unknown.

Currently, the returned string is always
percent-encoded already, but this may change in the future.

## `->urls_for( $rfc822messageid )`

    my $urls = $links->urls_for( '1234.abc@example.com' );
    print $urls->{'Gmail'};

# REPOSITORY

The public repository of this module is
[http://github.com/Corion/Mail::URLFor](http://github.com/Corion/Mail::URLFor).

# SUPPORT

The public support forum of this module is
[https://perlmonks.org/](https://perlmonks.org/).

# BUG TRACKER

Please report bugs in this module via the RT CPAN bug queue at
[https://rt.cpan.org/Public/Dist/Display.html?Name=Mail-URLFor](https://rt.cpan.org/Public/Dist/Display.html?Name=Mail-URLFor)
or via mail to [mail-urlfor-Bugs@rt.cpan.org](https://metacpan.org/pod/mail-urlfor-Bugs@rt.cpan.org).

# AUTHOR

Max Maischein `corion@cpan.org`

# COPYRIGHT (c)

Copyright 2019 by Max Maischein `corion@cpan.org`.

# LICENSE

This module is released under the same terms as Perl itself.
