Sending an email

Written by

Yandex Cloud

Updated at September 19, 2025

Getting started
Sending an email

In Yandex Cloud Postbox, you can send an email:

Using the AWS CLI.
From a mail client via SMTP.
Using the AWS SDK.
Using cURL.

Note

To ensure the security of data transfer, Yandex Cloud Postbox supports TLS protocol versions 1.2 and 1.3.

Getting started

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.
Assign the postbox.sender role to the service account.
Create a key for the service account:
- 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.
- 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.
- IAM token. This authorization method is suitable for sending emails from functions in Cloud Functions and containers in Serverless Containers, as well as for Compute Cloud VMs linked to a service account. Select this method if you do not want to create and store static access keys.
  
  Warning
  
  Note that an IAM token is valid for up to 12 hours. If you need to provide authorization data in the mail client configuration file, use authentication by API key or password.
Available combinations of authentication and emailing methods:

Emailing method
Authentication method
AWS CLI SMTP AWS SDK cURL

API_key

Static access key

IAM_token

Sending an email

AWS CLI

Static access key

Install the AWS CLI.
Set up the AWS CLI:
1. Launch the interactive profile setup:
```
aws configure
```
2. Specify the previously obtained key ID of the postbox-user service account:
```
AWS Access Key ID [****************ver_]: <service_account_key_ID>
```
3. Specify the previously obtained secret key of the postbox-user service account:
```
AWS Secret Access Key [****************w5lb]: <service_account_secret_key>
```
4. Specify the ru-central1 default region name:
```
Default region name [ru-central1]: ru-central1
```
5. Specify JSON as the default format for output data:
```
Default output format [None]: json
```

Prepare two JSON files:

destination.json: File with a list of destination addresses:
```
{
  "ToAddresses": ["test@example.com"]
}
```

message.json: File with the subject and content of the email:

{
  "Simple": {
    "Subject": {
      "Data": "Test message",
      "Charset": "UTF-8"
    },
    "Body": {
      "Text": {
        "Data": "Test message. Hello!",
        "Charset": "UTF-8"
      }
    }
  }
}

Send an email using the AWS CLI:

aws sesv2 send-email \
  --from-email-address mail@example.com \
  --destination file://destination.json \
  --content file://message.json \
  --endpoint-url https://postbox.cloud.yandex.net

Check the mailbox specified in destination.json for the email.

SMTP

API key

Static access key

IAM token

In the SMTP server settings of your email client, specify the following parameters:

	Email client supports STARTTLS	Email client supports SMTPS instead of STARTTLS
Server name	`postbox.cloud.yandex.net`
Port	`587`	`465`
Username	ID of the created API key
Password	Secret part of the created API key

Send an email using your email client and make sure the specified recipients receive it.

Get a password using the previously created static access key of the service account. To do this, run the generate.py script. Use Python 3 or higher.

python generate.py <service_account_secret_key>

generate.py

#!/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()

In the SMTP server settings of your email client, specify the following parameters:

	Email client supports STARTTLS	Email client supports SMTPS instead of STARTTLS
Server name	`postbox.cloud.yandex.net`
Port	`587`	`465`
Username	ID of the previously created static access key
Password	Password obtained in the previous step

Send an email using your email client and make sure the specified recipients receive it.

In your SMTP mail client settings, specify the following parameters:

	Email client supports STARTTLS	Email client supports SMTPS instead of STARTTLS
Server name	`postbox.cloud.yandex.net`
Port	`587`	`465`
Username	`IAM_TOKEN`
Password	Service account IAM token

Send an email using your email client and make sure the specified recipients receive it.

AWS SDK

You can send an email using the AWS SDK for .NET Core, Go, JavaScript, and Python. For more details, see these tutorials:

cURL

To send an email using cURL, run this command:

Static access key

IAM token

curl \
    --request POST \
    --url 'https://postbox.cloud.yandex.net/v2/email/outbound-emails' \
    --header 'Content-Type: application/json' \
    --user "${KEY_ID}:${SECRET_KEY}" \
    --aws-sigv4 "aws:amz:ru-central1:ses" \
    --data-binary '@email.json'

curl \
    --request POST \
    --url 'https://postbox.cloud.yandex.net/v2/email/outbound-emails' \
    --header 'Content-Type: application/json' \
    --header 'X-YaCloud-SubjectToken: <IAM_token>' \
    --data '{
        "FromEmailAddress": "<sender>",
        "Destination": {
            "ToAddresses": ["<recipient>"]
        },
        "Content": {
            "Simple": {
                "Subject": {
                    "Data": "<subject>"
                },
                "Body": {
                    "Text": {
                        "Data": "<email text>"
                    }
                }
            }
        }
    }'

You can provide the request body in the command line argument or file.

File example

{
    "FromEmailAddress": "<sender>",
    "Destination": {
        "ToAddresses": ["<recipient>"]
    },
    "Content": {
        "Simple": {
            "Subject": {
                "Data": "<subject>"
            },
            "Body": {
                "Text": {
                    "Data": "<email text>"
                }
            }
        }
    }
}

To use AWS Signature Version 4 to sign a request, specify the --aws-sigv4 parameter. To learn how to create a signature by yourself, see Signing requests.

Emailing method Authentication method	AWS CLI	SMTP	AWS SDK	cURL
API_key
Static access key
IAM_token

Sending an email

Getting startedGetting started

Sending an emailSending an email

AWS CLIAWS CLI

SMTPSMTP

AWS SDKAWS SDK

cURLcURL

Was the article helpful?

Getting started

Sending an email

AWS CLI

SMTP

AWS SDK

cURL