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 `example.com`, you'll need to setup `click.example.com` (or whatever you choose) to point to your Postal server.
19 |
20 | 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.
21 |
22 | 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.
23 |
24 | If you're happy things are working, you can enable tracking as follows:
25 |
26 | 1. Find the web server you wish to enable tracking on in the Postal web interface
27 | 2. Go to the **Domains** item
28 | 3. Select **Tracking Domains**
29 | 4. Click **Add a tracking domain**
30 | 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.
31 |
32 | ## Disabling tracking on a per e-mail basis
33 |
34 | If you don't wish to track anything in an email you can add a header to your e-mails before sending it.
35 |
36 | ```text
37 | X-AMP: skip
38 | ```
39 |
40 | ## Disabling tracking for certain link domains
41 |
42 | 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.
43 |
44 | ## Disabling tracking on a per link basis
45 |
46 | 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.
47 |
48 | * `https+notrack://postalserver.io`
49 | * `http+notrack://katapult.io/signup`
50 |
--------------------------------------------------------------------------------
/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/3.features/ip-pools.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: IP Pools
3 | description: ''
4 | category: Features
5 | ---
6 | Postal supports sending messages from different IP addresses. This allows you to configure certain sets of IPs for different mail servers or send from different IPs based on the sender or recipient addresses.
7 |
8 | ## Enabling IP pools
9 |
10 | By default, IP pools are disabled and all email is sent from any IP address on the host running the workers. To use IP pools, you'll need to enable them in the configuration file. You can do this by setting the following in your `postal.yml` configuration file. You'll then need to restart Postal using `postal stop` and `postal start`.
11 |
12 | ```yaml
13 | postal:
14 | use_ip_pools: true
15 | ```
16 |
17 | ## Configuring IP pools
18 |
19 | Once you have enabled IP pools, you'll need to set them up within the web interface. You'll see an **IP Pools** link in the top right of the interface. From here you can add pools and then add IP addresses within them.
20 |
21 | Once an IP pool has been added, you'll need to assign it any organization that should be permitted to use it. Open up the organization and choose **IPs** and then tick the pools you want to allocate.
22 |
23 | Once allocated to an organization, you can assign the IP pool to servers from the server's **Settings** page. You can also use the IP pool to configure IP rules for the organization or server.
24 |
25 | ::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
26 | It's very important to make sure that the IP addresses you add in the web interface are actually configured on your Postal servers. If the IPs don't exist on the server, message delivery may fail or messages will not be dequeued correctly.
27 | ::
28 |
--------------------------------------------------------------------------------
/content/3.features/logging.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Logging
3 | description: ''
4 | category: Features
5 | ---
6 |
7 | All Postal processes log to STDOUT and STDERR which means their logs are managed by whatever engine is used to run the container. In the default case, this is Docker.
8 |
9 | ## Redirecting logs to the host syslog
10 |
11 | If you want to send your log data to the host system's syslog then you can configure this. This is useful if you wish to use external tools like `fail2ban` to block users from accessing your system.
12 |
13 | The quickest way to achieve this is to use a docker compose overide file in `/opt/postal/install/docker-compose.override.yml`. The contents of this file, would contain the following:
14 |
15 | ```yaml
16 | version: "3.9"
17 | services:
18 | smtp:
19 | logging:
20 | driver: syslog
21 | options:
22 | tag: postal-smtp
23 | ```
24 |
25 | If you wanted to put worker and web server logs there too, you can define those. The example above demonstrates using the `smtp` server process.
26 |
27 | ## Limiting the size of logs
28 |
29 | Docker cam be configured to limit the size of the log files it stores. To avoid storing large numbers of log files, you should configure this appropriately. This can be achieved by setting a maximum size in your `/etc/docker/daemon.json` file.
30 |
31 | ```json
32 | {
33 | "log-driver": "local",
34 | "log-opts": {
35 | "max-size": "100m"
36 | }
37 | }
38 | ```
39 |
40 | ## Sending logs to Graylog
41 |
42 | Postal includes support for sending log output to a central Graylog server over UDP. This can be configured using the following options:
43 |
44 | ```yaml
45 | gelf:
46 | # GELF-capable host to send logs to
47 | host:
48 | # GELF port to send logs to
49 | port: 12201
50 | # The facility name to add to all log entries sent to GELF
51 | facility: postal
52 | ```
53 |
--------------------------------------------------------------------------------
/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/3.features/smtp-authentication.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: SMTP Authentication
3 | description: ''
4 | category: Features
5 | ---
6 |
7 | For sending outgoing emails through the Postal SMTP server you will need to generate a credential through the Postal web interface. This credential is associated with a server and allows you to send mail from any domain associated with that domain (or the organization that owns the domain.)
8 |
9 | ## Authentication types
10 |
11 | When authenticating to the SMTP server, there are three supported authentication types.
12 |
13 | * `PLAIN` - the credentials are passed in plain text to the server. When using this, you can provide any string as the username (e.g. `x`) and the password should contain your credential string.
14 | * `LOGIN` - the credentials are passed Base64-encoded to the server. As above, you can use anything as the username and the password should contain the credential string (Base64-encoded).
15 | * `CRAM-MD5` - this is a challenge-response mechanism based on the HMAC-MD5 algorithm. Unlike the above two mechanism, the username does matter and should contain the organization and server permalinks separated by a `/` or `_` character. The password used should be the value from your credential.
16 |
17 | ## From/Sender validation
18 |
19 | When sending outgoing email through the SMTP server, it is important that the `From` header contains a domain that is owned by the server or its organization. If this it not valid, you will receive a `530 From/Sender name is not valid` error.
20 |
21 | If you have enabled "Allow Sender Header" for the server, you can include this domain in the `Sender` header instead and any value you wish in the `From` header.
22 |
23 | ## IP-based authentication
24 |
25 | Postal has the option to authenticate clients based on their IP address. To use this, you need to create an **SMTP-IP** credential for the IP or network you wish to allow to send mail. Use this carefully to avoid creating an open relay.
26 |
--------------------------------------------------------------------------------
/content/3.features/smtp-tls.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: SMTP TLS
3 | description: ''
4 | category: Features
5 | ---
6 |
7 | By default, Postal's SMTP server is not TLS enabled however you can enable it by generating and providing a suitable certificate. We recommend that you use a certificate issued by a recognised certificate authority, but this isn't essential to use this feature.
8 |
9 | ## Key & certificate locations
10 |
11 | Certificates should be placed in your `/opt/postal/config` directory.
12 |
13 | * `/opt/postal/config/smtp.key` - the private key in PEM format
14 | * `/opt/postal/config/smtp.cert` - the certificate in PEM format
15 |
16 | ### Generating a self signed certificate
17 |
18 | You can use the command below to generate a self-signed certificate.
19 |
20 | ```bash
21 | openssl req -x509 -newkey rsa:4096 -keyout /opt/postal/config/smtp.key -out /opt/postal/config/smtp.cert -sha256 -days 365 -nodes
22 | ```
23 |
24 | ## Configuration
25 |
26 | Once you have a key and certificate you will need to enable TLS in the configuration file (`/opt/postal/config/postal.yml`). Additional options are available too.
27 |
28 | ```yaml
29 | smtp_server:
30 | # ...
31 | tls_enabled: true
32 | # tls_certificate_path: other/path/to/cert/within/container
33 | # tls_private_key_path: other/path/to/cert/within/container
34 | # tls_ciphers:
35 | # ssl_version: SSLv23
36 | ```
37 |
38 | You will need to run `postal restart` if you change the configuration or your key/certificate.
39 |
--------------------------------------------------------------------------------
/content/3.features/spam-and-virus-checking.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Spam & Virus Checking
3 | description: ''
4 | category: Features
5 | ---
6 | Postal can integrate with SpamAssassin and ClamAV to automatically scan incoming and outgoing messages that pass through mail servers.
7 |
8 | ::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
9 | This functionality is disabled by default.
10 | ::
11 |
12 | ## Setting up SpamAssassin
13 |
14 | By default, Postal will talk to SpamAssassin's `spamd` using an TCP socket connection (port 783). You'll need to install SpamAssassin on your server and then enable it within Postal.
15 |
16 | ### Installing SpamAssassin
17 |
18 | ```
19 | sudo apt install spamassassin
20 | ```
21 |
22 | #### Systemd systems
23 | On systems that use systemd (e.g. Debian Bookworm), you will need to enable the SpamAssassin timer. It is used to udpate the spam rules (which can be done manually using `sa-update`).
24 |
25 | ```shell
26 | systemctl enable --now spamassassin-maintenance.timer
27 | ```
28 |
29 | #### Other systems
30 | On other systems, you will need to open up `/etc/default/spamassassin` and change `ENABLED` to `1` and `CRON` to `1`. On some systems (such as Ubuntu 20.04 or newer), you might need to enable the SpamAssassin daemon with the following command.
31 |
32 | ```bash
33 | update-rc.d spamassassin enable
34 | ```
35 |
36 | Then you should restart SpamAssassin.
37 |
38 | ```
39 | sudo systemctl restart spamassassin
40 | ```
41 |
42 | ### Enabling in Postal
43 |
44 | To enable spam checking, you'll need to add the following to your `postal.yml` configuration file and restart. If you have installed SpamAssassin on a different host to your Postal installation you can change the host here but be sure to ensure that the `spamd` is listening on your external interfaces.
45 |
46 | ```yaml
47 | spamd:
48 | enabled: true
49 | host: 127.0.0.1
50 | port: 783
51 | ```
52 |
53 | ```
54 | postal stop
55 | postal start
56 | ```
57 |
58 | ### Classifying Spam
59 |
60 | The spam system is based on a numeric scoring system and different scores are assigned to different issues which may appear in a message. You can configure different thresholds which define when a message is treated as spam. We recommend starting at 5 and updating this once you've seen how your incoming messages are classified.
61 |
62 | You have three options which can be configured on a per route basis which defines how spam messages are treated:
63 |
64 | * **Mark** - messages will be sent through to your endpoint but the spam information will be made available to you.
65 | * **Quarantine** - the message will placed into your hold queue and you'll need to release them if you wish them to be passed to your application. They will only remain here for 7 days,
66 | * **Fail** - the message will be marked as failed and will only be recorded in your message history without being sent.
67 |
--------------------------------------------------------------------------------
/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://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/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/4.developer/_dir.yml: -------------------------------------------------------------------------------- 1 | title: Developer -------------------------------------------------------------------------------- /content/5.other/1.auto-responders-and-bounces.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Auto-Responders & Bounces 3 | description: '' 4 | --- 5 | When you send an e-mail you may be automatically be sent a bounce message or an auto responder by the destination mail server. These are handled slightly differently to normal incoming e-mail and it's worth understanding how these work. 6 | 7 | Messages like these aren't usually sent to the e-mail address that sent the message but are sent to the **return path** address. This is an address which Postal assigns to your mail server and is provided to the destination mail server for the purpose of sending this type of message. The return to address will be something like `abcdef@psrp.yourdomain.com`. 8 | 9 | If you wish to route mail which is sent to your return path address to your application, you can set up a **return path route**. This is the same as a normal route except you should enter the name as `__returnpath__` and leave the domain field blank. You can only choose HTTP endpoints for this type of route. Once added, messages sent to your return path that aren't detected as bounces will be sent to HTTP endpoint you choose. 10 | 11 | ## A note about bounces 12 | 13 | Messages that Postal detects as being bounces for a message you have already sent will not be delivered to your return path route. The original message will be updated and a `MessageBounced` webhook event will be triggered. 14 | -------------------------------------------------------------------------------- /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/5.other/3.debugging.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Debugging 3 | description: '' 4 | 5 | --- 6 | 7 | This page contains information on how to identify problems with your installation. 8 | 9 | ## DNS 10 | 11 | Whilst Postal can verify DNS records on its own, it can be useful to check what the rest of the internet is seeing. 12 | 13 | You can make use of [Whats My DNS](https://whatsmydns.net) for a quick global check or the `dig` command if you have it on a terminal, i.e. `dig txt yourdomain.com` or `dig a yourdomain.com`. 14 | 15 | ## SMTP 16 | 17 | The quickest way to ensure the internet can connect to your Postal SMTP is with `telnet postal.yourdomain.com 25`. You can proceed to attempt sending a message manually if you are familiar with the raw SMTP commands to further verify your Postal installation is working correctly. 18 | 19 | ### SMTP SSL 20 | 21 | If you aren't sure about whether the SSL certificate you have provided to Postal is set up correctly you can use `openssl s_client -connect postal.yourdomain.com:25 -starttls smtp` to get some information about your certificate from the point of view of SMTP. 22 | -------------------------------------------------------------------------------- /content/5.other/4.wildcards-and-address-tags.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Wildcards & Address Tags 3 | description: '' 4 | 5 | --- 6 | Postal supports the use of wildcards and address tags in routes. 7 | 8 | ## Using a wildcard 9 | 10 | Wildcards will allow you to receive all e-mail for every address on a domain. However, for most use cases, this isn't recommended because it means that large volumes of spam may be processed by your mail server that would otherwise have been rejected by Postal without troubling you. 11 | 12 | Just enter `*` in the name box to create a route for this. 13 | 14 | ## Using address tags 15 | 16 | Postal supports the use of "tags" on e-mail addresses which means you can add a single route but still receive from multiple addresses. For example, if you add a route for `email` you will also receive messages for `email+anything@yourdomain.com` without any additional configuration. 17 | -------------------------------------------------------------------------------- /content/5.other/_dir.yml: -------------------------------------------------------------------------------- 1 | title: Other Notes -------------------------------------------------------------------------------- /content/index.yml: -------------------------------------------------------------------------------- 1 | title: 'Postal - an open source mail delivery platform' 2 | description: 'A fully featured open source mail delivery platform for incoming & outgoing e-mail' 3 | features: 4 | links: 5 | - label: 'Discover more features' 6 | trailingIcon: 'i-heroicons-arrow-right-20-solid' 7 | color: 'gray' 8 | to: '/welcome/feature-list' 9 | size: lg 10 | items: 11 | - title: 'Comprehensive Web Interface' 12 | description: 'Manage your mail servers and view mail logs through an easy to user web interface.' 13 | icon: 'i-heroicons-window-20-solid' 14 | - title: 'Scalable' 15 | description: 'Easily horizontally scale your mail service up and down as needed.' 16 | icon: 'i-heroicons-arrows-pointing-out-16-solid' 17 | target: '_blank' 18 | - title: 'Webhooks' 19 | description: 'Set up webhooks to notify HTTP endpoints when messages are delivered or have issues.' 20 | icon: 'i-heroicons-envelope-open-solid' 21 | - title: 'Development Mode' 22 | description: 'Automatically hold messages in Postal as needed to handle testing during development.' 23 | icon: 'i-heroicons-adjustments-vertical-solid' 24 | - title: 'IP Pools' 25 | description: 'Send mail from different IP addresses to help build and maintain good IP reputation.' 26 | icon: 'i-heroicons-arrow-path-rounded-square-solid' 27 | - title: 'Spam & anti-virus integrations' 28 | description: 'Integrate with SpamAssassin, rspamd and ClamAV to have incoming & outgoing messages checked for threats and spam.' 29 | icon: 'i-heroicons-trash-solid' 30 | -------------------------------------------------------------------------------- /error.vue: -------------------------------------------------------------------------------- 1 | 31 | 32 | 33 |
34 |
37 |
38 |
39 |
41 |
42 |
43 |
44 |
45 |
46 |
47 |
49 |
50 |
52 |
53 |
--------------------------------------------------------------------------------
/layouts/docs.vue:
--------------------------------------------------------------------------------
1 |
10 |
11 |
12 | 54 | 55 |
62 |
66 |
67 |
26 |
50 |
51 |
57 |
58 |
59 |
80 |
81 |
--------------------------------------------------------------------------------
/public/CNAME.off:
--------------------------------------------------------------------------------
1 | docs.postalserver.io
2 |
--------------------------------------------------------------------------------
/public/cover.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/cover.png
--------------------------------------------------------------------------------
/public/factory.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/factory.jpg
--------------------------------------------------------------------------------
/public/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/favicon.ico
--------------------------------------------------------------------------------
/public/icon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/icon.png
--------------------------------------------------------------------------------
/public/logo-dark.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/public/logo-light.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/public/preview-dark.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/preview-dark.png
--------------------------------------------------------------------------------
/public/preview.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/preview.png
--------------------------------------------------------------------------------
/public/screenshot.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/screenshot.png
--------------------------------------------------------------------------------
/public/screenshots.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/screenshots.png
--------------------------------------------------------------------------------
/public/screenshots/Screen-Shot-2021-07-29-23-26-18.23-Qwv2DD40v4jMEoaHtE.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/screenshots/Screen-Shot-2021-07-29-23-26-18.23-Qwv2DD40v4jMEoaHtE.png
--------------------------------------------------------------------------------
/public/screenshots/oidc.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/screenshots/oidc.png
--------------------------------------------------------------------------------
/public/screenshots/tracked-message.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/postalserver/docs/c8f5b246a38aea8a1a2b551e7763c427195b2894/public/screenshots/tracked-message.png
--------------------------------------------------------------------------------
/public/supporters/katapult-dark.svg:
--------------------------------------------------------------------------------
1 |
28 |
--------------------------------------------------------------------------------
/public/supporters/katapult-light.svg:
--------------------------------------------------------------------------------
1 |
28 |
--------------------------------------------------------------------------------
/public/supporters/krystal-dark.svg:
--------------------------------------------------------------------------------
1 |
20 |
--------------------------------------------------------------------------------
/public/supporters/krystal-light.svg:
--------------------------------------------------------------------------------
1 |
20 |
--------------------------------------------------------------------------------
/renovate.json:
--------------------------------------------------------------------------------
1 | {
2 | "extends": [
3 | "@nuxtjs"
4 | ]
5 | }
6 |
--------------------------------------------------------------------------------
/server/api/search.json.get.ts:
--------------------------------------------------------------------------------
1 | import { serverQueryContent } from '#content/server'
2 |
3 | export default eventHandler(async (event) => {
4 | return serverQueryContent(event).where({ _type: 'markdown', navigation: { $ne: false } }).find()
5 | })
--------------------------------------------------------------------------------
/server/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "extends": "../.nuxt/tsconfig.server.json"
3 | }
4 |
--------------------------------------------------------------------------------
/tailwind.config.ts:
--------------------------------------------------------------------------------
1 | import type { Config } from 'tailwindcss'
2 | import defaultTheme from 'tailwindcss/defaultTheme'
3 |
4 | export default 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 |