Transactional Email API


Transactional Email is a platform that allows you to send transactional emails. Unlike marketing emails, (which are mass distributions of the same marketing message to multiple recipients), transactional emails are personalized emails sent to individuals in response to events they have triggered (e.g. password recovery, billing information, delivery updates, etc).

With Transactional Email, you can:

  • register a domain from which to send emails
  • send transactional emails via an SMTP relay
  • send transactional emails via a REST API
  • view your email's delivery status
  • cancel emails that you no longer wish to send


Refer to our dedicated concepts page to find definitions of the different terms referring to Transactional Email.


  1. Configure your environment variables.


    This is an optional step that seeks to simplify your usage of the API.

    export SCW_ACCESS_KEY="<API access key>"
    export SCW_SECRET_KEY="<API secret key>"
    export SCW_PROJECT_ID="<Scaleway Project ID>"
  2. Register your domain. Run the following command to register your domain. Make sure you note down the dkim_config that displays in the output, as you will need it for the next steps.

    curl -X POST "$REGION/domains" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -d "{\"domain_name\":\"\",\"project_id\":\"$PROJECT_ID\"}"
  3. Create an SPF and a DKIM record.

    Find out how to create your SPF and DKIM records in our documentation.


    The DKIM private key is discarded when your domain is revoked. You must update the corresponding DKIM record if you register that domain again.

  4. Create an MX record


    Adding an MX record is not mandatory but we recommend you do it to avoid getting your emails rejected.

    Find out how to add an MX record in our documentation.

  5. Perform a check of your domain. Run the following commands to query your domain and then perform a check of your domain.

    curl -X POST "$REGION/domains/<domain-id>/check" \
    -H "X-Auth-Token: $TOKEN" \
    -d "{}"
    # Wait a few seconds,then run
    curl -X GET "$REGION/domains/<domain-id>" \
    -H "X-Auth-Token: $TOKEN"

    If the check fails, last_error will describe what happened. Perform another check request once you have fixed the problem. To ensure good scoring, your DNS must be correctly set up before sending any emails. The domain check is performed asynchronously.

  6. Send an email via the REST API. Run the following command to send an email using the REST API.


    The attachment content must be base64 encoded and is limited to 2MB. In the following example, both html and attachments fields are optional.

    cat > mail.json <<EOF
    "from": {
    "name": "Alice",
    "email": ""
    "to": [
    "name": "Bob",
    "email": ""
    "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="
    "additional_headers": [
    "key": "Reply-To",
    "value": ""
    "key": "x-project-tracker",
    "value": "1234"
    curl -X POST "$REGION/emails" \
    -H "X-Auth-Token: $TOKEN" \
    -d @mail.json
  7. Send an email via SMTP.

    An SMTP relay is available at on ports 25, 587, 2587, 465 (TLS) and 2465 (TLS).

    Use your project_id to authenticate as username and your token as a password.


    It is possible to remove the dashes in UUIDs to shorten them.

  • You have a Scaleway account
  • You are the owner of the domain name you want to use
  • You have your Organization and your Project ID
  • You have created an API key and that the API key has sufficient IAM permissions to perform the actions described on this page.
  • You have installed curl

Technical information


Scaleway's infrastructure spans different regions and Availability Zones.

Transactional Email is available in the Paris region, which is represented by the following path parameter: fr-par.

Technical limitations

  • Transactional Email's attachment types are limited to:
    • application/ics
    • application/pdf
    • application/x-pdf
    • application/xml
    • image/gif
    • image/jpeg
    • image/jpg
    • image/png
    • text/calendar
    • text/csv
    • text/html
    • text/plain
    • text/xml
  • Attachment size is limited to 2MB
  • The recursive SPF include directive is not supported
  • The subject, body and HTML of your emails must have at least 10 characters

Going further

For more information about Transactional Email, you can check out the following pages:

  • Transactional Email Documentation
  • Scaleway Slack Community join the #transactional-email channel
  • Contact our support team.


This section lists your emails and shows you how to manage them.



This section lists your domains, shows you to manage them, and gives you information about them.



This section gives you information about your emails' statuses

Docs APIScaleway consoleDedibox consoleScaleway LearningScaleway.comPricingBlogCarreer
© 2023-2024 – Scaleway