Home Managed Services Transactional Email How to

Generate API keys for API and SMTP sending with IAM

Jump toUpdate content

How to generate API keys for API and SMTP sending with IAM

Reviewed on 07 November 2023 • Published on 07 November 2022

This page shows you how to generate API keys with IAM to send transactional emails via API and SMTP.

Security & Identity (IAM):

You may need certain IAM permissions to carry out some actions described on this page. This means:

you are the Owner of the Scaleway Organization in which the actions will be carried out, or
you are an IAM user of the Organization, with a policy granting you the necessary permission sets

Requirements:

You have an account and are logged into the Scaleway console.
You are the Owner of your Organization, or an IAM user in an Organization where you have the IAMManager permission set.
You have a domain name.
You have configured your domain with Transactional Email.
You have added SPF, DKIM and MX records to your domain.

Generate an API key using IAM and send emails via the API

To send your emails via the API, a valid API key and your Project ID are required.

Create an IAM application.
Create a policy giving appropriate permissions to carry out actions for Transactional Email in the desired Project(s), with the IAM application attached as a principal.
Create an API key for your application.
Important:
Make sure you save your secret and access keys as you will need them in the following step.
Open a terminal on your computer and type the following command to send an email via the API:

cat > mail.json <<EOF
{
    "from": {
        "name": "Alice",
        "email": "alice@my.domain.example.com"
    },
    "to": [
        {
        "name": "Bob",
        "email": "bob@caramail.fr"
        }
    ],
    "subject": "Some subject",
    "text": "Some text.",
    "html": "<p>Some <span style=\"font-weight:bold\">HTML</span>.</p>",
    "project_id": "<project-id>",
    "attachments": [
        {
            "name": "file.html",
            "type": "text/html; charset=\"utf8\"",
            "content": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KICAgIDxoZWFkPgogICAgICAgIDxtZXRhIGNoYXJzZXQ9InV0Zi04Ij4KICAgICAgICA8dGl0bGU+dGl0bGU8L3RpdGxlPgogICAgPC9oZWFkPgogICAgPGJvZHk+CiAgICAgICAgPHA+SGVsbG8gPHNwYW4gc3R5bGU9ImNvbG9yOmJsdWUiPndvcmxkPC9zcGFuPiE8L3A+CiAgICA8L2JvZHk+CjwvaHRtbD4="
        }
    ]
}
EOF
curl -X POST "https://api.scaleway.com/transactional-email/v1alpha1/regions/$REGION/emails" \
-H "X-Auth-Token: $TOKEN" \
-d @mail.json

Important:

If you have not configured your environment on your local machine, make sure you replace \<project_id\> with your Project ID, $REGION with fr-par and $TOKEN with your secret key. If you do not replace the Project ID, the API displays a “permission denied” error message
Make sure you replace the email addresses with yours and your recipient’s

The following output should display:

{"emails":[{"id":"655c27f2-b2a3-4a9f-8e1f-3e6dc268b1c4","message_id":"3d928e21-187a-4539-b303-403156e37911","project_id":"3e44a89e-1f75-45f5-9b93-422db94165eb","mail_from":"alice@my.domain.example.com","rcpt_to":"bob@caramail.fr","rcpt_type":"to","created_at":"2022-08-01T07:55:36.758671147Z","updated_at":"2022-08-01T07:55:36.758671147Z","status":"new","status_details":"not yet processed","try_count":0,"last_tries":[]}]}%

Generate an API key using IAM to send emails via SMTP

Note:

Scaleway supports the PLAIN and LOGIN authentication methods.

The Transactional Email SMTP relay is available at smtp.tem.scw.cloud on ports 25, 587, 2587 (non TLS), 465 and 2465 (TLS). To send your emails using SMTP, a valid API secret key and your Project ID are required.

Generate an API key as shown above.
Authenticate yourself to the server using your Project ID as username.
Use your secret key as password and start sending emails.