This is the source code for self-hosting addy.io.

• Why is it called addy.io?
• Why did you make this site?
• Why should I use addy.io?
• Do you store emails?
• What is a shared domain alias?
• What is a standard alias?
• Can I use my own domain?
• Can I add a domain and also use it as a recipient?
• Can I add a domain if I'm already using it for email somewhere else?
• Why should I use this instead of a similar service?
• Is there a browser extension?
• Is there an Android app?
• Is there an iOS app?
• Is there a Raycast extension?
• How do I add my own GPG/OpenPGP key for encryption?
• Are attachments encrypted too?
• Are forwarded emails signed when encryption is enabled?
• Can I reply/send from aliases using encryption?
• Is my public GPG/OpenPGP key removed when I reply/send from an alias?
• Can I mark emails forwarded to me by addy.io as spam?
• Can I use aliases to create multiple accounts on other websites and services?
• Can I have multiple Free accounts?
• What if I don't want anyone to link ownership of my aliases together?
• Where is the server located?
• What if I don't trust you?
• What is the maximum number of recipients I can add to an alias?
• What happens when I delete my account?
• Does this work with any email provider?
• How do I reply to a forwarded email?
• I'm trying to reply/send from an alias but the email keeps coming back to me, what's wrong?
• I'm trying to reply/send from an alias but it is rejected, what's wrong?
• I've been forwarded an email with a red warning banner saying it may have been spoofed, what does it mean?
• Does addy.io strip out the banner information when I reply to an email?
• How do I send email from an alias?
• Will people see my real email if I reply to a forwarded one?
• Can emails have attachments?
• What is the max email size limit?
• What happens if I have a subscription but then cancel it?
• If I subscribe will Stripe see my real email address?
• How do you prevent spammers?
• What do you use to do DNS lookups on domain names?
• Is there a limit to how many emails I can forward?
• Is there a limit to how many aliases I can create per hour?
• How is my bandwidth calculated?
• How many emails can I receive before I go over my bandwidth limit?
• What happens if I go over my bandwidth limit in a given month?
• Can I login using an additional username?
• I'm not receiving any emails, what's wrong?
• I'm having trouble logging in, what's wrong?
• How do I know this site won't disappear next month?
• What happens to addy.io if you die?
• Is the application tested?
• How do I host this myself?
• Who's behind addy.io?
• I couldn't find an answer to my question, how can I contact you?

Addy is short for "Address". The word "Addy" is internet slang for an email address, e.g.

"My addy is being spammed. I should've kept it private."

I made this service after trying a few other options that do a similar thing. I was really interested in how they worked and loved the thought of protecting my real email addresses from spam.

I also wanted to address some issues with other services such as:

• Proprietary closed source code
• Adverts, analytics and trackers used on the sites
• No option to encrypt emails using a GPG/OpenPGP key
• No option for multiple recipients

I made the code open-source to show everyone what was going on behind the scenes and to allow others to help improve the application.

I use this service myself for the vast majority of sites I'm signed up to.

There are a number of reasons you should consider using this service:

• Protect your real email address from spam by simply deactivating/deleting aliases that receive unsolicited emails
• Identify who has sold your data by using a different email address for every site
• Protect your identity in the event of a data breach by making it difficult for hackers to cross-reference your accounts
• Prevent inbox snooping by encrypting all inbound emails using GPG/OpenPGP encryption
• Update where emails are forwarded without having to go through and change your email address for each site individually
• Reply to forwarded emails anonymously without revealing your true email address

Emails are only ever stored in the event of a failed delivery, and only if you have this option enabled in your account settings.

A shared domain alias is any alias that has a domain name that is also shared with other users. For example anyone can generate an alias with the @anonaddy.me domain. Aliases with shared domain names must be pre-generated and cannot be created on-the-fly like standard aliases.

A standard alias is any alias that can be created on-the-fly. Automatic on-the-fly alias creation is only available for domains that are unique to you. For example, your unique username subdomain, any additional usernames or any custom domains. So if you signed up with the username "johndoe", any alias you create using @johndoe.anonaddy.com would be a standard alias (even if you've generated a Random Character/Random Word one).

Yes you can use your own domain name so you can also have *@example.com as your aliases. To do so you simply need to add a TXT record to verify your ownership of the domain. Then you will need to add an MX record to your domain so that our server can handle incoming emails. You can then add a few other records to enable sending from your domain too.

No, you cannot use the same domain as a custom domain and also for a recipient on addy.io.

e.g if you add "example.com" as a custom domain, you cannot then add "[email protected]" as a recipient. This is because a domain cannot direct email to multiple locations simultaneously using MX records. So your email would arrive for "example.com" and then attempt to be forwarded to "[email protected]" which would create a loop.

You can instead use a subdomain for your custom domain, e.g. "mail.example.com" instead of "example.com", this would allow you to create *@mail.example.com for your aliases. More details can be found here.

If you have a custom domain say example.com and you are already using it for email somewhere else e.g. ProtonMail or Namecheap then you cannot also use it simultaneously with addy.io.

This is because emails cannot be handled by multiple different mail servers at the same time, even if they have the same priority MX records. It can only be delivered to one mail server at a time which will typically be the MX record with the smallest number since this has the highest priority.

You can either:

• Migrate your domain to addy.io by removing the current provider's MX records and adding addy.io's.
• Or, if you would like to keep using your domain with your current email provider then I would recommend instead adding a subdomain of it to addy.io such as mail.example.com.

Using a subdomain will not interfere with your current email setup and you'll be able to create aliases *@mail.example.com through addy.io.

Here are a few reasons I can think of:

• Bring your own GPG/OpenPGP key to encrypt your forwarded emails (and the option to replace subjects)
• No adverts
• No analytics or trackers (just server access logs)
• No third party content
• Open-source application code
• No limitation on the number of aliases that can be created
• Generous monthly bandwidth
• Multiple domains to choose for aliases (currently anonaddy.com, anonaddy.me and more for paid plan users)
• Ability to generate random character and random word aliases at shared domains
• Ability to add additional usernames to compartmentalise aliases
• New features added regularly

Yes there is an open-source browser extension available to download for Firefox and Chrome (also available on other chromium based browsers such as Brave and Vivaldi). You can use the extension to generate new aliases remotely.

Yes, there is an excellent open-source Android app created by Stjin that is available to download from the Play Store (paid) and F-Droid (free). The developer of this app has put in a lot of time and effort so if you would like to support him please purchase the Play Store version.

There is also another open-source Android app created by KhalidWar available on the Play Store.

Yes, KhalidWar's open-source app from above is also available on the App Store.

Yes, http.james' open-source extension is available on the Raycast Store.

On the recipients page you simply need to click "Add public key" and paste in your public key data. Now all emails forwarded to you will be encrypted with your key. You can even hide and encrypt the subject as addy.io supports protected headers.

Yes attachments are part of the email body and are also encrypted if you have it enabled.

Yes when you have encryption enabled all forwarded emails are signed using our [email protected] private key.

You can add this key to your own keyring so that you can verify emails have come from us.

The fingerprint of the [email protected] key is "26A987650243B28802524E2F809FD0D502E2F695" you can find the key on https://keys.openpgp.org.

1. If the person you are sending your message to already uses GPG/OpenPGP encryption then you can simply encrypt your reply/send from your alias using their public key.

2. If the person you are sending your message to does not use GPG/OpenPGP encryption then you can instead encrypt your reply/send with the [email protected] public key ("26A987650243B28802524E2F809FD0D502E2F695"). Your reply/send will then be automatically decrypted on the addy.io server before being sent on to the correct destination in clear text. This is useful if you wish to hide your replies/sends from your email provider such as Gmail.

Yes, any attached GPG/OpenPGP public keys or GPG/OpenPGP signatures are automatically removed when replying or sending from an alias. This is to prevent you accidentally revealing your real email address which is usually shown as an identity in your public key.

No, you must not mark messages forwarded to you by addy.io as spam as this can damage the reputation of the mail servers and is against the terms and conditions.

If an alias is receiving spam messages then please deactivate it or delete it.

addy.io is signed up to multiple feedback loops (FBLs) that trigger a notification when any messages are marked as spam. Repeatedly marking messages as spam will result in your account being disabled.

No, you must not use addy.io to create large numbers of accounts on other websites/services as this is against the terms and conditions.

Having multiple Free accounts is not considered an acceptable use of our service. Any users found to be abusing this rule may have their accounts disabled. This does not apply to those with a paid subscription.

If you're concerned that your aliases are all linked by your username e.g. @johndoe.anonaddy.com, then you have a couple of options:

1. You can generate random character or random word aliases instead, these are all under a shared domain and cannot be linked to a user.
2. You can add additional usernames and separate your aliases under each of them. e.g. you could have one username for personal stuff, another for work, another for hobbies etc.

The server is located in Amsterdam, Netherlands with Greenhost.net. Greenhost focuses greatly on privacy and security and their servers run entirely on Dutch wind energy. The backup mail server is located in Warsaw, Poland with UpCloud.

It's good to keep your guard up when online so you should never trust anyone 100%. I'll try my best to be as honest and transparent as I can but if you still aren't convinced you can always just fire up your own server and self-host this application. You'll need to know about server administration and PHP. You can find more information here https://github.com/anonaddy/anonaddy#self-hosting.

The limit is currently set to 10 which should suffice in the vast majority of situations.

When you delete your account the following happens:

• All of your recipients are deleted from the database
• All of your aliases that use a shared domain e.g. @anonaddy.me are soft deleted from the database (this is to prevent any chance of another user generating the same alias in the future) any identifying information e.g the alias description is removed
• All of your other aliases are deleted from the database
• All of your custom domains are deleted from the database
• Your user details are deleted from the database
• Your username and any additional usernames that you created are encrypted and added to a table in the database. This is to prevent anybody signing up with the same username in the future.
• Any subscription information is deleted from the database

Yes this will work with any provider, although I can't guarantee it won't land in spam initially.

Each forwarded email has a From: header set. This header will look something like this:

From: <[email protected]>

Where [email protected] is the address of the person who sent you the email and [email protected] is the alias that forwarded you the email.

All you need to do is click reply in your email client or web interface and it will automatically fill the To: field with the correct address.

To check if a reply has worked properly check in your dashboard if the reply count has been incremented for that alias.

For further details please see this help article - Replying to email using an alias.

If you are trying to reply or send from an alias but the email keeps coming back to yourself then it is most likely because you are not sending the message from an email address that is not listed as a verified recipient on your addy.io account.

If you try to reply or send from an alias using an unverified email address then the message will simply be forwarded to you as it would be if it was sent by any other sender.

Please double check that you are indeed sending from a verified recipient email address by inspecting your sent items to see which address it was actually sent from.

If you see the rejection message 550 5.1.1 Recipient address rejected: Address does not exist then this means that the alias has either been deleted or does not yet exist (and you do not have catch-all enabled), you must restore (or create) it before you can send/reply from it.

If you receive an email notification with the subject "Attempted reply/send from alias has failed" then it is usually because you have a verified recipient that is using your own domain which does not have a DMARC policy.

Note: This is referring to your verified recipient address on your addy.io account and not any of your custom domains or the email address that you are replying / sending to

When replying or sending from an alias, additional checks are carried out to ensure it is not a spoofed email. Your addy.io recipient's email domain must pass DMARC checks in order to protect against spoofed emails and to make sure that the reply/send from attempt definitely came from your recipient.

For example if the verified recipient on your addy.io account is [email protected] and you get this email notification then it is because the domain "example.com" does not have a DMARC policy in place.

To resolve this you simply need to add a DMARC record, for example:

You should also have SPF and DKIM records in place.

To learn more about DMARC please see this site - https://dmarc.org/.

If your addy.io recipient is with a popular mail service provider for example: Gmail, Outlook, Tutanota, Mailbox.org, Protonmail etc. then they will already have a DMARC policy in place so you do not need to take any action.

If an incoming email looks like spam (for example, because it has failed its DMARC check) then a red warning banner is added by addy.io before forwarding the message on to you. This warning banner is added in order to help protect you from any potential phishing attempts, for example someone pretending to be your bank.

Most of the time this is nothing to worry about and is just because the sender has not correctly configured their DNS records.

To see why this banner was added you can view the headers of the received email and look for the header called 'X-AnonAddy-Authentication-Results'. This header shows the original email's authentication results and will show you why the email failed its DMARC checks.

Yes, the email banner "This email was sent to..." will be automatically removed when you reply to any messages. You can test this by replying to yourself from one of your aliases.

Make sure not to alter or edit the email banner as this may cause issues when trying to match and remove it. You can still remove it manually from the quoted message of your reply if you wish.

This works in the same way as replying to an email.

Let's say that you have the alias [email protected] and you want to send an email to [email protected].

All you need to do is enter the following in the To: field.

<[email protected]>

Note: you must send the email from a verified recipient on your account.

Then send the email exactly as you would any other. To check that the email has sent successfully, look in your dashboard at the sent count column and see if it has been incremented for that alias.

If you want an easy way to construct the correct email address that you should send to you can click "Send from" next to any alias in the web application and after entering the destination address it will display the right email address to use.

This works exactly the same for shared domain aliases, additional usernames and custom domains.

You can even use the send from feature to create an alias on the fly that does not yet exist. This only works for standard aliases or those at custom domains that behave as a catch-all.

You must generate aliases that use shared domains (e.g. [email protected]) beforehand in order to be able to send from them.

If you need to send an email to an address with an extension e.g. [email protected] then it's exactly the same method:

<[email protected]>

Just enter the extension too!

For further details please see this help article - Sending email from an alias.

No, your real email will not be shown, the email will look as if it has come from us instead. Just make sure not to include anything that might identify you when composing the reply, i.e. your full name.

Yes you can add attachments to emails forwarded and replies. Attachments count towards your bandwidth.

The max email size is currently set to 25MB (including attachments).

If you cancel your subscription it will remain active until the end of your current billing cycle, you will still be able to use your paid plan features until the billing cycle ends.

A few days before your billing cycle ends you will receive an email letting you know the steps you need to take to prevent the loss of any emails. Shortly after ending the following will happen:

• Any custom domains will be deactivated
• Any additional usernames will be deactivated
• If you have any more than 1 recipient they will be deleted
• Paid account settings will be reverted to default values
• Any aliases using paid plan only domains will be deactivated
• If you have any more than 10 aliases using a shared domain e.g. anonaddy.me they will be deactivated
• If your account username has catch-all disabled then it will be enabled

You will not be able to activate any of the above again until you resubscribe.

When you subscribe you can choose which email to provide to Stripe, feel free to use an alias. This email will be used for notifications from Stripe such as; if your card payment fails or if your card has expired.

The following is in place to help prevent spam:

• Rspamd - Fast, free and open-source spam filtering system
• DNS blacklist checks - spamhaus.org
• SPF, DKIM - to check the SPF record on the sender's domain
• DMARC - to check for email spoofing and reject emails that fail
• FQDN - the sender must be using a valid fully qualified domain name
• PTR record check - if the sender has no valid PTR record it is rejected

The server is running a local DNS caching server to improve the speed of queries.

Not unless you are really going to town. Each user is throttled to 200 emails per hour through the server.

Currently you are limited to creating 10 new aliases per hour on the free plan, 20 per hour on the Lite plan and 50 per hour on the Pro plan. If you try to create more than this the emails will be deferred until you are back below the limit.

Each time a new email is received Postfix calculates its size in bytes. A column in the database is then simply incremented by that size when the email is forwarded or a reply is sent. At the start of each month your bandwidth is reset to 0.

I don't use rolling 30 day total as the only way to do this would be to log the date and size of every single email received.

Blocked emails do not count towards your bandwidth (e.g. if an alias is inactive or deleted).

The average email is about 76800 bytes (75KB), this is roughly equivalent to 7,000 words in plain text. So the 10MB monthly allowance would be around 140 emails and the Lite plan's 100MB would be almost 1,400 emails.

If you get close to your limit (over 80%) you'll be sent an email letting you know. If you continue and go over your limit the server will respond to any delivery attempts to your aliases with the following: 552 5.2.2 Recipient address rejected: User over quota until your bandwidth resets the next month or you upgrade your plan.

Yes, you can login with any of your usernames. You can add 1 additional username as a Lite user and up to 10 additional usernames as a Pro user for totals of 2 and 11 respectively (including the one you signed up with).

Please make sure to add [email protected] and any aliases you use to your address book and also to check your spam folder. Make sure to mark emails from addy.io as safe if they turn up in spam.

If an alias has been deleted and you try to send email to it, the emails will be rejected with an error message - "550 5.1.1 Recipient address rejected: Address does not exist".

Check that you have not deactivated the alias, custom domain or additional username. When any of these are deactivated, emails will be silently discarded, they will not be rejected or return any error message.

The sender of the email may be failing SPF, DMARC or DNS blacklist checks resulting in the email being rejected. The sender should also have correct reverse DNS setup and use a FQDN as their hostname.

If you are forwarding emails to an icloud.com email address some users are having issues with a small number of emails being rejected (often those from Facebook).

For some reason Apple seems to think these emails are spam/phishing and returns this error message:

Diagnostic-Code: smtp; 550 5.7.1 [CS01] Message rejected due to local policy.

If you are having issues with emails being rejected as "possibly spammy" by Google, iCloud or Microsoft then please try the following steps if you can:

1. Replace the email subject by going to your settings in addy.io
2. Try adding a GPG key and enabling encryption. This will prevent the email's content being scanned and reduce the chance of it being rejected.
3. Enable the option to hide and encrypt the email subject
4. Try disabling the banner information on forwarded emails
5. Try adding the alias email (and/or domain) to your contact list (address book) or safe senders list if possible

For Outlook, Hotmail or MSN you can find instructions on how to add a domain to your safe senders list here.

I will also soon be adding an option to change the format of the display from part of the "From:" header.

If neither of the above options work then please try changing to another recipient so that you can continue to receive emails.

If you still aren't receiving emails please contact me.

If you are having trouble logging in it will likely fall under one of the following scenarios:

1. Incorrect username

Please make sure you are using your account username (e.g. johndoe) and not your email address to try to login.

2. Forgotten password

If you've forgotten your password you can reset it by entering your username here - https://app.addy.io/password/reset

3. Forgotten username

If you've forgotten your username you can request a reminder by entering your email address here - https://app.addy.io/username/reminder

4. Lost 2FA device

Please use the backup code that you were shown when you enabled 2FA.

5. Errors with hardware security key

If you have a YubiKey and are using Windows and have an issue with your personal password/PIN you may need to reset the key using the YubiKey manager software.

I am very passionate about this project. I use it myself every day and will be keeping it running indefinitely. The service also provides me with an income.

I do have someone in place who can keep the service running in the event of me not being here. They are able to continue paying for the servers that host addy.io and the domains that it uses. All addy.io domains also always have over 5 years until they expire.

They would make a Twitter announcement informing all users that they would be keeping the service running. You would then be able to decide whether you'd like to continue using addy.io or start to update your email addresses.

Yes it has over 200 automated PHPUnit tests written.

You will need to set up your own server with Postfix so that you can pipe the received mail to the application. You can find more information here https://github.com/anonaddy/anonaddy#self-hosting.

For those who prefer using Docker there is an image you can use here - github.com/anonaddy/docker.

My name is Will Browning, I'm a web developer from the UK and an advocate for online privacy and open-source software. You can find me on Twitter although I don't tweet that much!

For any other questions just send an email to - contact (at) help.addy.io (GPG Key)

• Postfix (3.0.0+) (plus postfix-mysql for database queries and postfix-pcre)
• PHP (8.2+) and the php-mailparse extension, the php-gnupg extension if you plan to encrypt forwarded emails, the php-imagick extension for generating 2FA QR codes
• Port 25 unblocked and open
• Redis (7.x+) for throttling and queues
• FQDN as hostname e.g. mail.anonaddy.me
• MariaDB / MySQL
• Nginx
• Rspamd
• DNS records - MX, SPF, DKIM, DMARC
• Reverse DNS
• SSL/TLS Encryption - you can install a free certificate from Let’s Encrypt.

For full details please see the self-hosting instructions file.

Thanks to Vlad Timofeev, Patrick Dobler, Luca Steeb, narolinus and Lukas for supporting me by sponsoring the project on GitHub!

Also an extra special thanks to CrazyMax for sponsoring me and also creating and maintaining the awesome addy.io Docker image!

Huge thank you to Stjin and KhalidWar for their amazing mobile apps.

Also to https://gitlab.com/mailcare/mailcare and https://github.com/niftylettuce/forward-email for their awesome open-source projects that helped me along the way.

GNU Affero General Public License v3.0. Please see License File for more information.