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

Concepts

Refer to our dedicated concepts pageOpen in new context 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.

   Code
   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.

   Code
   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 recordsOpen in new context 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 recordOpen in new context 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.

   Code
   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.

   Code
   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 ZonesOpen in new context.

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/acad-template
  • application/acad
  • application/autocad_dwg
  • application/autocad_dxf
  • application/dwf
  • application/dxf
  • application/ics
  • application/pdf
  • application/pkcs10
  • application/pkcs7-mime
  • application/pkcs7-signature
  • application/vnd.dwt
  • application/vnd.ms-excel
  • application/vnd.ms-powerpoint
  • application/vnd.oasis.opendocument.spreadsheet
  • application/vnd.openxmlformats-officedocument.presentationml.presentation
  • application/vnd.openxmlformats-officedocument.presentationml.slideshow
  • application/vnd.openxmlformats-officedocument.presentationml.template
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.openxmlformats-officedocument.spreadsheetml.template
  • application/x-dwf
  • application/x-dwg
  • application/x-dwt
  • application/x-dxf
  • application/x-pdf
  • application/x-pkcs12
  • application/x-pkcs7-certificates
  • application/x-pkcs7-certreqresp
  • application/x-pkcs7-crl
  • application/x-pkcs7-mime
  • application/x-pkcs7-signature
  • application/xml
  • image/gif
  • image/jpeg
  • image/jpg
  • image/png
  • image/svg+xml
  • image/vnd.dwg
  • image/vnd.dxf
  • model/vnd.dwf
  • text/calendar
  • text/csv
  • text/html
  • text/plain
  • text/xml
• Attachment size is limited to 2 MB via API and 50 MB via SMTP.
• The recursive SPF include directive is not supported

Going further

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

• Transactional Email DocumentationOpen in new context
• Scaleway Slack CommunityOpen in new context join the #transactional-email channel
• Contact our support teamOpen in new context.