Sending an email using the Transactional Email API

Reviewed on 04 November 2024 • Published on 24 April 2024

This page shows you how to send a simple transactional email in JSON format to multiple recipients using the additional_headers parameter and the Scaleway Transactional Email API.

Before you start

To complete the actions presented below, you must have:

A Scaleway account logged into the console
Configured your API key
Owner status or IAM permissions allowing you to perform actions in the intended Organization
Installed curl
Configured your domain name with Transactional Email
Added SPF, DKIM, MX and DMARC records to your domain

Open a terminal and paste the following code to configure your environment variables. Make sure that you add your own values.

export SCW_ACCESS_KEY="<API access key>"
export SCW_SECRET_KEY="<API secret key>"
export SCW_PROJECT_ID="<Scaleway Project ID>"

Run the following command to retrieve your domain’s ID, as you will need it in the next step. The output should return your domain’s information.

curl -X GET \
-H "X-Auth-Token: $SCW_SECRET_KEY" \
"https://api.scaleway.com/transactional-email/v1alpha1/regions/fr-par/domains"

Run the following command to ensure that your domain is verified:

curl -X GET "https://api.scaleway.com/transactional-email/v1alpha1/regions/$REGION/domains/<domain-id>" \
-H "X-Auth-Token: $SCW_SECRET_KEY"

Copy the following template. Make sure that you replace the placeholder information with your own.

cat > mail.json <<EOF
{
    "from": {
        "name": "Me", # Replace 'Me' with your own name
        "email": "me@my.domain.example.com"  # Replace 'me@my.domain.example.com' with your email address
    },
    "to": [
        {
            "name": "Your recipient", # Replace 'Your recipient' with your recipient's name
            "email": "your.recipient@mail.fr" # Replace 'your.recipient@mail.fr' with your recipient's email address
        }
    ],
    "subject": "This is a subject", # Replace with your subject. Subjects must have at least 10 characters
    "project_id": "<Scaleway Project ID>", # Replace '<Scaleway Project ID>' with your Scaleway Project ID
    "text": "This is a short sentence.", # Replace with the body of your email
    "html": "<html><body><p>This is a short sentence.</p></body></html>", # Replace with the content you want to send,
    "attachments": [
{
	"name": "test.pdf",
	"type": "application/pdf",
	"content": "AAAA==" # Your PDF encoded in Base64
}
    ],
    "additional_headers": [
        {
            "key": "Reply-To",
            "value": "user1@example.com, user2@example.com, user3@example.com" # Replace the email addresses with the relevant ones
        }
    ]
}
EOF
curl -X POST "https://api.scaleway.com/transactional-email/v1alpha1/regions/$REGION/emails" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -d @mail.json

Once you have added your own information to the template above, run it in your terminal. An output similar to the following should display:

{"emails":[{"id":"655c27f2-b2a3-4a9f-8e1f-3e6dc268b1c4","message_id":"3d928e21-187a-4539-b303-403156e37911","project_id":"8j512135-9f5f-42b3-a900-9fdf0195b563","mail_from":"me@my.domain.example.com","rcpt_to":"your.recipient@mail.fr","rcpt_type":"to","created_at":"2024-04-01T07:55:36.758671147Z","updated_at":"2024-04-01T07:55:36.758671147Z","status":"new","status_details":"not yet processed","try_count":0,"last_tries":[]}]}

Run the following command to check that your email has been sent. Make sure that you replace $EMAIL_ID with the ID of the email you retrieved in the output of the previous step.

curl --request GET \
--url https://api.scaleway.com/transactional-email/v1alpha1/regions/fr-par/emails/$EMAIL_ID \
--header 'X-Auth-Token: $SCW_SECRET_KEY'

You should get an output similar to the following:

{
    "id": "655c27f2-b2a3-4a9f-8e1f-3e6dc268b1c4",
    "message_id": "3d928e21-187a-4539-b303-403156e37911",
    "project_id": "8j512135-9f5f-42b3-a900-9fdf0195b563",
    "mail_from": "me@my.domain.example.com",
    "rcpt_to": "your.recipient@mail.fr",
    "rcpt_type": "to",
    "created_at": "2024-04-01T07:55:36.758671Z",
    "updated_at": "2024-04-01T07:55:41.266916Z",
    "status": "sent",
    "status_details": "success",
    "try_count": 1,
    "last_tries": [
        {
            "rank": 1,
            "tried_at": "2024-04-01T07:55:41.266916Z",
            "code": 250,
            "message": "Ok"
        }
    ]
}