Transactional Email API

Introduction

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

Concepts

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

Quickstart

1. Configure your environment variables.

   Note

   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 "https://api.scaleway.com/transactional-email/v1alpha1/regions/$REGION/domains" \
       -H "X-Auth-Token: $SCW_SECRET_KEY" \
       -d "{\"domain_name\":\"my.domain.example.com\",\"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.

   Note

   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

   Note

   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 "https://api.scaleway.com/transactional-email/v1alpha1/regions/$REGION/domains/<domain-id>/check" \
       -H "X-Auth-Token: $TOKEN" \
       -d "{}"
   # Wait a few seconds,then run
   curl -X GET "https://api.scaleway.com/transactional-email/v1alpha1/regions/$REGION/domains/<domain-id>" \
       -H "X-Auth-Token: $TOKEN"
   

   Note

   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.

   Note

   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": "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="
           }
       ],
       "additional_headers": [
           {
               "key": "Reply-To",
               "value": "admin@my.domain.example.com"
           },
           {
               "key": "x-project-tracker",
               "value": "1234"
           }
       ]
   }
   EOF
   curl -X POST "https://api.scaleway.com/transactional-email/v1alpha1/regions/$REGION/emails" \
       -H "X-Auth-Token: $TOKEN" \
       -d @mail.json
   

7. Send an email via SMTP.

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

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

Technical information

Regions

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/pkcs7-signature
  • application/vnd.ms-excel
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.openxmlformats-officedocument.spreadsheetml.template
  • application/x-pdf
  • application/xml
  • image/gif
  • image/jpeg
  • image/jpg
  • image/png
  • image/svg+xml
  • 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.