Transactional Email API documentationv1alpha1

Download OpenAPI

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

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:

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:

Emails

This section lists the recipient types and the status types of your emails.

Recipient type (rcpt_type):

  • unknown: the recipient of your email is of unknown type.
  • to: the main recipient of your email.
  • cc: other recipients receive a copy of the email.
  • bcc: other recipients receive a hidden copy of your email.

Status of your email:

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

List emails

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

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
string
ID of the Project in which to list the emails (optional). (UUID format).

domain_id
string
ID of the domain for which to list the emails (optional). (UUID format).

message_id
string
ID of the message for which to list the emails (optional). (UUID format).

subject
string
Subject of the email.

since
string
List emails created after this date (optional). (RFC 3339 format).

until
string
List emails created before this date (optional). (RFC 3339 format).

mail_from
string
List emails sent with this `mail_from` sender's address (optional).

mail_to
string
List emails sent with this `mail_to` recipient's address (optional).

statuses
array
List emails having any of this status (optional).
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

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.

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
Subject of the email.

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 the email. (RFC 3339 format).
Request Example
200 Response

emails
array
Single page of emails matching the requested criteria.
Response Example

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

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
Message ID 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 recipient. Possible values are unknown_rcpt_type, to, cc and bcc. The default value is unknown_rcpt_type.

subject
string
Subject of the email.

created_at
nullable string
Creation date of the email object. (RFC 3339 format).

updated_at
nullable string
Last update 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 status information.

try_count
integer
Number of attempts to send the email.

last_tries
array
Information about the last three attempts to send the email.
Response Example

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.

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
Message ID 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 recipient. Possible values are unknown_rcpt_type, to, cc and bcc. The default value is unknown_rcpt_type.

subject
string
Subject of the email.

created_at
nullable string
Creation date of the email object. (RFC 3339 format).

updated_at
nullable string
Last update 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 status information.

try_count
integer
Number of attempts to send the email.

last_tries
array
Information about the last three attempts to send the email.
Response Example

This section lists the statuses of your sender domain.

Status of your domain:

  • unknown: your domain's status cannot be read.
  • pending: your domain's validity has been checked once. It will be fully checked after a pending period.
  • checked: your domain has been checked and is valid. You can send emails from this domain.
  • unchecked: your domain has neither been checked nor validated yet.
  • invalid: your domain is not valid for email sending. The check has failed.
  • locked: your domain is locked. You cannot send emails from this domain.
  • revoked: your domain has been deleted. You cannot send emails from this domain.

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

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
Requested page number. Value must be greater or equal to 1. 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
Number of domains that match the request (without pagination).

domains
array
Response Example

You must specify the region, project_id and domain_name to register a domain in a specific 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
ID of the project to which the domain belongs.

domain_name
string
Fully qualified domain dame.

accept_tos
boolean
Accept Scaleway's Terms of Service.
Request Example
200 Response

id
string
ID of the domain.

organization_id
string
ID of the domain's Organization.

project_id
string
ID of the domain's 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 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 valid. (RFC 3339 format).

revoked_at
nullable string
Date and time of the domain's deletion. (RFC 3339 format).

last_error
nullable string
Error message returned if the last check failed.

spf_config
string
Snippet of the SPF record to register in the DNS zone.

dkim_config
string
DKIM public key to record in the DNS zone.

statistics
object
Domain's statistics.

region
string
Response Example

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

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 domain's Organization.

project_id
string
ID of the domain's 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 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 valid. (RFC 3339 format).

revoked_at
nullable string
Date and time of the domain's deletion. (RFC 3339 format).

last_error
nullable string
Error message returned if the last check failed.

spf_config
string
Snippet of the SPF record to register in the DNS zone.

dkim_config
string
DKIM public key to record in the DNS zone.

statistics
object
Domain's statistics.

region
string
Response Example

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

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 domain's Organization.

project_id
string
ID of the domain's 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 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 valid. (RFC 3339 format).

revoked_at
nullable string
Date and time of the domain's deletion. (RFC 3339 format).

last_error
nullable string
Error message returned if the last check failed.

spf_config
string
Snippet of the SPF record to register in the DNS zone.

dkim_config
string
DKIM public key to record in the DNS zone.

statistics
object
Domain's statistics.

region
string
Response Example

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

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 delete.
Body

Request Example
200 Response

id
string
ID of the domain.

organization_id
string
ID of the domain's Organization.

project_id
string
ID of the domain's 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 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 valid. (RFC 3339 format).

revoked_at
nullable string
Date and time of the domain's deletion. (RFC 3339 format).

last_error
nullable string
Error message returned if the last check failed.

spf_config
string
Snippet of the SPF record to register in the DNS zone.

dkim_config
string
DKIM public key to record in the DNS zone.

statistics
object
Domain's statistics.

region
string
Response Example

This section gives you information about your emails' statuses

Get information on your emails' 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
string
Number of emails for this Project (optional).

domain_id
string
Number of emails sent from this domain (must be coherent with the `project_id` and the `organization_id`) (optional).

since
string
Number of emails created after this date (optional). (RFC 3339 format).

until
string
Number of emails created before this date (optional). (RFC 3339 format).

mail_from
string
Number of emails sent with this `mail_from` sender's address (optional).
200 Response

total_count
integer
Total number of emails matching the requested criteria.

new_count
integer
Number of emails still in the `new` transient state. This means emails received from the API but not yet processed.

sending_count
integer
Number of emails still in the `sending` transient state. This means emails received from the API but not yet in their final status.

sent_count
integer
Number of emails in the final `sent` state. This means emails that have been delivered to the target mail system.

failed_count
integer
Number of emails in the final `failed` state. This means emails that have been refused by the target mail system with a final error status.

canceled_count
integer
Number of emails in the final `canceled` state. This meanns emails that have been canceled upon request.
Response Example