Scaleway Emails API

openapi: 3.2.0
info:
  title: Transactional Email Emails API
  description: Transactional Email is a platform that allows you to send transactional emails.
  version: v1alpha1
servers:
- url: https://api.scaleway.com
tags:
- name: Emails
  description: This section lists your emails and shows you how to manage them.
paths:
  /transactional-email/v1alpha1/regions/{region}/emails:
    get:
      tags:
      - Emails
      operationId: ListEmails
      summary: List emails
      description: Retrieve the list of emails sent from a specific domain or for a specific Project or Organization. You must specify the `region`.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      - in: query
        name: page
        schema:
          $ref: '#/components/schemas/google.protobuf.Int32Value'
      - in: query
        name: page_size
        schema:
          type: integer
          format: uint32
      - in: query
        name: project_id
        description: (Optional) ID of the Project in which to list the emails. (UUID format)
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      - in: query
        name: domain_id
        description: (Optional) ID of the domain for which to list the emails. (UUID format)
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      - in: query
        name: message_id
        description: (Optional) ID of the message for which to list the emails. (UUID format)
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      - in: query
        name: since
        description: (Optional) List emails created after this date. (RFC 3339 format)
        schema:
          type: string
          format: date-time
          example: '2022-03-22T12:34:56.123456Z'
      - in: query
        name: until
        description: (Optional) List emails created before this date. (RFC 3339 format)
        schema:
          type: string
          format: date-time
          example: '2022-03-22T12:34:56.123456Z'
      - in: query
        name: mail_from
        description: (Optional) List emails sent with this sender's email address.
        schema:
          type: string
      - in: query
        name: mail_to
        description: Deprecated. List emails sent to this recipient's email address.
        schema:
          type: string
          deprecated: true
      - in: query
        name: mail_rcpt
        description: (Optional) List emails sent to this recipient's email address.
        schema:
          type: string
      - in: query
        name: statuses
        description: (Optional) List emails with any of these statuses.
        schema:
          type: array
          items:
            $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.Email.Status'
      - in: query
        name: subject
        description: (Optional) List emails with this subject.
        schema:
          type: string
      - in: query
        name: search
        description: (Optional) List emails by searching to all fields.
        schema:
          type: string
      - in: query
        name: order_by
        description: (Optional) List emails corresponding to specific criteria.
        schema:
          type: string
          enum:
          - created_at_desc
          - created_at_asc
          - updated_at_desc
          - updated_at_asc
          - status_desc
          - status_asc
          - mail_from_desc
          - mail_from_asc
          - mail_rcpt_desc
          - mail_rcpt_asc
          - subject_desc
          - subject_asc
          x-enum-descriptions:
            values:
              created_at_desc: Order by creation date (descending chronological order)
              created_at_asc: Order by creation date (ascending chronological order)
              updated_at_desc: Order by last update date (descending chronological order)
              updated_at_asc: Order by last update date (ascending chronological order)
              status_desc: Order by status (descending alphabetical order)
              status_asc: Order by status (ascending alphabetical order)
              mail_from_desc: Order by mail_from (descending alphabetical order)
              mail_from_asc: Order by mail_from (ascending alphabetical order)
              mail_rcpt_desc: Order by mail recipient (descending alphabetical order)
              mail_rcpt_asc: Order by mail recipient (ascending alphabetical order)
              subject_desc: Order by subject (descending alphabetical order)
              subject_asc: Order by subject (ascending alphabetical order)
          default: created_at_desc
      - in: query
        name: flags
        description: (Optional) List emails containing only specific flags.
        schema:
          type: array
          items:
            $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.Email.Flag'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.ListEmailsResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  \"https://api.scaleway.com/transactional-email/v1alpha1/regions/{region}/emails\""
      - lang: HTTPie
        source: "http GET \"https://api.scaleway.com/transactional-email/v1alpha1/regions/{region}/emails\" \\\n  X-Auth-Token:$SCW_SECRET_KEY"
    post:
      tags:
      - Emails
      operationId: CreateEmail
      summary: Send an email
      description: You must specify the `region`, the sender and the recipient's information and the `project_id` to send an email from a checked domain.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.CreateEmailResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: object
                  description: Sender information. Must be from a checked domain declared in the Project.
                  properties:
                    email:
                      type: string
                      description: Email address.
                    name:
                      type: string
                      description: (Optional) Name displayed.
                      nullable: true
                  x-properties-order:
                  - email
                  - name
                to:
                  type: array
                  description: An array of the primary recipient's information.
                  items:
                    $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.CreateEmailRequest.Address'
                cc:
                  type: array
                  description: An array of the carbon copy recipient's information.
                  items:
                    $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.CreateEmailRequest.Address'
                bcc:
                  type: array
                  description: An array of the blind carbon copy recipient's information.
                  items:
                    $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.CreateEmailRequest.Address'
                subject:
                  type: string
                  description: Subject of the email.
                text:
                  type: string
                  description: Text content.
                html:
                  type: string
                  description: HTML content.
                project_id:
                  type: string
                  description: ID of the Project in which to create the email. (UUID format)
                  example: 6170692e-7363-616c-6577-61792e636f6d
                attachments:
                  type: array
                  description: Array of attachments.
                  items:
                    $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.CreateEmailRequest.Attachment'
                send_before:
                  type: string
                  description: Maximum date to deliver the email. (RFC 3339 format)
                  format: date-time
                  example: '2022-03-22T12:34:56.123456Z'
                  nullable: true
                additional_headers:
                  type: array
                  description: Array of additional headers as key-value.
                  items:
                    $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.CreateEmailRequest.Header'
              required:
              - from
              x-properties-order:
              - from
              - to
              - cc
              - bcc
              - subject
              - text
              - html
              - project_id
              - attachments
              - send_before
              - additional_headers
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"from\": {\n        \"email\": \"string\",\n        \"name\": \"string\"\n    },\n    \"html\": \"string\",\n    \"project_id\": \"6170692e-7363-616c-6577-61792e636f6d\",\n    \"subject\": \"string\",\n    \"text\": \"string\"\n  }' \\\n  \"https://api.scaleway.com/transactional-email/v1alpha1/regions/{region}/emails\""
      - lang: HTTPie
        source: "http POST \"https://api.scaleway.com/transactional-email/v1alpha1/regions/{region}/emails\" \\\n  X-Auth-Token:$SCW_SECRET_KEY \\\n  from:='{\n    \"email\": \"string\",\n    \"name\": \"string\"\n  }' \\\n  html=\"string\" \\\n  project_id=\"6170692e-7363-616c-6577-61792e636f6d\" \\\n  subject=\"string\" \\\n  text=\"string\""
  /transactional-email/v1alpha1/regions/{region}/emails/{email_id}:
    get:
      tags:
      - Emails
      operationId: GetEmail
      summary: Get an email
      description: Retrieve information about a specific email using the `email_id` and `region` parameters.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      - in: path
        name: email_id
        description: ID of the email to retrieve. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.Email'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  \"https://api.scaleway.com/transactional-email/v1alpha1/regions/{region}/emails/{email_id}\""
      - lang: HTTPie
        source: "http GET \"https://api.scaleway.com/transactional-email/v1alpha1/regions/{region}/emails/{email_id}\" \\\n  X-Auth-Token:$SCW_SECRET_KEY"
  /transactional-email/v1alpha1/regions/{region}/emails/{email_id}/cancel:
    post:
      tags:
      - Emails
      operationId: CancelEmail
      summary: Cancel an email
      description: 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.
      parameters:
      - in: path
        name: region
        description: The region you want to target
        required: true
        schema:
          type: string
          enum:
          - fr-par
      - in: path
        name: email_id
        description: ID of the email to cancel. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.Email'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST \\\n  -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}' \\\n  \"https://api.scaleway.com/transactional-email/v1alpha1/regions/{region}/emails/{email_id}/cancel\""
      - lang: HTTPie
        source: "http POST \"https://api.scaleway.com/transactional-email/v1alpha1/regions/{region}/emails/{email_id}/cancel\" \\\n  X-Auth-Token:$SCW_SECRET_KEY"
components:
  schemas:
    scaleway.transactional_email.v1alpha1.Email.Try:
      type: object
      properties:
        rank:
          type: integer
          description: Rank number of this attempt to send the email.
          format: uint32
        tried_at:
          type: string
          description: Date of the attempt to send the email. (RFC 3339 format)
          format: date-time
          example: '2022-03-22T12:34:56.123456Z'
          nullable: true
        code:
          type: integer
          description: The SMTP status code received after the attempt. 0 if the attempt did not reach an SMTP server.
          format: int32
        message:
          type: string
          description: The SMTP message received. If the attempt did not reach an SMTP server, the message returned explains what happened.
      x-properties-order:
      - rank
      - tried_at
      - code
      - message
    scaleway.transactional_email.v1alpha1.CreateEmailRequest.Header:
      type: object
      properties:
        key:
          type: string
          description: Email header key.
        value:
          type: string
          description: Email header value.
      x-properties-order:
      - key
      - value
    scaleway.transactional_email.v1alpha1.CreateEmailRequest.Address:
      type: object
      properties:
        email:
          type: string
          description: Email address.
        name:
          type: string
          description: (Optional) Name displayed.
          nullable: true
      x-properties-order:
      - email
      - name
    scaleway.transactional_email.v1alpha1.Email.Status:
      type: string
      enum:
      - unknown
      - new
      - sending
      - sent
      - failed
      - canceled
      x-enum-descriptions:
        values:
          unknown: If unspecified, the status of the email is unknown by default
          new: The email is new
          sending: The email is in the process of being sent
          sent: The email was sent
          failed: The sending of the email failed
          canceled: The sending of the email was canceled
      default: unknown
    scaleway.transactional_email.v1alpha1.Email.Flag:
      type: string
      enum:
      - unknown_flag
      - soft_bounce
      - hard_bounce
      - spam
      - mailbox_full
      - mailbox_not_found
      - greylisted
      - send_before_expiration
      - blocklisted
      x-enum-descriptions:
        values:
          unknown_flag: If unspecified, the flag type is unknown by default
          soft_bounce: Refers to a non critical error received while sending the email(s). Soft bounced emails are retried
          hard_bounce: Refers to a critical error that happened while sending the email(s)
          spam: Refers to an email considered as spam
          mailbox_full: Refers to an undelivered email because the recipient mailbox is full
          mailbox_not_found: Refers to an undelivered email because the recipient mailbox does not exist
          greylisted: Refers to an email slightly delayed by the recipient to ensure that Scaleway is not sending spam
          send_before_expiration: Refers to an email with a `send-before` tag to indicate the maximum time limit for the email to be sent
          blocklisted: Refers to an email blocked by a blocklist
      default: unknown_flag
    scaleway.transactional_email.v1alpha1.ListEmailsResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Number of emails matching the requested criteria.
          format: uint32
        emails:
          type: array
          description: Single page of emails matching the requested criteria.
          items:
            $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.Email'
      x-properties-order:
      - total_count
      - emails
    google.protobuf.Int32Value:
      type: integer
      format: int32
      nullable: true
    scaleway.transactional_email.v1alpha1.CreateEmailRequest.Attachment:
      type: object
      properties:
        name:
          type: string
          description: Filename of the attachment.
        type:
          type: string
          description: MIME type of the attachment.
        content:
          type: string
          description: Content of the attachment encoded in base64.
      x-properties-order:
      - name
      - type
      - content
    scaleway.transactional_email.v1alpha1.Email:
      type: object
      properties:
        id:
          type: string
          description: Technical ID of the email.
        message_id:
          type: string
          description: Message ID of the email.
        project_id:
          type: string
          description: ID of the Project to which the email belongs.
        mail_from:
          type: string
          description: Email address of the sender.
        rcpt_to:
          type: string
          description: Deprecated. Email address of the recipient.
          deprecated: true
        mail_rcpt:
          type: string
          description: Email address of the recipient.
        rcpt_type:
          type: string
          description: Type of recipient.
          enum:
          - unknown_rcpt_type
          - to
          - cc
          - bcc
          x-enum-descriptions:
            values:
              unknown_rcpt_type: If unspecified, the recipient type is unknown by default
              to: Primary recipient
              cc: Carbon copy recipient
              bcc: Blind carbon copy recipient
          default: unknown_rcpt_type
        subject:
          type: string
          description: Subject of the email.
        created_at:
          type: string
          description: Creation date of the email object. (RFC 3339 format)
          format: date-time
          example: '2022-03-22T12:34:56.123456Z'
          nullable: true
        updated_at:
          type: string
          description: Last update of the email object. (RFC 3339 format)
          format: date-time
          example: '2022-03-22T12:34:56.123456Z'
          nullable: true
        status:
          type: string
          description: Status of the email.
          enum:
          - unknown
          - new
          - sending
          - sent
          - failed
          - canceled
          x-enum-descriptions:
            values:
              unknown: If unspecified, the status of the email is unknown by default
              new: The email is new
              sending: The email is in the process of being sent
              sent: The email was sent
              failed: The sending of the email failed
              canceled: The sending of the email was canceled
          default: unknown
        status_details:
          type: string
          description: Additional status information.
          nullable: true
        try_count:
          type: integer
          description: Number of attempts to send the email.
          format: uint32
        last_tries:
          type: array
          description: Information about the last three attempts to send the email.
          items:
            $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.Email.Try'
        flags:
          type: array
          description: Flags categorize emails. They allow you to obtain more information about recurring errors, for example.
          items:
            $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.Email.Flag'
      x-properties-order:
      - id
      - message_id
      - project_id
      - mail_from
      - rcpt_to
      - mail_rcpt
      - rcpt_type
      - subject
      - created_at
      - updated_at
      - status
      - status_details
      - try_count
      - last_tries
      - flags
    scaleway.transactional_email.v1alpha1.CreateEmailResponse:
      type: object
      properties:
        emails:
          type: array
          description: Single page of emails matching the requested criteria.
          items:
            $ref: '#/components/schemas/scaleway.transactional_email.v1alpha1.Email'
      x-properties-order:
      - emails
  securitySchemes:
    scaleway:
      in: header
      name: X-Auth-Token
      type: apiKey