Suggest an edit

Sending an email using the Transactional Email API

Reviewed on 24 April 2024Published 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
  1. 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>"
  2. 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" \
  3. Run the following command to ensure that your domain is verified:

    curl -X GET "$REGION/domains/<domain-id>" \
    -H "X-Auth-Token: $SCW_SECRET_KEY"
  4. 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": "" # Replace '' with your email address
    "to": [
    "name": "Your recipient", # Replace 'Your recipient' with your recipient's name
    "email": "" # Replace '' 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": ",," # Replace the email addresses with the relevant ones
    curl -X POST "$REGION/emails" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -d @mail.json
  5. 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":"","rcpt_to":"","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":[]}]}
  6. 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$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": "",
    "rcpt_to": "",
    "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"
Docs APIScaleway consoleDedibox consoleScaleway LearningScaleway.comPricingBlogCarreer
© 2023-2024 – Scaleway