diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..1257657d9e1fd0e7989f748b7dad1737afc3f004
--- /dev/null
+++ b/README.md
@@ -0,0 +1,106 @@
+Postfix
+=========
+
+This role installs Postfix and allows basic configuration.
+
+Requirements
+------------
+
+This role requires Ansible 2.4 or higher.
+
+Role Variables
+--------------
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| postfix__recommended_packages | `[]` | Additional packages to install. These packages will have default configuration. |
+| postfix__mailname | `{{ ansible_fqdn }}` | The name of the mail system. |
+| postfix__tables | empty | Dictionaries used to build lookup tables. [Details below.](#postfix__tables) |
+| postfix__main_cf | `{}` | Used to modify or add lines in the main.cf file. [Details below.](#postfix__main_cf) |
+
+### `postfix__tables`
+
+This dictionary contains nested dictionaries that are used to build the lookup
+tables with the corresponding name. So `postfix__tables.transport` is used to
+build the transport lookup table, `postfix__tables.sasl_passwd` is used to build
+the SASL password map table, etc. Within each dictionary the 'key' is the lookup
+pattern and the 'value' is the returned value.
+
+For example, this `postfix__tables.transport` dictionary:
+
+```yaml
+postfix__tables:
+  transport:
+    'internal.domain.tld': ':'
+    '*': 'discard:'
+```
+
+would result in the following transport table:
+
+```
+internal.domain.tld :
+* discard:
+```
+
+This role currently only supports the transport lookup table and the SASL lookup
+table. More information on the transport table format can be found
+[here][transport-docs] and more information on the SASL passwords lookup table
+format can be found [here.][sasl-passwd-docs]
+
+### `postfix__main_cf`
+
+This dictionary is used to add or modify lines in the main.cf file. Each key
+corresponds to a parameter in main.cf, and the value is what the parameter
+should be set to. If the parameter already exists in the file, then that line
+will be replaced. Otherwise, a new line will be added at the end of the file.
+
+This dictionary is merged with the internal `postfix__main_cf_default`
+dictionary which defines some reasonable defaults, such as enabling
+opportunistic TLS for the SMTP client. All keys in `postfix__main_cf_default`
+can be overridden in `postfix__main_cf`.
+
+Example Playbooks
+----------------
+
+This example configures Postfix to accept mail on the loopback interface and
+relay it to Mailgun's SMTP servers. It also uses SASL + TLS to authenticate with
+Mailgun.
+
+```yaml
+- hosts: servers
+  tasks:
+    - include_role:
+        name: postfix
+      vars:
+        postfix__main_cf:
+          inet_interfaces: loopback-only
+          relayhost: '[smtp.mailgun.org]:587'
+          smtp_sasl_auth_enable: 'yes'
+          smtp_tls_security_level: encrypt
+          smtp_sasl_tls_security_options: noanonymous
+        postfix__tables:
+          sasl_passwd:
+            '[smtp.mailgun.org]:587': 'USERNAME:PASSWORD'
+```
+
+Another common configuration when doing development is to filter all mail so
+that only mail sent to your internal domain is actually sent. All other mail
+will be dropped silently to prevent accidentally sending emails when developing
+against real data. You can do that using transport maps
+
+```yaml
+- hosts: servers
+  tasks:
+    - include_role:
+        name: postfix
+      vars:
+        postfix__tables:
+          transport:
+            'internal.domain.tld': ':'
+            '*': 'discard:'
+```
+
+
+
+[transport-docs]: http://www.postfix.org/transport.5.html
+[sasl-passwd-docs]: http://www.postfix.org/SASL_README.html#client_sasl_sender