34 |
37 |
38 |
40 |
41 |
42 |
43 |
44 |
45 |
47 |
48 |
50 |
51 |
--------------------------------------------------------------------------------
/error.vue:
--------------------------------------------------------------------------------
1 |
31 |
32 |
33 |
34 |
37 |
38 |
39 |
41 |
42 |
43 |
44 |
45 |
46 |
47 |
49 |
50 |
52 |
53 |
--------------------------------------------------------------------------------
/content/2.getting-started/0.index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Getting Started
3 | description: ''
4 | position: 1.0
5 | category: Installation
6 | ---
7 |
8 | Postal is fairly easy to install but running your own mail server isn't something for
9 | everyone. If you use Postal, you will be responsible for configuring your DNS as well
10 | as maintaining the platform (including running upgrades). If this doesn't sound like
11 | something you're up for, try a hosted platform.
12 |
13 | The process for installing Postal is outlined below. When you're ready to get started
14 | go to the [Pre-Requisites](/getting-started/prerequisites) page.
15 |
16 | 1. Install Docker and other pre-requisites
17 | 2. Add appropriate configuration and DNS entries
18 | 3. Start Postal
19 | 4. Make your first user
20 | 5. Login to the web interface to create your first virtual mail server
21 |
22 | ## A visual learner?
23 |
24 | You can watch this video which walks through the installation process.
25 |
26 |
27 |
--------------------------------------------------------------------------------
/content/3.features/health-metrics.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Health & Metrics
3 | description: ''
4 | category: Features
5 | ---
6 |
7 | The Postal worker and SMTP server processes come with additional functionality that allows you to monitor the health of the process as well as look at live metrics about their performance.
8 |
9 | ## Port numbers
10 |
11 | By default, the health server listens on a different port for each type of process.
12 |
13 | * Worker - listens on port `9090`
14 | * SMTP server - listens on port `9091`
15 |
16 | Unlike other services, if these ports are in use when the process starts, the health server will simply not start but the rest of the process will run as normal. This will be shown in the logs.
17 |
18 | To configure these ports you can set the `HEALTH_SERVER_PORT` and `HEALTH_SERVER_BIND_ADDRESS` environment variables.
19 |
20 | ## Metrics
21 |
22 | The metrics are exposed at `/metrics` and are in a standard Prometheus exporter format. This means they can be scraped by any tool that can ingest Prometheus metrics. This will then allow them to be turned in to graphs as appropriate.
23 |
24 | ## Health checks
25 |
26 | The `/health` endpoint will return "OK" when the process is running. This can be used for health check monitoring.
27 |
--------------------------------------------------------------------------------
/content/4.developer/2.client-libraries.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Client Libraries
3 | description: ''
4 |
5 | ---
6 |
7 | There are a number of client libraries available to help send e-mail using the Postal platform. These aren't all developed by the Postal team.
8 |
9 | * [Ruby](https://github.com/postalserver/postal-ruby)
10 | * [Rails](https://github.com/postalserver/postal-rails)
11 | * [Ruby (mail gem)](https://github.com/postalserver/postal-mailgem)
12 | * [PHP](https://github.com/postalserver/postal-php)
13 | * [Node](https://github.com/postalserver/postal-node)
14 | * [Java](https://github.com/matthewmgamble/postal-java)
15 | * [.Net](https://github.com/KingdomFirst/PostalServer-DotNet-Framework)
16 | * [.NET Core](https://github.com/mDev86/PostalApiClient)
17 | * [Go](https://github.com/Pacerino/postal-go)
18 | * [Elixir (via Swoosh)](https://hexdocs.pm/swoosh/Swoosh.Adapters.Postal.html)
19 | * [Drupal](https://www.drupal.org/project/postal_mail)
20 | * [Python](https://github.com/regenara/postal_py)
21 |
22 | All of these libraries will make use of the API rather than using any SMTP protocol - this is considered to be best approach for delivering your messages.
23 |
24 | If your framework makes use of SMTP, you do not need a client library however you will also miss out on some of Postals functionality.
25 |
--------------------------------------------------------------------------------
/components/Header.vue:
--------------------------------------------------------------------------------
1 |
8 |
9 |
10 | 54 | 55 |
62 |
66 |
67 | /opt/postal/config as /config so any full directory paths mentioned in postal.yml will likely need to start with /config and not /opt/postal/config
30 | ::
31 |
32 | ## Initializing the database
33 |
34 | Once you've added your configuration, you need to initialize your database by adding all the appropriate tables. Run the following commands to create the schema and then create your first admin user.
35 |
36 | ```bash
37 | postal initialize
38 | postal make-user
39 | ```
40 |
41 | ## Running postal
42 |
43 | You're now ready to actually run Postal itself. You can go ahead and do this by running:
44 |
45 | ```
46 | postal start
47 | ```
48 |
49 | This will run a number of containers on your machine. You can use `postal status` to see details of these components.
50 |
51 | ## Caddy
52 |
53 | To handle SSL termination and all web traffic, you'll need to configure a web proxy. You can use anything that takes your fancy here - nginx, Apache, HAProxy, anything - but in this example, we're going to use [Caddy](https://caddyserver.com). It's a great little server that requires very little configuration and is very easy to set up.
54 |
55 | ```
56 | docker run -d \
57 | --name postal-caddy \
58 | --restart always \
59 | --network host \
60 | -v /opt/postal/config/Caddyfile:/etc/caddy/Caddyfile \
61 | -v /opt/postal/caddy-data:/data \
62 | caddy
63 | ```
64 |
65 | Once this has started, Caddy will issue an SSL certificate for your domain and you'll be able to immediately access the Postal web interface and login with the user you created in one of the previous steps.
66 |
67 | 
68 |
--------------------------------------------------------------------------------
/content/4.developer/3.http-payloads.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Receiving e-mail by HTTP
3 | description: ''
4 |
5 | ---
6 |
7 | One of the most useful features in Postal is the ability to have incoming messages delivered to your own application as soon as they arrive. To receive incoming messages from Postal you can set it up to pass them to an HTTP URL of your choosing.
8 |
9 | Each endpoint has an HTTP URL (we highly recommend making use of HTTPS where possible) as well as a set of rules which defines how data is sent to you.
10 |
11 | * You can choose whether data is encoded as normal form data or whether Postal sends JSON as the body of the request.
12 | * You can choose whether to receive the raw message (raw) or have it as a JSON dictionary (processed).
13 | * You can choose whether you'd like replies and signatures to be separated from the plain body of the message.
14 |
15 | Your server should accept Postals incoming request and reply within 5 seconds. If it takes longer than this, Postal will assume it has failed and the request will be retried. Your server should send a `200 OK` status to signal to Postal that you've received the request.
16 |
17 | Messages will be tried up to 18 times with an exponential back-off until a successful response is seen except in the case of `5xx` statuses which will fail immediately.
18 |
19 | When a message permanently fails to be delivered to your endpoint (i.e. the server returned a 5xx status code or it wasn't accepted after 18 attempts), the recipient will be sent a bounce message.
20 |
21 | You can view the attempts (along with debugging information) on the message page in the web interface.
22 |
23 | ## The processed payload
24 |
25 | When you chose to receive the message as JSON (processed), you'll receive a payload with the following attributes.
26 |
27 | ```javascript
28 | {
29 | "id":12345,
30 | "rcpt_to":"sales@awesomeapp.com",
31 | "mail_from":"test@example.com",
32 | "token":"rtmuzogUauKN",
33 | "subject":"Re: Welcome to AwesomeApp",
34 | "message_id":"81026759-68fb-4872-8c97-6dd2901cb33a@rp.postal.yourdomain.com",
35 | "timestamp":1478169798.924355,
36 | "size":"822",
37 | "spam_status":"NotSpam",
38 | "bounce":false,
39 | "received_with_ssl":false,
40 | "to":"sales@awesomeapp.com",
41 | "cc":null,
42 | "from":"John Doe Hello there!
", 48 | "auto_submitted":"auto-reply", 49 | "attachment_quantity":1, 50 | "attachments":[ 51 | { 52 | "filename":"test.txt", 53 | "content_type":"text/plain", 54 | "size":12, 55 | "data":"SGVsbG8gd29ybGQh" 56 | } 57 | ] 58 | } 59 | ``` 60 | 61 | * You will only have the `attachments` attribute if you have enabled it. 62 | * The `data` attribute for each attachment is Base64 encoded. 63 | 64 | ## The raw message payload 65 | 66 | When you choose to receive the full message, you will receive the following attributes. 67 | 68 | ```javascript 69 | { 70 | "id":12345, 71 | "message":"REtJTS1TaWduYXR1cmU6IHY9MTsgYT1yc2Etc2hhMjU2Oy...", 72 | "base64":true, 73 | "size":859 74 | } 75 | ``` 76 | 77 | * The `base64` attribute specifies whether or not the `message` attribute is encoded with Base64. This is likely to be true all the time. 78 | -------------------------------------------------------------------------------- /content/4.developer/1.api.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Using the API 3 | description: '' 4 | 5 | --- 6 | The HTTP API allows you to send messages to us using JSON over HTTP. You can either talk to the API using your current HTTP library or you can use one of the pre-built libraries. 7 | 8 | [Full API documentation](https://apiv1.postalserver.io) 9 | 10 | ::callout{icon="i-heroicons-information-circle"} 11 | This API does not support managing all the functions of Postal. There are plans to introduce a new v2 API which will have more functionality and significantly better documentation. We do not have an ETA for this. Additionally, we will not be accepting any pull requests to extend the current API to have any further functionality than it currently does. 12 | :: 13 | 14 | ## General API Instructions 15 | 16 | * You should send POST requests to the URLs shown below. 17 | * Parameters should be encoded in the body of the request and `application/json` should be set as the `Content-Type` header. 18 | * The response will always be provided as JSON. The status of a request can be determined from the `status` attribute in the payload you receive. It will be `success` or `error`. Further details can be found in the `data` attribute. 19 | 20 | An example response body is shown below: 21 | 22 | ```javascript 23 | { 24 | "status":"success", 25 | "time":0.02, 26 | "flags":{}, 27 | "data":{"message_id":"xxxx"} 28 | } 29 | ``` 30 | 31 | To authenticate to the API you'll need to create an API credential for your mail server through the web interface. This is a random string which is unique to your server. 32 | 33 | To authenticate a request to the API, you need to pass this key in the `X-Server-API-Key` HTTP header. 34 | 35 | ## Sending a message 36 | 37 | There are two ways to send a message - you can either provide each attribute needed for the e-mail individually or you can craft your own RFC 2822 message and send this instead. 38 | 39 | Full details about these two methods can be found in our API documentation: 40 | 41 | * [Sending a message](https://postalserver.github.io/postal-api/controllers/send/message) 42 | * [Sending an RFC 2822 message](https://postalserver.github.io/postal-api/controllers/send/raw) 43 | 44 | For both these methods, the API will return the same information as the result. It will contain the `message_id` of the message that was sent plus a `messages` hash with the IDs of the messages that were sent by the server to each recipient. 45 | 46 | ```javascript 47 | { 48 | "message_id":"message-id-in-uuid-format@rp.postal.yourdomain.com", 49 | "messages":{ 50 | "john@example.com":{"id":37171, "token":"a4udnay1"}, 51 | "mary@example.com":{"id":37172, "token":"bsfhjsdfs"} 52 | } 53 | } 54 | ``` 55 | 56 | ## GET Message 57 | 58 | To retrieve a message and its contents, use the `GET` method with the `id` (received when sending the message) and `_expansions` parameters (if you need more information than the basics) for the message from Postal. For more details, refer to the [Postal API documentation](https://postalserver.github.io/postal-api/controllers/messages/message.html). 59 | 60 | ```json 61 | { 62 | "id": 14, 63 | "_expansions": true 64 | } 65 | ``` 66 | 67 | ### Example cURL Request 68 | 69 | You can use the following cURL command to make the request: 70 | 71 | ```bash 72 | curl --location 'https://
25 |
44 |
45 |
46 | NVM Setup
26 | 27 | **Change to the project directory** 28 | ```bash 29 | cd /path/to/postal-docs 30 | ``` 31 | 32 | **Install the correct Node version** 33 | ```bash 34 | nvm install 35 | ``` 36 | 37 | **Use the correct Node version** 38 | ```bash 39 | nvm use 40 | ``` 41 | 42 | 43 |
47 |
48 |
59 |
60 |
61 |
62 |
63 | ### Prepare Your System
64 |
65 |
66 | **Change to the project directory**
67 | ```bash
68 | cd /path/to/postal-docs
69 | ```
70 | ### Install Dependencies
71 | Install the Node dependencies using PNPM.
72 | ```bash
73 | pnpm install
74 | ```
75 | ### Start the Development Web Server
76 | Start the development server on http://localhost:3000
77 |
78 | > [!NOTE]
79 | > If you see a warning about a "Missing `NUXT_UI_PRO_LICENSE`", you can ignore that message. This is only used in production.
80 |
81 | ```bash
82 | pnpm dev
83 | ```
84 |
85 | Your local development environment is now running. You can view the site at http://localhost:3000. Any changes you make to the content will be automatically reflected in the browser once you save the file.
86 |
87 | ## How to Edit the Docs Content?
88 | This documentation uses [Nuxt Content](https://content.nuxtjs.org/) and works on the following key concepts:
89 | - Content is stored as markdown files in the `/content` folder.
90 | - Pages are sorted by the number at the beginning of their MD file.
91 | - Pages need to have a title and description as their metadata.
92 | - You can use any Nuxt UI and [Nuxt UI Pro prose component](https://ui.nuxt.com/pro/prose/callout).
93 |
94 |
95 | #### Example:
96 | ```
97 | ---
98 | title: Feature List
99 | description: 'This is a list of features (in no particular order) of things that Postal can do.'
100 | ---
101 |
102 | # Feature List
103 | Here you can write your content.
104 | ...
--------------------------------------------------------------------------------
/pages/index.vue:
--------------------------------------------------------------------------------
1 |
23 |
24 |
25 | Enable PNPM
49 | 50 | ### Corepack 51 | 52 | PNPM is available by default; you just need to enable corepack. 53 | 54 | ```bash 55 | corepack enable pnpm 56 | ``` 57 | 58 |
26 |
50 |
51 |
57 |
58 |
59 |
80 |
81 |
--------------------------------------------------------------------------------
/content/3.features/click-and-open-tracking.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Click & Open Tracking
3 | description: ''
4 | category: Features
5 | ---
6 |
7 | Postal supports tracking opens and clicks from e-mails. This allows you to see when people open messages or they click links within them.
8 |
9 | 27 | Postal v3 is now available — upgrade by following our upgrade guide 28 |
29 | 30 |
31 |
48 |
49 |
32 |
47 |
33 |
34 |
43 | 
35 | Postal is a complete and fully featured mail delivery platform for use by websites & web servers. 36 | Think Sendgrid, Mailgun or Postmark but open source and ready for you to run on your own servers. 37 |
38 |
39 |
42 |
44 | 
45 |
46 |
45 |
60 |
79 | The Postal project is supported by
61 | 73 |74 | If you want to help support this project, please get in touch with the team. A good place to start is 75 | Discord otherwise drop an e-mail to 76 | team@postalserver.io.
77 | 78 |
10 |
11 |
12 | ## How it works
13 |
14 | Once enabled, Postal will automatically scan your outgoing messages and replace any links and images with new URLs that go via your Postal web server. When the link is clicked, Postal will log the click and redirect to the user to the original URL automatically. The links that are included in the e-mail should be on the same domain as the sender and therefore you need to configure a subdomain like `click.yourdomain.com` and point it to your Postal server.
15 |
16 | ## Configuring your web server
17 |
18 | To avoid messages being marked as spam, it's important that the subdomain that Postal uses in the re-written URLs is on the same domain as that sending the message. This means if you are sending mail from `yourdomain.com`, you'll need to setup `click.yourdomain.com` (or whatever you choose) to point to your Postal server.
19 |
20 | There are two ways how to achive that traffic to `click.yourdomain.com` will reach Postal:
21 | 1. Adding CNAME record for `click.yourdomain.com` to previously configured `track.postal.example.com` followed by Caddy additional configuration.
22 | 2. Configuring custom proxy for `click.yourdomain.com` on your webserver.
23 |
24 | ### Additional Caddy configuration
25 |
26 | If you used Caddy as proxy for overall Postal traffic it easy to add additional proxy its config `/opt/postal/config/Caddyfile`:
27 |
28 | ```
29 | # ... previous content
30 |
31 | click.yourdomain.com {
32 | reverse_proxy 127.0.0.1:5000 {
33 | header_up X-Postal-Track-Host "1"
34 | }
35 | }
36 | ```
37 |
38 | After saving this new configuration restart Caddy, for example if you're using docker, you may be able to `docker restart postal-caddy`.
39 |
40 | After this you should see `Hello.` on `click.yourdomain.com` and SSL should work out of the box.
41 |
42 | ### Custom proxy on webserver
43 |
44 | You'll need to add an appropriate virtual host on your web server that proxies traffic from that domain to the Postal web server. The web server must add the `X-Postal-Track-Host: 1` header so the Postal web server knows to treat requests as tracking requests.
45 |
46 | Once you have configured this, you should be able to visit your chosen domain in a browser and see `Hello.` printed back to you. If you don't see this, review your configuration until you do. If you still don't see this and you enable the tracking, your messages will be sent with broken links and images.
47 |
48 | ### Setting up tracking domain
49 |
50 | If you're happy things are working, you can enable tracking as follows:
51 | 1. Find the web server you wish to enable tracking on in the Postal web interface
52 | 2. Go to the **Domains** item
53 | 3. Select **Tracking Domains**
54 | 4. Click **Add a tracking domain**
55 | 5. Enter the domain that you have configured and choose the configuration you want to use. It is **highly** recommended that you use SSL for these connections. Anything else is likely to cause problems with reputation and user experience.
56 |
57 | ## Disabling tracking on a per e-mail basis
58 |
59 | If you don't wish to track anything in an email you can add a header to your e-mails before sending it.
60 |
61 | ```text
62 | X-AMP: skip
63 | ```
64 |
65 | ## Disabling tracking for certain link domains
66 |
67 | If there are certain domains you don't wish to track links from, you can define these on the tracking domain settings page. For example, if you list `yourdomain.com` no links to this domain will be tracked.
68 |
69 | ## Disabling tracking on a per link basis
70 |
71 | If you wish to disable tracking for a particular link, you can do so by inserting `+notrack` as shown below. The `+notrack` will be removed leaving a plain link.
72 |
73 | * `https+notrack://postalserver.io`
74 | * `http+notrack://katapult.io/signup`
75 |
--------------------------------------------------------------------------------
/content/5.other/2.containers.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Our container image
3 | description: ""
4 | ---
5 |
6 | This page contains information about how Postal actually is packaged and run within a container.
7 |
8 | ## Where's the container?
9 |
10 | Postal is packaged and hosted at `ghcr.io/postalserver/postal`.
11 |
12 | The `latest` tag will always track the `main` branch within the repository and therefore will have the latest copy of the application. It is not recommended to use this tag in production because you may start using it at any time without noticing.
13 |
14 | Each version of Postal will also be tagged, for example, `3.0.0`. We always recommend using a version tag in production. To upgrade, you simply need to start using the newer version of the container and be sure to run the `upgrade` command. You can view all the tags which exist [on GitHub](https://github.com/postalserver/postal/pkgs/container/postal) and in [our CHANGELOG](https://github.com/postalserver/postal/blob/main/CHANGELOG.md).
15 |
16 | ## What processes need to run?
17 |
18 | There are 3 processes that need to be running for a successful Postal installation. All processes are run within the same image (`ghcr.io/postalserver/postal`). The table below identifies the processes.
19 |
20 | ### The web server
21 |
22 | - **Command:** `postal web-server`
23 | - **Ports:** 5000
24 |
25 | This is the main web server that handles all web traffic for Postal's admin interface and open/click tracking requests. By default, it listens on port 5000 but this can be configured in the `postal.yml` file by changing the `web_server.default_port` option or setting the `PORT` environment variable.
26 |
27 | You can run multiple web servers and load balance between them to add additional capacity for web requests.
28 |
29 | ### The SMTP server
30 |
31 | - **Command:** `postal smtp-server`
32 | - **Ports:** 25
33 | - **Capabilities required:** `NET_BIND_SERVICE`
34 |
35 | This is the main SMTP server for receiving messages from clients and other MTAs. As with the web server, you can configure this to run on any port by changing the `smtp_server.default_port` option in the `postal.yml` config file or setting the `PORT` environment variable.
36 |
37 | You can run multiple SMTP servers and load balance between them to add additional capacity for SMTP connections.
38 |
39 | ### The worker(s)
40 |
41 | - **Command:** `postal worker`
42 |
43 | This runs a worker which will receive jobs from the message queue. Essentially, this handles processing all incoming and outgoing e-mail. If you're needing to process lots of e-mails, you may wish to run more than one of these. You can run as many of these as you wish.
44 |
45 | ## Configuration
46 |
47 | The image expects all configuration to be mounted at `/config`. At a minimum, this directory must contain a `postal.yml` and a `signing.key`. You can see a minimal example `postal.yml` in the [installation tool repository](https://github.com/postalserver/install/blob/main/examples/postal.v3.yml). For a full example, [see here](https://github.com/postalserver/postal/blob/main/doc/config/yaml.yml).
48 |
49 | The `signing.key` can be generated using the following command:
50 |
51 | ```
52 | openssl genrsa -out path/to/signing.key 2048
53 | ```
54 |
55 | ## Networking
56 |
57 | If you wish to utilise IP pools, you will need to run Postal using host networking. This is because Postal will need to be able to determine which physical IPs are available to it and be able to send and receive traffic on those IPs.
58 |
59 | If you are not using IP pools, there is no need to use host networking and you can expose the ports listed above as appropriate.
60 |
61 | ## Waiting for services
62 |
63 | The container's entrypoint supports waiting for external services to be ready before starting the underlying process. To use this you need to set the `WAIT_FOR_TARGETS` environment variable with a list of services and ports. For example, `mariadb:3306`, replacing `mariadb` with the hostname or IP of your MariaDB server. You can specify multiple endpoint by separating them with a space.
64 |
65 | The default maximum time to wait is 30 seconds, you can override this using the `WAIT_FOR_TIMEOUT` environment variable.
66 |
--------------------------------------------------------------------------------
/content/3.features/oidc.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: OpenID Connect
3 | description: ''
4 | category: Features
5 | ---
6 |
7 | Postal supports OpenID Connect (OIDC) allowing you to delegate authentication to an external service. When enabled, there are various changes:
8 |
9 | * You are not required to enter a password when you add new users.
10 | * When a user first logs in with OIDC, they will be matched to a local user based on their e-mail address.
11 | * On subsequent logins, the user will be matched based on their unique identifier provided by the OIDC issuer.
12 | * Users without local passwords cannot reset their password through Postal.
13 | * Users cannot change their local password when associated with an OIDC identity.
14 | * Existing users that currently have a password will continue to be able to use that password until it is linked with an OIDC identity.
15 |
16 | 
17 |
18 | ## Configuration
19 |
20 | To get started, you'll need to find an OpenID Connect enabled provider. You should create your application within the provider in order to obtain a identifier (client ID) and a secret (client secret).
21 |
22 | You may be prompted to provide a "redirect URI" during this process. You should enter `https://postal.yourdomain.com/auth/oidc/callback`.
23 |
24 | Finally, you'll need to place your configuration in the Postal config file as normal.
25 |
26 | ```yaml
27 | oidc:
28 | # Start by enabling OIDC for your installation.
29 | enabled: true
30 |
31 | # The name of the OIDC provider as shown in the UI. For example:
32 | # "Login with My Proivder".
33 | name: My Provider
34 |
35 | # The OIDC issuer URL provided to you by your Identity provider.
36 | # The provider must support OIDC Discovery by hosting their configuration
37 | # at https://identity.example.com/.well-known/openid-configuration.
38 | issuer: https://identity.example.com
39 |
40 | # The client ID for OIDC
41 | identifier: abc1234567890
42 |
43 | # The client secret for OIDC
44 | secret: zyx0987654321
45 |
46 | # Scopes to request from the OIDC server. You'll need to find these from your
47 | # provider. You should ensure you request enough scopes to ensure the user's
48 | # email address is returned from the provider.
49 | scopes:
50 | - openid
51 | - email
52 | ```
53 |
54 | If your Identity Provider does not support OpenID Connect discovery (which is enabled by default, you can manually configure it.) For full details of the options available see the [example config file](https://github.com/postalserver/postal/blob/main/doc/config/yaml.yml).
55 |
56 | By default, Postal will look for an email address in the `email` field and a name in the `name` field. These can be overriden using configuration if these values can be found elsewhere.
57 |
58 | ## Logging in
59 |
60 | Once enabled, you can log in by pressing the **Login with xxx** button on the login page. This will direct you to your chosen identity provider. Once authorised, you will be directed back to the application. If a user exists matching the e-mail address returned by the OpenID provider, it will be linked and you will be logged in. If not, an error will be displayed.
61 |
62 | ## Debugging
63 |
64 | Details about the user matching process will be displayed in the web server logs when the callback from the Identity provider happens.
65 |
66 | ## Disabling local authentication
67 |
68 | Once you have established your OpenID Connect set up, you can fully disable local authentication. This will change the login page as well as user management options.
69 |
70 | ```yaml
71 | oidc:
72 | # ...
73 | local_authentication_enabled: false
74 | ```
75 |
76 | ## Using Google as an identity provider
77 |
78 | Setting up Postal to authenticate with Google is fairly straight forward. You'll need to use the Google Cloud console to generate a client ID and secret ([see docs](https://developers.google.com/identity/openid-connect/openid-connect)). When prompted for a redirect URI, you should be `https://postal.yourdomain.com/auth/oidc/callback`. The following configuration can be used to enable this:
79 |
80 | ```yaml
81 | oidc:
82 | enabled: true
83 | name: Google
84 | issuer: https://accounts.google.com
85 | identifier: # your client ID from Google
86 | secret: # your client secret from Google
87 | scopes: [openid, email]
88 | ```
89 |
--------------------------------------------------------------------------------
/content/2.getting-started/1.prerequisites.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Pre-requisites
3 | description: ''
4 | position: 2.0
5 | category: Installation
6 | ---
7 |
8 | There are some things you'll need to do before you can install Postal.
9 |
10 | ## Servers
11 |
12 | We **strongly** recommend installing Postal on its own dedicated server (i.e. a server running no other software). The minimum specification for Postal is as follows:
13 |
14 | * At least 4GB of RAM
15 | * At least 2 CPU cores
16 | * An appropriate amount of disk space (at least 25GB) for your use case
17 |
18 | Most people install Postal on virtual servers. There are lots of providers to choose from including [Digital Ocean](https://m.do.co/c/17696597a9ed) and [Linode](https://www.linode.com) however you may find that the IP address given to you is already on blocklists so it may take additional testing to find a provider that is right for you.
19 |
20 | One thing to be aware of is you'll need to ensure that your provider does not block port 25 outbound. This is quite common and is used to prevent abuse from spammers.
21 |
22 | It doesn't matter what operating system you choose as long as you are able to install Docker on it (see next section). Nothing in these instructions will make assumptions about your operating system.
23 |
24 | ## Docker
25 |
26 | Postal runs entirely using containers which means to run Postal you'll need some software to run these containers. We recommend using Docker for this purpose but you can use whatever software you wish.
27 |
28 | You'll need to install Docker Engine on your server to begin with. [Follow the instructions on the Docker website](https://docs.docker.com/engine/install/) to install Docker.
29 |
30 | You'll also need to ensure you have the [Docker Compose plugin](https://docs.docker.com/compose/install/linux/) installed.
31 |
32 | Before continuing ensure that you can run both `docker` and `docker compose` from your prompt.
33 |
34 | ## System utilities
35 |
36 | There are a few system utilities that you need to have installed before you'll be able to run some of the Postal commands.
37 |
38 | On Ubuntu/Debian:
39 |
40 | ```
41 | apt install git curl jq
42 | ```
43 |
44 | On CentOS/RHEL:
45 |
46 | ```
47 | yum install git curl jq
48 | ```
49 |
50 | ## Git & installation helper repository
51 |
52 | You'll need to make sure you have `git` installed on your server. You'll then need to clone the Postal installation helper repository. This contains some bootstrapping config and other useful things which will speed along your installation.
53 |
54 | ```
55 | git clone https://github.com/postalserver/install /opt/postal/install
56 | sudo ln -s /opt/postal/install/bin/postal /usr/bin/postal
57 | ```
58 |
59 | ## MariaDB (10.6 or higher)
60 |
61 | Postal requires a database engine to store all email and other essential configuration data. You will need to provide credentials that allow full access to create and delete databases as well as having full access to any databases created. Postal will provision a database automatically for each mail server that you create.
62 |
63 | We do not support using MySQL in place of MariaDB.
64 |
65 | You can run MariaDB in a container, assuming you have Docker, using this command:
66 |
67 | ```
68 | docker run -d \
69 | --name postal-mariadb \
70 | -p 127.0.0.1:3306:3306 \
71 | --restart always \
72 | -e MARIADB_DATABASE=postal \
73 | -e MARIADB_ROOT_PASSWORD=postal \
74 | mariadb
75 | ```
76 |
77 | * This will run a MariaDB instance and have it listen on port 3306.
78 | * Be sure to choose a secure password. You'll need to put this in your Postal configuration when you install it so be sure to make a (secure) note of it.
79 | * If you are unable or unwilling to grant root access, the database user you create separately needs all permissions on databases called `postal` and `postal-*` (this prefix can be configured in the `message_db` part of your configuration).
80 |
81 | ::callout{icon="i-heroicons-information-circle"}
82 | Whilst you can configure the maximum message size however you wish, you will need to verify that MariaDB is configured with innodb_log_file_size to at least 10 times the biggest message you wish to send (150MB for 15MB email, 250MB for 25MB email, etc).If you have a legacy v1 database you might also want to check that raw tables in the database have the type
LONGBLOB.
83 | ::
84 |
--------------------------------------------------------------------------------
/public/supporters/krystal-dark.svg:
--------------------------------------------------------------------------------
1 |
20 |
--------------------------------------------------------------------------------
/public/supporters/krystal-light.svg:
--------------------------------------------------------------------------------
1 |
20 |
--------------------------------------------------------------------------------
/content/4.developer/4.webhooks.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Webhooks
3 | description: ''
4 |
5 | ---
6 |
7 | Postal supports sending webhooks over HTTP when various events occur during the lifecycle of a message.
8 |
9 | This page lists all the different types of event along with an example JSON payload that you'll receive. In many cases, only a small amount of information will be sent, if you require more information you should use the API to obtain it.
10 |
11 | ## Message Status Events
12 |
13 | These events are triggered on various events in an e-mail's lifecycle. The payload format is identical for all messages however the `status` attribute may change. The following statuses may be delivered.
14 |
15 | * `MessageSent` - when a message is successfully delivered to a recipient/endpoint.
16 | * `MessageDelayed` - when a message's delivery has been delayed. This will be sent each time Postal attempts a delivery and a message is delayed further.
17 | * `MessageDeliveryFailed` - when a message cannot be delivered.
18 | * `MessageHeld` - when a message is held.
19 |
20 | ```javascript
21 | {
22 | "status":"Sent",
23 | "details":"Message sent by SMTP to aspmx.l.google.com (2a00:1450:400c:c0b::1b) (from 2a00:67a0:a:15::2)",
24 | "output":"250 2.0.0 OK 1477944899 ly2si31746747wjb.95 - gsmtp",
25 | "time":0.22,
26 | "sent_with_ssl":true,
27 | "timestamp":1477945177.12994,
28 | "message":{
29 | "id":12345,
30 | "token":"abcdef123",
31 | "direction":"outgoing",
32 | "message_id":"5817a64332f44_4ec93ff59e79d154565eb@app34.mail",
33 | "to":"test@example.com",
34 | "from":"sales@awesomeapp.com",
35 | "subject":"Welcome to AwesomeApp",
36 | "timestamp":1477945177.12994,
37 | "spam_status":"NotSpam",
38 | "tag":"welcome"
39 | }
40 | }
41 | ```
42 |
43 | ## Message Bounces
44 |
45 | If Postal receives a bounce message for a message that was previously accepted, you'll receive the `MessageBounced` event.
46 |
47 | ```javascript
48 | {
49 | "original_message":{
50 | "id":12345,
51 | "token":"abcdef123",
52 | "direction":"outgoing",
53 | "message_id":"5817a64332f44_4ec93ff59e79d154565eb@app34.mail",
54 | "to":"test@example.com",
55 | "from":"sales@awesomeapp.com",
56 | "subject":"Welcome to AwesomeApp",
57 | "timestamp":1477945177.12994,
58 | "spam_status":"NotSpam",
59 | "tag":"welcome"
60 | },
61 | "bounce":{
62 | "id":12347,
63 | "token":"abcdef124",
64 | "direction":"incoming",
65 | "message_id":"5817a64332f44_4ec93ff59e79d154565eb@someserver.com",
66 | "to":"abcde@psrp.postal.yourdomain.com",
67 | "from":"postmaster@someserver.com",
68 | "subject":"Delivery Error",
69 | "timestamp":1477945179.12994,
70 | "spam_status":"NotSpam",
71 | "tag":null
72 | }
73 | }
74 | ```
75 |
76 | ## Message Click Event
77 |
78 | If you have click tracking enabled, the `MessageLinkClicked` event will tell you that a user has clicked on a link in one of your e-mails.
79 |
80 | ```javascript
81 | {
82 | "url":"https://atech.media",
83 | "token":"VJzsFA0S",
84 | "ip_address":"185.22.208.2",
85 | "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36",
86 | "message":{
87 | "id":12345,
88 | "token":"abcdef123",
89 | "direction":"outgoing",
90 | "message_id":"5817a64332f44_4ec93ff59e79d154565eb@app34.mail",
91 | "to":"test@example.com",
92 | "from":"sales@awesomeapp.com",
93 | "subject":"Welcome to AwesomeApp",
94 | "timestamp":1477945177.12994,
95 | "spam_status":"NotSpam",
96 | "tag":"welcome"
97 | }
98 | }
99 | ```
100 |
101 | ## Message Loaded/Opened Event
102 |
103 | If you have open tracking enabled, the `MessageLoaded` event will tell you that a user has opened your e-mail (or, at least, have viewed the tracking pixel embedded within it.)
104 |
105 | ```javascript
106 | {
107 | "ip_address":"185.22.208.2",
108 | "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36",
109 | "message":{
110 | "id":12345,
111 | "token":"abcdef123",
112 | "direction":"outgoing",
113 | "message_id":"5817a64332f44_4ec93ff59e79d154565eb@app34.mail",
114 | "to":"test@example.com",
115 | "from":"sales@awesomeapp.com",
116 | "subject":"Welcome to AwesomeApp",
117 | "timestamp":1477945177.12994,
118 | "spam_status":"NotSpam",
119 | "tag":"welcome"
120 | }
121 | }
122 | ```
123 |
124 | ## DNS Error Event
125 |
126 | Postal regularly monitors domains it knows about to ensure that your SPF/DKIM/MX records are correct. If you'd like to be notified when the checks fail, you can subscribe to the `DomainDNSError` event.
127 |
128 | ```javascript
129 | {
130 | "domain":"example.com",
131 | "uuid":"820b47a4-4dfd-42e4-ae6a-1e5bed5a33fd",
132 | "dns_checked_at":1477945711.5502,
133 | "spf_status":"OK",
134 | "spf_error":null,
135 | "dkim_status":"Invalid",
136 | "dkim_error":"The DKIM record at example.com does not match the record we have provided. Please check it has been copied correctly.",
137 | "mx_status":"Missing",
138 | "mx_error":null,
139 | "return_path_status":"OK",
140 | "return_path_error":null,
141 | "server":{
142 | "uuid":"54529725-8807-4069-ab29-a3746c1bbd98",
143 | "name":"AwesomeApp Mail Server",
144 | "permalink":"awesomeapp",
145 | "organization":"atech"
146 | },
147 | }
148 | ```
149 |
--------------------------------------------------------------------------------
/content/2.getting-started/4.dns-configuration.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: DNS configuration
3 | description: ''
4 | position: 2.3
5 | category: Installation
6 | ---
7 | To work properly, you'll need to configure a number of DNS records for your Postal installation. Review the table below and create appropriate DNS records with your DNS provider. You will need to enter the record names you choose in your `postal.yml` configuration file.
8 |
9 | We'll assume for the purposes of this documentation you have both IPv4 and IPv6 available to your server. We'll use the following values in this documentation, you'll need to replace them as appropriate.
10 |
11 | * `192.168.1.3` - IPv4 address
12 | * `2a00:1234:abcd:1::3` - IPv6 address
13 | * `postal.example.com` - the hostname you wish to use to run Postal
14 |
15 | ## A Records
16 |
17 | You'll need these records for accessing the API, management interface & SMTP server.
18 |
19 | | Hostname | 23 |Type | 24 |Value 25 | |
|---|---|---|
| postal.example.com | 30 |A | 31 |192.168.1.3 |
32 |
| postal.example.com | 35 |AAAA | 36 |2a00:1234:abcd:1::3 |
37 |
| Hostname | 47 |Type | 48 |Value 49 | |
|---|---|---|
| mx1.postal.example.com | 54 |A | 55 |192.168.1.3 |
56 |
| mx1.postal.example.com | 59 |AAAA | 60 |2a00:1234:abcd:1::3 |
61 |
| mx2.postal.example.com | 64 |A | 65 |192.168.1.3 |
66 |
| mx2.postal.example.com | 69 |AAAA | 70 |2a00:1234:abcd:1::3 |
71 |
| Hostname | 83 |Type | 84 |Value 85 | |
|---|---|---|
| spf.postal.example.com | 90 |TXT | 91 |v=spf1 ip4:192.168.1.3 ip6:2a00:1234:abcd:1::3 ~all |
92 |
~all with -all to make the SPF record stricter.
98 | ::
99 |
100 | ## Return Path
101 |
102 | The return path domain is the default domain that is used as the `MAIL FROM` for all messages sent through a mail server. You should add DNS records as below.
103 |
104 | | Hostname | 108 |Type | 109 |Value 110 | |
|---|---|---|
| rp.postal.example.com | 115 |A | 116 |192.168.1.3 |
117 |
| rp.postal.example.com | 120 |AAAA | 121 |2a00:1234:abcd:1::3 |
122 |
| rp.postal.example.com | 125 |MX | 126 |10 postal.example.com |
127 |
| rp.postal.example.com | 130 |TXT | 131 |v=spf1 a mx include:spf.postal.example.com ~all |
132 |
| postal._domainkey.rp.postal.example.com | 135 |TXT | 136 |Value from postal default-dkim-record |
137 |
| Hostname | 150 |Type | 151 |Value 152 | |
|---|---|---|
| routes.postal.example.com | 157 |MX | 158 |10 postal.example.com |
159 |
| Hostname | 171 |Type | 172 |Value 173 | |
|---|---|---|
| track.postal.example.com | 178 |A | 179 |192.168.1.3 |
180 |
| track.postal.example.com | 183 |AAAA | 184 |2a00:1234:abcd:1::3 |
185 |
/etc), you must ensure these are now within the `/opt/postal/config` directory otherwise they won't be available within the container that Postal runs within.
86 | ::
87 |
88 |
89 | ## Removing the old Postal helper script
90 |
91 | Run the following command to backup the old Postal helper script.
92 |
93 | ```
94 | mv /usr/bin/postal /usr/bin/postal.v1
95 | ```
96 |
97 | ## Installing Postal v2
98 |
99 | The next thing to do is to download the new Postal installation helpers repo and set up the new `postal` command.
100 |
101 | ```
102 | git clone https://github.com/postalserver/install /opt/postal/install
103 | sudo ln -s /opt/postal/install/bin/postal /usr/bin/postal
104 | ```
105 |
106 | Next, run a normal upgrade using the new Postal command line helper. This will run a new image to upgrade your database schema to that required for Postal v2.
107 |
108 | ```
109 | postal upgrade
110 | ```
111 |
112 | Finally, you can start the Postal components.
113 |
114 | ```
115 | postal start
116 | ```
117 |
118 | You should now find that Postal is running again and working as normal. Confirm that all process types are running using `postal status`. Your output should look like this:
119 |
120 | ```
121 | Name Command State Ports
122 | ------------------------------------------------------------------
123 | postal_cron_1 /docker-entrypoint.sh post ... Up
124 | postal_requeuer_1 /docker-entrypoint.sh post ... Up
125 | postal_smtp_1 /docker-entrypoint.sh post ... Up
126 | postal_web_1 /docker-entrypoint.sh post ... Up
127 | postal_worker_1 /docker-entrypoint.sh post ... Up
128 | ```
129 |
130 | ## A note about SMTP ports
131 |
132 | If you were previously running the Postal SMTP server on any port other than 25, you can revert this configuration and have Postal listen on this port directly. To do this, you can remove any `iptables` rules you might have and update your `postal.yml` with the new port number.
133 |
134 | ## Rolling back
135 |
136 | If something goes wrong and you need to rollback to the previous version you can still do that by reverting the `postal` helper and starting it again.
137 |
138 | ```
139 | postal stop
140 | unlink /usr/bin/postal
141 | mv /usr/bin/postal.v1 /usr/bin/postal
142 | postal start
143 | ```
144 |
145 | ## Tidying up
146 |
147 | When you're happy that everything is running nicely, there are some final things you should do:
148 |
149 | - Remove `/opt/postal/app`. This is where the application itself lived and is no longer required.
150 | - Remove `/opt/postal/log`. Logs are no longer stored here.
151 | - Remove `/opt/postal/vendor`. This is no longer used.
152 | - Remove the backup Postal helper tool from `/usr/bin/postal.v1`.
153 | - If you changed any tracking domains to use your main IP address, you can remove the additional IP from the server after checking that all DNS updates have applied.
154 |
155 | ## Installing on a new server with existing data
156 |
157 | If you want to simply install Postal on a new server and copy your data over, you can do so by following these instructions.
158 |
159 | 1. Create your new server and follow the instructions for installing Postal. You should have a working installation at this point.
160 | 2. On your old server, stop Postal using `postal stop`. Make sure it has fully stopped before continuing using `postal status`.
161 | 3. On your new server, stop Postal using `postal stop`.
162 | 4. Use whatever tool takes your fancy (`mysqldump`, `Mariabackup` etc...) to copy your databases to your new server. Make sure you copy the `postal` database as well as all other databases prefixed with `postal` (or whatever you have configured your prefix to be in the `message_db` part of your configuration).
163 | 5. On your new server, run `postal upgrade-db` to update the copied database with the changed table structures
164 | 6. Ensure that your `postal.yml` is merged appropriately. For example, make sure your `dns` section is correct. There is no need to copy the `rails.secret` - a new secret on the new host won't be a problem.
165 | 7. If you stopped Postal cleanly before beginning, there is no need to copy any persisted data from RabbitMQ.
166 | 8. Shutdown your old Postal server.
167 | 9. Move the IP address(es) from the old server to the new one (if both old and new servers are with the same provider).
168 | 10. Start Postal on the new server using `postal start`.
169 |
--------------------------------------------------------------------------------
/public/supporters/katapult-dark.svg:
--------------------------------------------------------------------------------
1 |
28 |
--------------------------------------------------------------------------------
/public/supporters/katapult-light.svg:
--------------------------------------------------------------------------------
1 |
28 |
--------------------------------------------------------------------------------