Transactional Email APIv1alpha1

Download OpenAPI

Introduction

Transactional email is used to send an email to an individual in response to an event (e.g. password recovery, billing information, delivery updates, etc). It is not designed for marketing (bulk) emails.

Before sending an email, you must register the sender's domain name and update the zone file for this domain to have proper authentication information in the zone file and prove the domain is yours.

Current Phase: Public beta

Features

This service enables you to:

  • 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

Technical limitations

As of this first beta release, some limitations apply:

  • Attachment type is 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
  • Recursive SPF include directive is not supported
  • Subject, text, html must have at least 10 characters

Step 0: Prerequisites

In order to set up your environment, you can follow the quickstart steps. You can find your project ID in the Scaleway web console.

You will also need to be the legitimate owner and admin of the domain you wish to send emails from.

Step 1: Register your domain

The returned dkim_config is needed for step 3.

Step 2: Create or update an SPF record

Create a TXT record for the registered domain (e.g. my.domain.example.com) containing v=spf1 include:_spf.tem.scw.cloud -all. If an SPF record already exists for that domain, update it so it contains include:_spf.tem.scw.cloud.

Step 3: Create a DKIM record

Create a TXT record for the <project-id>._domainkey sub-domain of the registered domain (e.g. 77ff06f5-6de5-46f2-92fd-a86c1397e0d0._domainkey.my.domain.example.com) containing the DKIM config returned earlier.

Step 4: Check your domain

To ensure good scoring, DNS must be correctly set up before sending any emails. The domain check is performed asynchronously: simply query your domain to view its state.

If the check fails, last_error will describe the problem. Once fixed, just issue another check request.

Step 5: Send an email via REST API

Attachment content must be base64 encoded and is limited to 2MB. Note that, in the following example, both html and attachments fields are optional.

Step 5 (bis): 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).

You must authenticate with your project_id as username and your token as password. Note that it is possible to remove the dashes in UUIDs to shorten them.

Notes

The DKIM private key is discarded when revoking a domain. Thus, you must update the corresponding DKIM record if you re-register that domain.

Emails

Email object.

Recipient type (rcpt_type):

  • unknown: recipient is of unknown type.
  • to: recipient is of To type.
  • cc: recipient is of CC type.
  • bcc: recipient is of BCC type.

Status:

  • unknown: email is in an unknown status.
  • new: email has just been created.
  • sending: email is being processed.
  • sent: email has been accepted by the destination SMTP server.
  • failed: email did not reach destination SMTP server (timeout sending, or refused by the other end).
  • canceled: email has been canceled.

List emails sent from a domain and/or for a project and/or for an organization

GET
/transactional-email/v1alpha1/regions/{region}/emails
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Query Parameters
page
integer
Page number. The default value is 1.
page_size
integer
Page size. The default value is 20.
project_id
nullable string
Optional ID of the project in which to list the emails (UUID format).
domain_id
nullable string
Optional ID of the domain for which to list the emails (UUID format).
message_id
nullable string
Optional ID of the message for which to list the emails (UUID format).
since
nullable string
Optional, list emails created after this date (RFC 3339 format).
until
nullable string
Optional, list emails created before this date (RFC 3339 format).
mail_from
nullable string
Optional, list emails sent with this `mail_from` sender's address.
mail_to
nullable string
Optional, list emails sent with this `mail_to` recipient's address.
statuses
array
Optional, list emails having any of this status.
200 Response
total_count
integer
Count of all emails matching the requested criteria.
emails
array
Single page of emails matching the requested criteria.
Response Example

Send an email

POST
/transactional-email/v1alpha1/regions/{region}/emails
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Body
from
object
Sender information (must be from a checked domain declared in the project).
to
array
Array of recipient information (limited to 1 recipient).
cc
array
Array of recipient information (unimplemented).
bcc
array
Array of recipient information (unimplemented).
subject
string
Message subject.
text
string
Text content.
html
string
HTML content.
project_id
string
ID of the project in which to create the email.
attachments
array
Array of attachments.
send_before
nullable string
Maximum date to deliver mail (RFC 3339 format).
Request Example
200 Response
emails
array
Single page of emails matching the requested criteria.
Response Example

Get information about an email

GET
/transactional-email/v1alpha1/regions/{region}/emails/{email_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
email_id
required string
ID of the email to retrieve.
200 Response
id
string
Technical ID of the email.
message_id
string
MessageID of the email.
project_id
string
ID of the project to which the email belongs.
mail_from
string
Email address of the sender.
rcpt_to
string
Email address of the recipient.
rcpt_type
string
Type of the recipient. Possible values are unknown_rcpt_type, to, cc and bcc. The default value is unknown_rcpt_type.
created_at
nullable string
Creation date of the email object (RFC 3339 format).
updated_at
nullable string
Last update time of the email object (RFC 3339 format).
status
string
Status of the email. Possible values are unknown, new, sending, sent, failed and canceled. The default value is unknown.
status_details
nullable string
Additional information on the status.
try_count
integer
Total number of attempts to send the email.
last_tries
array
Informations about the latest three attempts to send the email.
Response Example

Try to cancel an email if it has not yet been sent

POST
/transactional-email/v1alpha1/regions/{region}/emails/{email_id}/cancel
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
email_id
required string
ID of the email to cancel.
Body
Request Example
200 Response
id
string
Technical ID of the email.
message_id
string
MessageID of the email.
project_id
string
ID of the project to which the email belongs.
mail_from
string
Email address of the sender.
rcpt_to
string
Email address of the recipient.
rcpt_type
string
Type of the recipient. Possible values are unknown_rcpt_type, to, cc and bcc. The default value is unknown_rcpt_type.
created_at
nullable string
Creation date of the email object (RFC 3339 format).
updated_at
nullable string
Last update time of the email object (RFC 3339 format).
status
string
Status of the email. Possible values are unknown, new, sending, sent, failed and canceled. The default value is unknown.
status_details
nullable string
Additional information on the status.
try_count
integer
Total number of attempts to send the email.
last_tries
array
Informations about the latest three attempts to send the email.
Response Example

Domain

Domain validated as sender of an email.

Status:

  • unknown: the domain status cannot be read.
  • pending: the domain has been checked for the first time, it will be fully checked after a pending period.
  • checked: the domain has been checked and is valid, emails can be sent from this domain.
  • unchecked: the domain has not yet been checked nor validated.
  • invalid: the domain is not valid for sending emails (check failed).
  • locked: the domain is locked, emails cannot be sent from this domain.
  • revoked: the domain has been revoked, emails cannot anymore be sent from this domain.

List domains in a project and/or in an organization

GET
/transactional-email/v1alpha1/regions/{region}/domains
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Query Parameters
page
integer
Page number (1 for the first page). The default value is 1.
page_size
integer
Page size. The default value is 20.
project_id
nullable string
status
array
organization_id
nullable string
name
nullable string
200 Response
total_count
integer
Total number of domains matching the request (without pagination).
domains
array
Response Example

Register a domain in a project

POST
/transactional-email/v1alpha1/regions/{region}/domains
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Body
project_id
string
domain_name
string
Request Example
200 Response
id
string
ID of the domain.
organization_id
string
ID of the organization to which the domain belongs.
project_id
string
ID of the project.
name
string
Domain name (example.com).
status
string
Status of the domain. Possible values are unknown, checked, unchecked, invalid, locked, revoked and pending. The default value is unknown.
created_at
nullable string
Date and time of domain's creation (RFC 3339 format).
next_check_at
nullable string
Date and time of the next scheduled check (RFC 3339 format).
last_valid_at
nullable string
Date and time the domain was last found to be valid (RFC 3339 format).
revoked_at
nullable string
Date and time of the revocation of the domain (RFC 3339 format).
last_error
nullable string
Error message if the last check failed.
spf_config
string
Snippet of the SPF record that should be registered in the DNS zone.
dkim_config
string
DKIM public key, as should be recorded in the DNS zone.
statistics
object
Domain's statistics.
region
string
Response Example

Get information about a domain

GET
/transactional-email/v1alpha1/regions/{region}/domains/{domain_id}
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
domain_id
required string
ID of the domain.
200 Response
id
string
ID of the domain.
organization_id
string
ID of the organization to which the domain belongs.
project_id
string
ID of the project.
name
string
Domain name (example.com).
status
string
Status of the domain. Possible values are unknown, checked, unchecked, invalid, locked, revoked and pending. The default value is unknown.
created_at
nullable string
Date and time of domain's creation (RFC 3339 format).
next_check_at
nullable string
Date and time of the next scheduled check (RFC 3339 format).
last_valid_at
nullable string
Date and time the domain was last found to be valid (RFC 3339 format).
revoked_at
nullable string
Date and time of the revocation of the domain (RFC 3339 format).
last_error
nullable string
Error message if the last check failed.
spf_config
string
Snippet of the SPF record that should be registered in the DNS zone.
dkim_config
string
DKIM public key, as should be recorded in the DNS zone.
statistics
object
Domain's statistics.
region
string
Response Example

Ask for an immediate check of a domain (DNS check)

POST
/transactional-email/v1alpha1/regions/{region}/domains/{domain_id}/check
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
domain_id
required string
ID of the domain to check.
Body
Request Example
200 Response
id
string
ID of the domain.
organization_id
string
ID of the organization to which the domain belongs.
project_id
string
ID of the project.
name
string
Domain name (example.com).
status
string
Status of the domain. Possible values are unknown, checked, unchecked, invalid, locked, revoked and pending. The default value is unknown.
created_at
nullable string
Date and time of domain's creation (RFC 3339 format).
next_check_at
nullable string
Date and time of the next scheduled check (RFC 3339 format).
last_valid_at
nullable string
Date and time the domain was last found to be valid (RFC 3339 format).
revoked_at
nullable string
Date and time of the revocation of the domain (RFC 3339 format).
last_error
nullable string
Error message if the last check failed.
spf_config
string
Snippet of the SPF record that should be registered in the DNS zone.
dkim_config
string
DKIM public key, as should be recorded in the DNS zone.
statistics
object
Domain's statistics.
region
string
Response Example

Revoke a domain

POST
/transactional-email/v1alpha1/regions/{region}/domains/{domain_id}/revoke
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
domain_id
required string
ID of the domain to revoke.
Body
Request Example
200 Response
id
string
ID of the domain.
organization_id
string
ID of the organization to which the domain belongs.
project_id
string
ID of the project.
name
string
Domain name (example.com).
status
string
Status of the domain. Possible values are unknown, checked, unchecked, invalid, locked, revoked and pending. The default value is unknown.
created_at
nullable string
Date and time of domain's creation (RFC 3339 format).
next_check_at
nullable string
Date and time of the next scheduled check (RFC 3339 format).
last_valid_at
nullable string
Date and time the domain was last found to be valid (RFC 3339 format).
revoked_at
nullable string
Date and time of the revocation of the domain (RFC 3339 format).
last_error
nullable string
Error message if the last check failed.
spf_config
string
Snippet of the SPF record that should be registered in the DNS zone.
dkim_config
string
DKIM public key, as should be recorded in the DNS zone.
statistics
object
Domain's statistics.
region
string
Response Example

Statistics

Statistical information

Get statistics on the email statuses

GET
/transactional-email/v1alpha1/regions/{region}/statistics
Path Parameters
region
required string
The region you want to target. Possible value is fr-par.
Query Parameters
project_id
nullable string
Optional, count emails for this project.
domain_id
nullable string
Optional, count emails send from this domain (must be coherent with the `project_id` and the `organization_id`).
since
nullable string
Optional, count emails created after this date (RFC 3339 format).
until
nullable string
Optional, count emails created before this date (RFC 3339 format).
mail_from
nullable string
Optional, count emails sent with this `mail_from` sender's address.
200 Response
total_count
integer
Total number of emails matching the request criteria.
new_count
integer
Number of emails still in the `new` transient state (received from the API, not yet processed).
sending_count
integer
Number of emails still in the `sending` transient state (received from the API, not yet in their final status).
sent_count
integer
Number of emails in the final `sent` state (have been delivered to the target mail system).
failed_count
integer
Number of emails in the final `failed` state (refused by the target mail system with a final error status).
canceled_count
integer
Number of emails in the final `canceled` state (canceled by customer's request).
Response Example