Transactional Email API documentationv1alpha1

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.

Requirements: To perform the following steps, you must first ensure that:

• 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

1. Configure your environment variables.

Note: This is an optional step that seeks to simplify your usage of the Transactional Email API.

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.

3. Create an SPF and a DKIM record.

Tip: Refer to the how to create your SPF and DKIM records documentation page to learn more.

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.

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.

7. Send an email via SMTP.

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

Use your project_id to authenticate as username and your token as a password. Note: It is possible to remove the dashes in UUIDs to shorten them.

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

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.

Retrieve the list of emails sent from a specific domain or for a specific Project or Organization. You must specify the region.

You must specify the region, the sender and the recipient's information and the project_id to send an email from a checked domain. The subject of the email must contain at least 6 characters.

Retrieve information about a specific email using the email_id and region parameters.

You can cancel the sending of an email if it has not been sent yet. You must specify the region and the email_id of the email you want to cancel.

Retrieve domains in a specific project or in a specific Organization using the region parameter.

You must specify the region, project_id and domain_name to register a domain in a specific Project.

Retrieve information about a specific domain using the region and domain_id parameters.

Perform an immediate DNS check of a domain using the region and domain_id parameters.

You must specify the domain you want to delete by the region and domain_id. Deleting a domain is permanent and cannot be undone.

Get information on your emails' statuses.