RFC 2368

The mailto URL scheme

📅 published July 1998, from ietf

RFC 2368: The mailto URL scheme 💌

Okay bestie, let's get into RFC 2368 🎀 It was written in July 1998 by P. Hoffman (Internet Mail Consortium), L. Masinter (Xerox Corporation), and J. Zawinski (Netscape Communications). It's a Standards Track doc, so this is the real deal, not just vibes ✨ It updates RFC 1738 and RFC 1808, and it's from the Network Working Group 🌸

Status of This Memo 📋

Okay so this doc is an Internet standards track protocol for the Internet community, and it's literally asking everyone to discuss it and send suggestions for making it better 🫶 If you want to know where this protocol stands in the standardization process, check the current edition of "Internet Official Protocol Standards" (STD 1). And distribution is unlimited, so share away 💅

Copyright (C) The Internet Society (1998). All Rights Reserved. 🦋

Abstract 🌈

This doc defines the format of Uniform Resource Locators (URLs) for pointing at electronic mail addresses 📧 It's part of a suite of documents that replace RFC 1738, 'Uniform Resource Locators', and RFC 1808, 'Relative Uniform Resource Locators'. The 'mailto' syntax from RFC 1738 gets extended so a URL can create more RFC 822 messages, because the URL can now describe extra header and body fields 🧚

1. Introduction 🌸

The mailto URL scheme is how you point at the Internet mailing address of a person or a service 💖 In its simplest form, a mailto URL is just an Internet mail address, nothing fancy.

But sometimes a resource needs more than just the address. It might need certain message headers or a message body too, so the mailto scheme got extended to let you set mail header fields and the message body ✨ Main character energy for URLs 👑

2. Syntax of a mailto URL 🎀

Following the syntax conventions of RFC 1738 [RFC1738], a "mailto" URL looks like this 💅

mailtoURL  =  "mailto:" [ to ] [ headers ]
to         =  #mailbox
headers    =  "?" header *( "&" header )
header     =  hname "=" hvalue
hname      =  *urlc
hvalue     =  *urlc

So "#mailbox" comes from RFC 822 [RFC822] 📮 That means it's zero or more comma-separated mail addresses, and they can include "phrase" and "comment" parts. Be careful here: every URL reserved character in "to" must be encoded, especially parentheses, commas, and the percent sign ("%"), since those show up a lot in mailbox syntax 🙈

The hname and hvalue pieces are the encoded forms of an RFC 822 header name and value. Same deal as to, all URL reserved characters have to be encoded 🍓

The special hname called body means the matching hvalue is the message body 💌 The body field should hold the content of the first text/plain body part of the message. Honestly, mailto is mostly meant for short text messages that get processed automatically, like "subscribe" requests for mailing lists, and not for full MIME bodies 🤖

Within mailto URLs, the characters "?", "=", and "&" are reserved 🔐

Here's a tricky one: since "&" (ampersand) is reserved in HTML, any mailto URL with an ampersand has to be written differently inside HTML than everywhere else. In an HTML document, a mailto URL must use "&" instead of "&" 🧁

Also, it's totally legal to specify both "to" and an hname whose value is "to". These all mean the same thing:

mailto:addr1%2C%20addr2

is equivalent to

mailto:?to=addr1%2C%20addr2

is equivalent to

mailto:addr1?to=addr2

And 8-bit characters in mailto URLs are forbidden 🚫 MIME encoded words (as defined in [RFC2047]) are allowed in header values, but not in any part of a "body" hname 🦋

3. Semantics and operations 🧚‍♀️

A mailto URL points at an "internet resource", which is the mailbox in the address 💗 When extra headers are included, it's still the same address, but now with an extra profile for accessing that resource. Some Internet resources can only be reached through email, but mailto is not meant for automatically fetching those things 🙅‍♀️

Here's the lowkey unusual part. With http URLs, resolving one causes an immediate back-and-forth between your client software and a host running an interactive server 🌐 Mailto is different, because resolving it doesn't trigger an immediate interaction at all. Instead, the client builds a message to the address with the header fields pre-filled as defaults ✏️ The user can edit it, send it as is, or just not send it, totally their choice 💅 How any URL scheme gets resolved isn't something the URL specifications dictate, so this is all fair game 🫶

4. Unsafe headers 🚨

Okay this is important, so listen up 👂 The user agent that interprets a mailto URL SHOULD choose not to create a message if any of the headers are considered dangerous. It can also choose to create a message with only some of the headers from the URL 💖 Only the Subject, Keywords, and Body headers are believed to be both safe and useful ✨

The creator of a mailto URL can't count on the resolver understanding anything beyond the "subject" and "body" headers 🙈 Clients that turn mailto URLs into mail messages should be able to correctly build RFC 822-compliant messages using just the "subject" and "body" headers 🎀

5. Encoding 🌷

RFC 1738 says a lot of characters in URLs have to be encoded 🔤 That affects mailto for some common characters you might find in addresses, headers, or message contents. One example is the space character (" ", ASCII hex 20). Check out the examples above that use %20 for spaces in the message body 🫧 Also, line breaks in the body of a message MUST be encoded with %0D%0A, no exceptions 🙅‍♀️

People writing mailto URLs need to be careful to encode any reserved characters they use, so that properly written URL interpreters can read them 💅 And client software that reads URLs has to be careful to decode the strings before building the mail message, so the message shows up in a form the recipient will understand. Those strings should get decoded before the user sees the message 👀

The mailto scheme is also limited because it doesn't support substitution of variables 🥲 So a message body that needs to include a user's email address can't be encoded using a mailto URL. This limitation also rules out mailto URLs that are signed with public keys and other variable information 🔑

9. References ✨

Okay bestie, here's the reading list 📚 Every spec the document leans on is listed here, with all its details, so you can go check them yourself 🤓

   [RFC822] Crocker, D., "Standard for the Format of ARPA Internet Text
            Messages", STD 11, RFC 822, August 1982.

   [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, Editors,
             "Uniform Resource Locators (URL)", RFC 1738, December 1994.

   [RFC1808] Fielding, R., "Relative Uniform Resource Locators", RFC
             1808, June 1995.

   [RFC2047] Moore, K., "MIME Part Three: Message Header Extensions for
             Non-ASCII Text", RFC 2047, November 1996.

A. Change from RFC 1738 🦋

Okay so RFC 1738 only gave us a super basic mailto, with no headers at all, just a plain addr-spec (not a full mailbox, bestie) 🙈 But people actually needed more, so the syntax grew into an extended version that includes more header fields. Iconic glow-up ✨

B. Acknowledgments 🫶

This document came from RFC 1738 and RFC 1808 [RFC1808], so the acknowledgments in those specs still apply. Give them credit, periodt 💜

The following people helped out with this memo, or had and discussed similar ideas for mailto. Main character energy, all of them 👑

  • Harald Alvestrand
  • Bryan Costales
  • Steve Dorner
  • Al Gilman
  • Mark Joseph
  • Laurence Lundblade
  • Keith Moore
  • Jacob Palme
  • Michael Patton

C. Author Contact Information 💌

Here's who wrote this thing and how to reach them 🧚 The contact details are copied exactly as they appear in the original:

   Paul E. Hoffman
   Internet Mail Consortium
   127 Segre Place
   Santa Cruz, CA  95060 USA

   EMail: phoffman@imc.org


   Larry Masinter
   Xerox Corporation
   3333 Coyote Hill Road
   Palo Alto, CA 94304 USA

   EMail: masinter@parc.xerox.com


   Jamie Zawinski
   Netscape Communications Corp.
   501 East Middlefield Road
   Mountain View, CA 94043 USA

   EMail: jwz@netscape.com

Copyright is held by The Internet Society (1998), and all rights are reserved 🌸 Here's the deal with sharing it. You can copy this document and pass it around, and you can make derivative works that comment on it, explain it, or help people implement it. You can publish and distribute those too, in whole or in part, with no real restrictions, as long as the copyright notice and this paragraph stay on every copy and derivative work 🔥

The document itself can't be modified in any way. You can't strip out the copyright notice or the references to the Internet Society or other Internet organizations. There are two exceptions. The first is for developing Internet standards, where the copyright procedures in the Internet Standards process have to be followed. The second is translating it into languages other than English 🌍

The limited permissions above are perpetual, and the Internet Society or its successors or assigns won't revoke them 💜

This document and the information in it is provided "AS IS", and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 💀
📦 where this page comes from