openapi: 3.0.0
info:
  title: Soracom and Query Analysis Email API
  description: Run SQL queries against Soracom Query, fetch query schemas, and search SIMs, Inventory devices, and Sigfox devices.
  version: 20250903-043502
servers:
- description: Japan coverage production API endpoint
  url: https://api.soracom.io/v1
- description: Global coverage production API endpoint
  url: https://g.api.soracom.io/v1
tags:
- description: '[Email addresses](/en/docs/email/)'
  name: Email
paths:
  /operators/{operator_id}/emails:
    get:
      description: 'Retrieves a list of email addresses registered to the operator.

        '
      operationId: listEmails
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/EmailsModel'
                type: array
          description: A list of email addresses registered to the operator.
        '400':
          description: 'Invoked using SAM user credentials. This operation is allowed only for root user.

            '
      security:
      - api_key: []
        api_token: []
      summary: List email addresses
      tags:
      - Email
      x-soracom-cli:
      - emails list
  /operators/{operator_id}/emails/{email_id}:
    delete:
      description: 'Deletes the email address corresponding to the specified email address ID from the operator.

        '
      operationId: deleteEmail
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: Email address ID.
        in: path
        name: email_id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Email address successfully deleted.
      security:
      - api_key: []
        api_token: []
      summary: Delete email address
      tags:
      - Email
      x-soracom-cli:
      - emails delete
    get:
      description: 'Retrieves information for the email address corresponding to the specified email address ID.

        '
      operationId: getEmail
      parameters:
      - description: Operator ID.
        in: path
        name: operator_id
        required: true
        schema:
          type: string
      - description: Email address ID.
        in: path
        name: email_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailsModel'
          description: Information about the specified email address.
      security:
      - api_key: []
        api_token: []
      summary: Get email address
      tags:
      - Email
      x-soracom-cli:
      - emails get
  /operators/add_email_token/issue:
    post:
      description: 'Generates an authentication token for adding a new email address and sends it to the specified email address. This authentication token is used with [Email:verifyAddEmailToken API](#/Email/verifyAddEmailToken) to complete email address verification and addition.


        **Warning**: This API can only be executed with root user credentials.

        '
      operationId: issueAddEmailToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueAddEmailTokenRequest'
        description: Request.
        required: true
      responses:
        '200':
          description: Authentication token successfully issued and sent to the specified email address.
        '400':
          description: Exceeds maximum number of emails.
      security:
      - api_key: []
        api_token: []
      summary: Issue an authentication token to add an email address
      tags:
      - Email
      x-soracom-cli:
      - emails issue-add-email-token
  /operators/add_email_token/verify:
    post:
      description: 'Verifies the authentication token issued by [Email:issueAddEmailToken API](#/Email/issueAddEmailToken) and adds the email address to the operator.


        **Warning**: Authentication tokens have an expiration time. Expired authentication tokens cannot be used.

        '
      operationId: verifyAddEmailToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyAddEmailTokenRequest'
        description: Request.
        required: true
      responses:
        '200':
          description: Email address successfully verified and added to the operator.
      summary: Verify an authentication token to add an email address
      tags:
      - Email
      x-soracom-cli:
      - emails verify-add-email-token
components:
  schemas:
    IssueAddEmailTokenRequest:
      properties:
        email:
          description: Email address to be added. Please enter a valid email address format (e.g., user@example.com).
          type: string
        password:
          description: Password of the root user. Required for authentication.
          type: string
      required:
      - email
      - password
      type: object
    VerifyAddEmailTokenRequest:
      properties:
        token:
          description: 'Authentication token issued by [Email:issueAddEmailToken API](#/Email/issueAddEmailToken). The authentication token is sent to the target email address.

            '
          type: string
      required:
      - token
      type: object
    EmailsModel:
      properties:
        createDateTime:
          format: int64
          type: integer
        email:
          type: string
        emailId:
          type: string
        updateDateTime:
          format: int64
          type: integer
        verified:
          description: 'Whether the email address has completed token-based verification.

            - `true`: verified

            - `false`: unverified'
          type: boolean
      required:
      - emailId
      - email
      - verified
      - createDateTime
      - updateDateTime
      type: object
  securitySchemes:
    api_key:
      description: 'API key for authentication. Obtain this from the Soracom User Console or via the Auth API.

        Required in combination with an API token for all authenticated requests.

        '
      in: header
      name: X-Soracom-API-Key
      type: apiKey
    api_token:
      description: 'API token for authentication. This token has an expiration time and must be refreshed periodically.

        Required in combination with an API key for all authenticated requests.'
      in: header
      name: X-Soracom-Token
      type: apiKey