Configuring Postfix to send emails via Yandex Cloud Postbox

In this tutorial, you will learn how to send emails via Yandex Cloud Postbox using Postfix on a Yandex Compute Cloud VM.

To start sending emails:

1. Get your cloud ready.
2. Create a VM for Postfix.
3. Install and configure Postfix.
4. Send an email.
5. Send a MIME email with an attachment.

If you no longer need the resources you created, delete them.

Get your cloud readyGet your cloud ready

Sign up for Yandex Cloud and create a billing account:

1. Navigate to the management console and log in to Yandex Cloud or create a new account.
2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure.

Learn more about clouds and folders here.

Required paid resourcesRequired paid resources

The infrastructure support costs include:

• Fee for a continuously running VM (see Yandex Compute Cloud pricing).
• Fee for using a public IP address (see Yandex Virtual Private Cloud pricing).
• Fee for using Yandex Cloud Postbox (see Yandex Cloud Postbox pricing).
• Fee for public DNS queries and DNS zones, if you are creating a resource record in Cloud DNS (see Cloud DNS pricing).

Set up resourcesSet up resources

1. Create an address.

2. Pass a domain ownership check.

3. Create a service account in the folder as the address. If you create the service account and address in different folders, you will get an error when attempting to send an email.

4. Assign the postbox.sender role to the service account.

5. Create a key for the service account:

   • To send an email over SMTP with API key authentication, create an API key. When creating an API key, set the scope for yc.postbox.send. Save the secret key you got in a secure location. You will not be able to view the secret key parameters again after you close the window.
   • To send an email using the AWS CLI or via SMTP with password authentication, create a static access key. Save the ID and secret key to a secure location. You will not be able to view the secret key parameters again after you close the window.

Create a VM for PostfixCreate a VM for Postfix

Install and configure PostfixInstall and configure Postfix

1. Connect to the VM over SSH:

   ssh -i <path_to_private_SSH_key> <VM_user_name>@<VM_public_IP_address>
   

2. Install Postfix and the required modules:

   sudo apt update
   sudo apt install -y postfix libsasl2-modules
   

3. Once installation is complete, the Postfix setup interface will open in the terminal:

   1. In the first step, select Internet with smarthost, then use TAB to select OK and press Enter.
   2. Select OK in all subsequent steps.
   3. Wait for the setup to complete.

4. Run the following command to configure Postfix:

   sudo postconf -e \
   "relayhost = postbox.cloud.yandex.net:587" \
   "smtp_sasl_auth_enable = yes" \
   "smtp_sasl_security_options = noanonymous" \
   "smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd" \
   "smtp_use_tls = yes" \
   "smtp_tls_security_level = secure" \
   "smtp_tls_note_starttls_offer = yes"
   

5. Check if a fallback relay is set and disable it if so:

   1. Open the terraform.tfvars file and find the following line:

      -o smtp_fallback_relay=
      

   2. If you find this line, prepend it with # to comment it out.

   3. Save the file.

6. Provide your SMTP credentials for Yandex Cloud Postbox:

   1. Open or create the /etc/postfix/sasl_passwd file and add the following line to it:

      postbox.cloud.yandex.net:587 SMTP_USERNAME:SMTP_PASSWORD
      

   2. Get authenticated:

      API key

      Static access key

      In the /etc/postfix/sasl_passwd file:

      • Replace SMTP_USERNAME with the API key ID you got when setting up your resources.
      • Replace SMTP_PASSWORD with the secret part of the API key.

      1. Create a file named generate.py and paste this code into it:

         #!/usr/bin/env python3
         
         import hmac
         import hashlib
         import base64
         import argparse
         import sys
         
         # These values are required to calculate the signature. Do not change them.
         DATE = "20230926"
         SERVICE = "postbox"
         MESSAGE = "SendRawEmail"
         REGION = "ru-central1"
         TERMINAL = "aws4_request"
         VERSION = 0x04
         
         
         def sign(key, msg):
             return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
         
         
         def calculate_key(secret_access_key):
             signature = sign(("AWS4" + secret_access_key).encode("utf-8"), DATE)
             signature = sign(signature, REGION)
             signature = sign(signature, SERVICE)
             signature = sign(signature, TERMINAL)
             signature = sign(signature, MESSAGE)
             signature_and_version = bytes([VERSION]) + signature
             smtp_password = base64.b64encode(signature_and_version)
             return smtp_password.decode("utf-8")
         
         
         def main():
             if sys.version_info[0] < 3:
                 raise Exception("Must be using Python 3")
         
             parser = argparse.ArgumentParser(
                 description="Convert a Secret Access Key to an SMTP password."
             )
             parser.add_argument("secret", help="The Secret Access Key to convert.")
             args = parser.parse_args()
         
             print(calculate_key(args.secret))
         
         
         if __name__ == "__main__":
             main()
         

      2. Generate a password:

         python3 generate.py <secret_key>
         

         Where <secret_key> is the secret key of the service account's static access key you got when setting up your resources.

         Use Python 3 or higher.

      3. In the /etc/postfix/sasl_passwd file:

         • Replace SMTP_USERNAME with the static access key ID.
         • Replace SMTP_PASSWORD with the generated password.

   3. Save the /etc/postfix/sasl_passwd file.

7. Create a hash table with the credentials:

   sudo postmap hash:/etc/postfix/sasl_passwd
   

8. Restrict access to the credential files (recommended):

   sudo chown root:root /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
   sudo chmod 0600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
   

9. Provide the root certificate to verify the TLS connection:

   sudo postconf -e 'smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt'
   

10. Restart Postfix to apply the settings:

    sudo systemctl restart postfix
    

Send an emailSend an email

In this example, you will send a plain text email without attachments.

1. Run this command:

   sendmail -f <sender_address> <recipient_address>
   

   Warning

   Here and in subsequent steps, the sender address must match the domain you verified ownership for when setting up your resources.

2. Paste the following text into the terminal and press Enter:

   From: <sender_address>
   Subject: Test Yandex Cloud Postbox via Postfix
   
   This is a test message sent via Yandex Cloud Postbox (SMTP, Postfix).
   .
   

3. Check the recipient's mailbox.

   If no email arrived, review the Postfix log: /var/log/mail.log.

Send a MIME email with an attachmentSend a MIME email with an attachment

In this example, you will send an email with HTML content and attached example.txt.

1. Create a file named mime-email.txt and paste this code into it:

   From: <sender_address>
   Subject: Test email via Yandex Cloud Postbox
   MIME-Version: 1.0
   Content-Type: multipart/mixed; boundary="BOUNDARY-OUTER"
   
   --BOUNDARY-OUTER
   Content-Type: multipart/alternative; boundary="BOUNDARY-INNER"
   
   --BOUNDARY-INNER
   Content-Type: text/plain; charset=UTF-8
   Content-Transfer-Encoding: quoted-printable
   
   This is the plain text part sent via Yandex Cloud Postbox SMTP.
   
   --BOUNDARY-INNER
   Content-Type: text/html; charset=UTF-8
   Content-Transfer-Encoding: quoted-printable
   
   <html>
     <body>
       <h1>Hello!</h1>
       <p>This is the HTML part sent via Yandex Cloud Postbox SMTP.</p>
     </body>
   </html>
   --BOUNDARY-INNER--
   
   --BOUNDARY-OUTER
   Content-Type: application/octet-stream
   MIME-Version: 1.0
   Content-Transfer-Encoding: base64
   Content-Disposition: attachment; filename="example.txt"
   
   U2FtcGxlIGF0dGFjaG1lbnQgY29udGVudA==
   --BOUNDARY-OUTER--
   

   Where:

   • From:: Sender's email address.
   • Subject:: Email subject.

2. Send the email:

   sendmail -f <sender_address> <recipient_address> < mime-email.txt
   

3. Check the recipient's mailbox.

   If no email arrived, review the Postfix log: /var/log/mail.log.

Delete the resources you createdDelete the resources you created

To stop paying for the resources you created:

1. Delete postfix-server.
2. Delete the address.
3. Delete the DNS zone if you created a resource record in it.