Skip to content

Instantly share code, notes, and snippets.

@MrXyfir MrXyfir/help.md
Last active Apr 28, 2019

Embed
What would you like to do?
Ptorx docs

Terminology

  • Email Aliases, alias emails, or forwarding emails
    • Email addresses created via Ptorx that typically act as a middleman for your primary emails by receiving mail and forwarding allowed mail to your primary email addresses.
  • Waterfall
    • Every alias has a waterfall that allows you to link filters, modifiers, and primary emails to it in a specific order. Each linked item is acted on in order, cascading downward like a waterfall, allowing you to redirect different mail to different primary emails based on filters and modifiers.
  • Primary Emails, real, or main emails
    • Your actual email addresses where you normally receive mail. These emails are where mail sent to your alias addresses will be redirected to. Enable Autolink to automatically link them to any new aliases you create.
  • Filters
    • Filters allow you to filter out mail (with whitelists or blacklists) before it reaches any primary emails that come after it in an alias's waterfall.
  • Modifiers
    • Modifiers allow you to modify components of an incoming email before it gets redirected to primary emails below it in an alias's waterfall.
  • Messages, or mail
    • Messages are any incoming pieces of mail received by your alias addresses.
  • Keys, or PGP keys
    • Your optional private and public keys which will be used to encrypt the text and HTML body contents of mail stored on Ptorx servers. Mail is encrypted by Ptorx servers with your public key and decrypted later in the app using the private key.
  • Mailbox Password
    • Separate from your account password, this is used to encrypt your private key if you have one. It's important this is a strong password because your encrypted private key will be stored on Ptorx for convenience. Only you, with your access to this password, will be able to read your encrypted mail.

Aliases

Deleting aliases

By deleting an email alias, that specific email is completely removed from your account, however it remains on Ptorx's system simply as a placeholder to prevent that address from ever being claimed again in the future. This means that once you delete an alias address there is no way for you or another user to claim that address. Deleted aliases will not forward or save received mail.

Replying to forwarded mail

You can safely reply to mail that is sent to an alias if that alias has Allow Anonymous Reply enabled. You can reply to this mail either from within the Ptorx app or by replying to the message you received in your email client as you would reply to any other message.

There are some limitations with this feature:

  • You will only be able to reply to mail so long as a copy of it is still stored on Ptorx.
  • If you reply to mail from within your email client, that client must support the Reply-To email header. Most popular clients (like Gmail) should support this.

The replies will be sent to the original sender using the address of the alias that received the message.

Forwarded mail marked as spam

Due to the nature of the service and for very technical reasons we won't bother with here, sometimes forwarded mail will end up in your spam folder even though it's perfectly legitimate mail. The solution to this is to whitelist ptorx.com or whichever alias email domains or addresses you use. This process will differ based on your mailbox provider.

For Gmail, the most popular option, you'd create a filter for the domain (@ptorx.com) or a specific address (example@ptorx.com) and set the Never send it to Spam action. Alternatively, you can also add individual addresses to your contacts whenever you receive a message by viewing the mail and selecting the Add example@example.com to Contacts list option. A good tutorial can be found here.

Send mail from alias using another app

Each alias has unique SMTP authentication credentials that can be used to send mail from that alias using a third-party, non-Ptorx email client like Gmail or Outlook.

  • Host: smtp.ptorx.com
  • Port: 587
  • User: your-alias@ptorx-or-your-domain.com
  • Pass: SMTP passkey provided when viewing alias in-app.

Note: Sending mail programmatically using your credentials is forbidden.

Modifiers

Modifiers give you expanded control over the content of the mail that gets sent to you. Modifiers are only applied to mail being redirected to a main email. If you have 'Save Mail' enabled on an alias, the saved mail will be unmodified.

Functions

Special functions are available within templates allow you to access and manipulate email content. All functions are accessed via the """func()""" syntax, where func is the name of the function.

Get variables

var("var")

Allows you to access variables from the message. Note that if a previous modifier has modified this variable then you will receive that modified value. If the variable does not exist then """var("...")""" will be removed and replaced with just an empty string.

Variables you can choose from:

  • from
  • to
  • subject
  • html - the message body as HTML
  • text - the message body as text

Example:

Email from: """var("from")"""

becomes

Email from: user@example.com

Get Header Values

header("header")

Allows you to access headers from the message. Note that if a previous modifier has modified this header then you will receive that modified header. If the header does not exist then """header("...")""" will be removed and replaced with just an empty string.

Example:

Send replies to: """header("reply-to")"""

becomes

Send replies to: replies@example.com

Find and replace

replace("var", "substr", "replacement")

Allows you to find and replace text within the specified variable. If the variable does not exist then """replace(...)""" will be removed and replaced with just an empty string.

Example:

Email from: """replace("from", "example", "domain")"""

becomes

Email from: user@domain.com

Find and replace with regular expressions

replace("var", regex(/pattern/flags), "replacement")

Allows you to find and replace text within the specified variable using JavaScript's regular expression engine. If the variable does not exist then """replace(...)""" will be removed and replaced with just an empty string.

Flags are optional. gimsuy may be used. See the Parameters: flags section on MDN for more information.

Special capabilities are enabled in the replacement value via the $ character:

  • $$: If you just want to insert a '$' character, you'll have to use $$.
  • $&: Inserts the matched substring.
  • $`: Inserts the portion of the string that precedes the matched substring.
  • $': Inserts the portion of the string that follows the matched substring.
  • $n: Where n is a non-negative integer lesser than 100, inserts the nth parenthesized submatch string.

Example:

Email from: """replace("from", regex(/(EXAMPLE|TEST)/gi), "domain")"""

becomes

Email from: user@domain.com

Domains

A domain on Ptorx is a normal domain name that can be used to create alias emails. All Ptorx users get access to the ptorx.com domain. Optionally, you can add your own domain to Ptorx, or request access to a domain added by another Ptorx user.

Using your own domain, or those used by few other users, can help circumvent blacklists.

Adding your domain to Ptorx

You can add your own domains to Ptorx, and use them to create aliases just like you would with a normal @ptorx.com alias. This is available at no extra cost and you can add as many domains as you like!

After initiating the process of adding your domain to Ptorx, you must verify that you own the domain, so don't bother trying to add a domain you don't own. You will verify ownership by setting a few DNS records:

Type Hostname Value
TXT example.com v=spf1 include:ptorx.com ~all
TXT selector._domainkey.example.com v=DKIM1; k=rsa; p=...
MX example.com ptorx.com

example.com should be whatever domain you entered into Ptorx. If you already have MX records set on your domain for another service, you should use a subdomain for mail that Ptorx will handle. Information for the second TXT record will be provided to you within the app.

For your MX record, you can set the priority to any number you like. 10 is typically the convention.

In certain cases it may take up to a day or two for these records to propagate. Use the 'verify' button when viewing your domain on Ptorx to check the values again. Mail will not be able to be received or sent until your domain is verified.

Removing or altering these records after verification will likely prevent your domain from working with Ptorx properly.

Requesting access to domains

If another user has already added a domain to Ptorx, you can request access to it by using the 'request access key' that is generated for you when you attempt to add the domain. You must send that key to the user who originally added the domain to Ptorx, and they must then authorize that key to use their domain.

A request key is used to prevent your account's information from needing to be shared with the domain owner.

Warning! Using another user's domain can be risky! If they decide to remove their domain from Ptorx, or don't renew its registration before it expires, you will lose access to any aliases you have created with that domain. They could also move their domain away from Ptorx which could potentially allow them to view your incoming mail!

Deleting a domain

Deleting a domain from your account if you are the domain's creator will result in all users of your domain, including you, losing any alias emails they have created with your domain. Your domain will be completely removed from Ptorx. You will be able to add your domain back to Ptorx in the future should you wish.

Deleting a user from your domain if you are the domain's creator will result in all of the user's aliases linked to your domain being deleted. The user will not be able to access your domain again without you authorizing their new request key.

Users of a domain must contact the domain's owner and request their account be removed as a user of the domain.

Credits

Credits are the currency with which actions on Ptorx are paid for. Sending, receiving, redirecting, and replying to mail all cost credits. Credits are awarded monthly based on your account tier.

Whenever your account runs out of credits, mail will no longer be received or redirected and you will not be able to send or reply to mail.

Actions

Action Cost
Send mail 1 credit
Receive mail 1 credit
Reply from app 1 credit
Reply from third-party inbox 2 credits
Forward to one primary email 2 credits

Note that the Forward action is really just a combination of the Send and Receive actions, as is the Reply from third-party inbox action. To clarify further: if someone sends you an email that is then redirected to one of your primary emails, that will only cost 2 credits. If it's forwarded to two primary emails, it will cost 3 credits.

Everything else on Ptorx can be done without charge.

Subscriptions

Ptorx subscriptions allow full access to all of Ptorx's features while also increasing the amount of credits your account will be topped up to every month.

Premium and Ultimate users are able to do things that Basic users (free, non-paying) cannot:

  • Send mail from an alias on Ptorx
  • Have more than one primary email
  • Reply to mail using and alias on Ptorx
  • Save incoming mail to Ptorx for later viewing within the app
  • Reply to mail anonymously using an alias from your non-Ptorx mailbox
  • Send mail from an alias using its SMTP credentials in non-Ptorx email clients

Privacy Policy

This privacy policy details how your 'Personally Identifiable Information' (PII) is used by Ptorx. PII, as described in US privacy law and information security, is information that can be used on its own or with other information to identify, contact, or locate a single person, or to identify an individual in context. Please read our privacy policy carefully to get a clear understanding of how we collect, use, protect or otherwise handle your PII in accordance with our website.

Information Collection and Usage

When ordering, registering, linking services to your account, or at other times on our site, as appropriate, you may be asked to enter your email address or other details to help you with your experience. Your information is only stored by Ptorx when you make actions that would require Ptorx to do so. For example when creating an account, email alias, or other digital items in our app.

We may use the information we collect from you when you register, make a purchase, sign up for our newsletter, respond to a survey or marketing communication, surf the website, or use certain other site features in the following ways:

  • To personalize your experience and to allow us to deliver the type of content and product offerings in which you are most interested.
  • To improve our website in order to better serve you.

Ptorx does not save any mail in part or full that is sent or received by our alias emails unless the specific alias email has the Save Mail feature enabled. When this feature is enabled, a full copy of every incoming email is stored until it expires or is manually deleted by the user. Ptorx does not use the mail we store for any purposes other than to provide the optional, requested features.

Information Security

We take measures to help protect information about you from loss, theft, misuse and unauthorized access, disclosure, alteration, and destruction. For example, we use HTTPS while information is being transmitted, and all payment transactions are processed through gateway providers and are not stored or processed on our servers.

Cookies

We use cookies as a required part of our authentication process that keep you logged in for your session.

Third-Party Disclosure

We do not sell, trade, or otherwise transfer to outside parties your PII or uploaded data.

Occasionally, at our discretion, we may include or offer third-party products or services on our website. These third-party sites have separate and independent privacy policies. We therefore have no responsibility or liability for the content and activities of these linked sites. Nonetheless, we seek to protect the integrity of our site and welcome any feedback about these sites.

We do not allow third-party behavioral tracking.

Do Not Track

We don't honor Do Not Track signals because:

  • Minimal tracking is required for users to login and for our service to work properly.
  • Minimal tracking data is only stored temporarily.

Contact Us

If there are any questions regarding this privacy policy, you may contact us using the information below.

Ptorx
3170 Huula Dr
Oceanside, California 92058
United States of America
contact@xyfir.com

Self-hosting Ptorx

Hosting Ptorx yourself gives you a greater level of control and privacy (assuming you set everything up correctly) but it does come at a cost: it's not a simple process. If you need a self-hosted Ptorx installation you can either follow this tutorial with no support should you get stuck, or you can hire us to do it for you by sending an email to contact@xyfir.com. Many steps will be vague and generalized, so you'll be expected to know how to fill in the blanks based on your environment and requirements.

Requisites

  • Access to a domain whose DNS records you can configure.
  • A Linux server (we'll use Ubuntu) whose host allows it to send mail, which primarily means that outgoing port 25 should be open.
  • Know-how to set up a secure server before we install Ptorx onto it.
  • Nginx or similar software installed to serve static files and act as a proxy for Ptorx and other APIs.
  • Let's Encrypt or similar geniune TLS (SSL) certificate (no self-signed certs!) for your main domain where the instance of Ptorx will be hosted. Additional mail-only domains don't need this.
  • Node.js installed on your server. Ptorx targets the latest version available at time of the last server/package.json update.
  • MariaDB or MySQL installed on your server. Ptorx.com runs MariaDB so there may be unknown discrepancies with MySQL.
  • sendmail installed on your server. (Make sure your server's hostname is set correctly to prevent slow mail!)
  • iptables-persistent installed on your server.

Step 0: Clone the Repo

First change to the directory where you wish to keep Ptorx.

git clone --recurse-submodules https://github.com/Xyfir/ptorx.git
cd ptorx

From now on we'll assume commands are run from ptorx/.

Step 1: Download npm Dependencies

Install npm depencies for each module:

cd server
npm install
cd ../web
npm install
cd ../accownt/server
npm install
cd ../web
npm install
cd ../../ccashcow/server
npm install
cd ../web
npm install
cd ../../yalcs/loader
npm install
cd ../server
npm install
cd ../web
npm install
cd ../../ # back to ptorx/

Then install pm2 to manage our API servers:

npm install -g pm2

Technically pm2 is not required, but it's what we'll use for this tutorial.

Step 2: Create Database

Create a database and preferably a non-root MySQL user with SELECT, INSERT, UPDATE, and DELETE privileges as well. We'll name our database ptorx but any name will do.

sudo mysql -u root -e "CREATE DATABASE ptorx"

Next we'll build the database:

sudo mysql -u root -p ptorx < server/db/build/structure.sql
sudo mysql -u root -p ptorx < server/db/build/data.sql

Replace ptorx with the name of your database.

Step 3: Create Data Directories

Now we need to create the data directories where Ptorx and its submodules will write both temporary and permanent data to the disk. You can put them wherever you'd like (just remember it for Step 4), but for now we'll put them alongside ptorx/.

mkdir ../accownt-db ../mail-cache ../ccashcow-db ../yalcs-db

You can also name the three directories however you'd like.

Step 4: Set Environment Variables

Ptorx and its submodules are configured via environment variables which are loaded into the applications via .env files located in each modules's directory.

To understand the syntax of the .env files, know that they are first loaded via dotenv and then the string values provided by dotenv are parsed by enve.

Step 4a: Create .env Files

First we'll create each file and then we'll work our way through populating them with values.

touch server/.env web/.env accownt/server/.env accownt/web/.env ccashcow/server/.env ccashcow/web/.env

Step 4b: Configure CCashCow

See Xyfir/ccashcow for instructions.

Use vim or nano or similar to edit the files ccashcow/server/.env and ccashcow/web/.env.

Step 4c: Configure Accownt

See Xyfir/accownt for instructions.

Edit the files accownt/server/.env and accownt/web/.env.

Step 4d: Configure Yalcs

See Xyfir/yalcs for instructions.

Edit the files yalcs/loader/.env, yalcs/server/.env, and yalcs/web/.env.

Step 4e: Configure Ptorx

Now we'll do the same thing for Ptorx. You can find the available environment variables in types/ptorx.d.ts under the Ptorx.Env namespace.

Step 5: Build From Source

cd server
npm run build
cd ../web
npm run build
cd ../accownt/server
npm run build
cd ../web
npm run build
cd ../../ccashcow/server
npm run build
cd ../web
npm run build
cd ../../yalcs/loader
npm run build
cd ../server
npm run build
cd ../web
npm run build
cd ../../

Step 6: Open and Forward Ports

Make sure your firewall allows traffic through the needed ports. If you're using ufw, it'll look something like:

sudo ufw allow smtp # 25
sudo ufw allow submission # 587
sudo ufw allow 2071 # -> 25
sudo ufw allow 2076 # -> 587

Next we'll need to forward incoming traffic from port 25 to the port you set for the MTA server via MTA_PORT in server/.env. We'll also forward 587 to the port for the MSA server, as configured via MSA_PORT. We'll assume the suggested ports for each.

sudo iptables -t nat -A PREROUTING -p tcp --dport 25 -j REDIRECT --to-port 2071
sudo iptables -t nat -A PREROUTING -p tcp --dport 587 -j REDIRECT --to-port 2076
sudo iptables -t nat -nvL # optionally validate your rules
iptables-save > /etc/iptables/rules.v4

Suggested Ports

Ptorx requires a lot of servers. The suggested local ports are as follows:

Name Port
Ptorx API 2070
Ptorx MTA 2071
Ptorx test MTA 2072
Ptorx client (for dev) 2073
Accownt 2074
CCashCow 2075
Ptorx MSA 2076
Yalcs 2079

Step 7: Set DNS Records

For this step, we'll be using example.com as a placeholder for your domain.

Step 7a: DKIM

First of all, set the domain key TXT record to <SELECTOR>._domainkey.example.com as provided by the Ptorx app after you've added your domain. Ignore the other records it tells you to set.

Step 7b: MX

Create a single MX record for example.com that points to your server's IP address, which will probably be the same as your domain's A record. The priority doesn't matter with only a single server, but we'll set it to 10.

Step 7c: SPF

This step is optional but highly recommended to prevent your mail from being marked as spam.

Create a TXT record for example.com with something like this:

"v=spf1 +a ~all"

Before you blindly copy and paste, you should understand how SPF works and how best to utilize it according your needs.

Step 7d: DMARC

This step is optional but highly recommended to prevent your mail from being marked as spam.

Create a TXT record for _dmarc.example.com with something like this:

"v=DMARC1; p=reject; fo=1; rua=mailto:aggregate-dmarc-x@example.com; ruf=mailto:fail-dmarc-x@example.com"

Before you blindly copy and paste, you should understand how DMARC works and how best to utilize it according your needs.

Step 7e: Reverse DNS

This step is optional but highly recommended to prevent your mail from being marked as spam.

Go to your server host's control panel and change the reverse DNS to your domain name. By default its value probably looks something like 0.0.0.0.yourhost.com where 0.0.0.0 is your server's IPv4 address and yourhost.com is the name of your server host. For example with VULTR, which Ptorx uses, it'll look like 140.82.16.198.vultr.com, and it can be found under the Settings > IPv4 tab when viewing your server instance.

Step 8: Start Servers

Last but not least, start the servers with pm2, which you should have installed earlier:

cd server
pm2 start --name ptorx npm -- run start
cd ../accownt/server
pm2 start --name accownt npm -- run start
cd ../../ccashcow/server
pm2 start --name ccashcow npm -- run start
cd ../../yalcs/server
pm2 start --name yalcs npm -- run start
cd ../../
pm2 startup # then follow instructions

Upgrading Ptorx

This is a general guide for upgrading from one version of Ptorx to another. It's likely there are more specific steps you'll have to follow based on your current version and that of which you wish to upgrade to, but these steps should typically get you at least 90% of the way there.

To begin the process of upgrading Ptorx, let's first reset the repos and pull in changes:

git reset --hard origin/master
git submodule foreach git reset --hard
git pull
git submodule update --recursive

Now we'll once again run through some of the steps above:

  • Go to Step 1 to update dependencies.
  • Go to Step 4 to update any .env files that may require changes.
  • Go to Step 5 to rebuild the apps.

Update your database if needed by running in order the server/db/upgrade/ SQL files for every version after your current installation's. For example, assuming you're on version 1.0.0 and the latest is 1.1.0:

sudo mysql -u root -p ptorx < server/db/upgrade/1.0.1.sql
sudo mysql -u root -p ptorx < server/db/upgrade/1.0.2.sql
sudo mysql -u root -p ptorx < server/db/upgrade/1.1.0.sql

Be sure to replace ptorx with the actual name of your database.

Finally, restart the servers:

pm2 restart all

Terms of Service

These terms and conditions outline the rules and regulations for the use of Ptorx's Website.

Ptorx (operated by Xyfir, LLC) is located at:

  • 3170 Huula Dr
  • Oceanside, California 92058
  • United States of America

By accessing Ptorx's website or using its applications we assume you accept these terms and conditions in full. Do not continue to use Ptorx's website or applications if you do not accept all of the terms and conditions stated on this page.

The following terminology applies to these Terms and Conditions, Privacy Statement and Disclaimer Notice and any or all Agreements: "Client", "You" and "Your" refers to you, the person accessing this website and accepting the Company's terms and conditions. "The Company", "Ourselves", "We", "Our" and "Us", refers to our Company. "Party", "Parties", or "Us", refers to both the Client and ourselves, or either the Client or ourselves. All terms refer to the offer, acceptance and consideration of payment necessary to undertake the process of our assistance to the Client in the most appropriate manner, whether by formal meetings of a fixed duration, or any other means, for the express purpose of meeting the Client's needs in respect of provision of the Company's stated services/products, in accordance with and subject to, prevailing law of United States. Any use of the above terminology or other words in the singular, plural, capitalization and/or he/she or they, are taken as interchangeable and therefore as referring to same.

These terms may be updated at any time without notice. Continued use of our sites, applications, or services implies consent to the revised terms.

Cookies

We employ the use of cookies for authentication purposes. By using Ptorx's website you consent to the use of cookies in accordance with Ptorx's privacy policy.

License

Unless otherwise stated, Ptorx and/or its licensors own the intellectual property rights for all material on Ptorx. All intellectual property rights are reserved. You may view and/or print pages from Ptorx for your own personal use subject to restrictions set in these terms and conditions.

You must not:

  • Republish material from Ptorx
  • Sell, rent or sub-license material from Ptorx
  • Reproduce, duplicate or copy material from Ptorx
  • Redistribute content from Ptorx (unless content is specifically made for redistribution)

Abuse

Abusing our services will result in an account termination. Abuse of our service includes but is not limited to:

  • Using Ptorx to send "email blasts"
  • Using Ptorx to send mass emails to a single or multiple addresses
  • Using Ptorx to send spam, phishing emails, malware, scams, etc
  • Using Ptorx to expoit, and/or break the terms of service of other third-party services
  • Creating multiple accounts on Ptorx to abuse the referral or free credits system
  • Using Ptorx emails in any way that may harm the reputations of Ptorx, Xyfir, or any of our affiliates
  • Making purchases and then initiating chargebacks

Termination

Users found to be abusing our service will have their account deleted and access revoked from Ptorx. If the user has made any purchases on Ptorx, they will not receive a refund. In the event of termination, emails will no longer be redirected or stored.

Disclaimer

To the maximum extent permitted by applicable law, we exclude all representations, warranties and conditions relating to our website and the use of this website (including, without limitation, any warranties implied by law in respect of satisfactory quality, fitness for purpose and/or the use of reasonable care and skill). Nothing in this disclaimer will:

  • limit or exclude our or your liability for death or personal injury resulting from negligence;
  • limit or exclude our or your liability for fraud or fraudulent misrepresentation;
  • limit any of our or your liabilities in any way that is not permitted under applicable law; or
  • exclude any of our or your liabilities that may not be excluded under applicable law.

The limitations and exclusions of liability set out in this Section and elsewhere in this disclaimer: (a) are subject to the preceding paragraph; and (b) govern all liabilities arising under the disclaimer or in relation to the subject matter of this disclaimer, including liabilities arising in contract, in tort (including negligence) and for breach of statutory duty.

To the extent that the website and the information and services on the website are provided free of charge, we will not be liable for any loss or damage of any nature.

Ptorx is not responsible for the actions or content posted of other users who utilize our service. Please contact us if you believe a user is abusing our service.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.