openapi: 3.1.2
info:
  title: SendPulse SMTP API
  description: >
    The SendPulse SMTP API allows you to send transactional emails, manage
    unsubscribed users,  monitor bounces, and configure sender identities.  SMTP
    is ideal for high-volume transactional messages like order confirmations, 
    password resets, and notifications.
  version: 1.0.0
  x-ai-description: >
    Expert-level SMTP relay service for transactional and bulk email delivery. 
    This API provides granular control over the delivery lifecycle, including 
    sender IP management, bounce tracking, and multi-channel fallback support.
  license:
    name: Apache 2.0
    identifier: Apache-2.0
servers:
  - url: https://api.sendpulse.com
paths:
  /smtp/emails:
    post:
      summary: Send an email
      operationId: sendSmtpEmail
      tags:
        - Emails
      x-ai-role: email_deliverability_expert
      x-ai-description: >
        Triggers the delivery of a transactional email using either custom
        HTML/text  or a pre-defined system template. This is the primary
        endpoint for  high-priority communications.
      x-ai-reasoning-instructions:
        - >-
          Determine if the user is providing raw HTML/text or using a template
          ID.
        - >-
          If using attachments, ensure the file size is within limits and
          contents are Base64 encoded if using `attachments_binary`.
        - >-
          Validate that the sender email is already verified in the SendPulse
          account.
      x-ai-responding-instructions:
        - Confirm successful queuing by returning the internal Message ID.
        - If a template is used, mention that variables were mapped correctly.
        - Advise on checking delivery status via the `id` returned.
      x-ai-suggestions:
        - Use `template` for consistent branding across transactional emails.
        - 'Set `auto_plain_text: true` if you only provide HTML.'
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - PIIHandling
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: object
                  required:
                    - subject
                    - from
                    - to
                  oneOf:
                    - required:
                        - html
                        - text
                    - required:
                        - template
                  properties:
                    html:
                      type: string
                      description: HTML version of an email, encoded in Base64
                    text:
                      type: string
                      description: Text version of the email
                    template:
                      type: object
                      required:
                        - id
                        - variables
                      properties:
                        id:
                          oneOf:
                            - type: string
                            - type: integer
                          description: Template ID
                        variables:
                          type: object
                          description: Template variables mapping
                    auto_plain_text:
                      type: boolean
                      default: false
                    subject:
                      type: string
                    from:
                      type: object
                      required:
                        - name
                        - email
                      properties:
                        name:
                          type: string
                        email:
                          type: string
                    to:
                      type: array
                      items:
                        type: object
                        required:
                          - email
                        properties:
                          name:
                            type: string
                          email:
                            type: string
                    reply_to:
                      type: object
                      properties:
                        name:
                          type: string
                        email:
                          type: string
                    cc:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                          email:
                            type: string
                    bcc:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                          email:
                            type: string
                    attachments:
                      type: object
                      description: Filename to content mapping
                    attachments_binary:
                      type: object
                      description: Filename to Base64 content mapping
      responses:
        '200':
          description: Email sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  id:
                    type: string
                    example: pzkic9-0afezp-fc
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                account.expired:
                  summary: account.expired
                  value:
                    message: Account expired
                    error_code: 403
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                email.required:
                  summary: email.required
                  value:
                    message: Argument email missing
                    error_code: 422
                from.email.required:
                  summary: from.email.required
                  value:
                    message: Argument from.email missing
                    error_code: 10
                from.email.invalid:
                  summary: from.email.invalid
                  value:
                    message: Argument from.email is invalid
                    error_code: 10
                email.to.invalid:
                  summary: email.to.invalid
                  value:
                    message: Argument email.to is invalid
                    error_code: 11
                subject.required:
                  summary: subject.required
                  value:
                    message: Argument subject missing
                    error_code: 12
                email.body.missing:
                  summary: email.body.missing
                  value:
                    message: Missed email body
                    error_code: 13
                template.id.required:
                  summary: template.id.required
                  value:
                    message: Argument template.id missing
                    error_code: 10
                template.invalid:
                  summary: template.invalid
                  value:
                    message: Argument template is invalid
                    error_code: 422
                from.invalid:
                  summary: from.invalid
                  value:
                    message: Argument from is invalid
                    error_code: 422
                attachments_binary.invalid:
                  summary: attachments_binary.invalid
                  value:
                    message: Argument attachments_binary is invalid
                    error_code: 422
                recipients.too_many:
                  summary: recipients.too_many
                  value:
                    message: 5.5.3 Too many recipients
                    error_code: 550
                data.malformed:
                  summary: data.malformed
                  value:
                    message: Badly formed incoming data
                    error_code: 999
                recipient.email.invalid:
                  summary: recipient.email.invalid
                  value:
                    message: Recipient email is invalid
                    error_code: 422
                template.not_found:
                  summary: template.not_found
                  value:
                    message: Template not found
                    error_code: 31
                template.body.empty:
                  summary: template.body.empty
                  value:
                    message: Template body is empty
                    error_code: 32
                variables.format_invalid:
                  summary: variables.format_invalid
                  value:
                    message: Variables list passed in wrong format
                    error_code: 731
                smtp_user.not_found:
                  summary: smtp_user.not_found
                  value:
                    message: No such SMTP user, you need to create SMTP account first
                    error_code: 400
                message.size_exceeded:
                  summary: message.size_exceeded
                  value:
                    message: Message size limit exceeded
                    error_code: 422
                sending.limited:
                  summary: sending.limited
                  value:
                    message: >-
                      Sending from your account is currently limited. Please try
                      later.
                    error_code: 422
                quota.exceeded:
                  summary: quota.exceeded
                  value:
                    message: Sending quota or bandwidth exceeded
                    error_code: 422
                sender.invalid:
                  summary: sender.invalid
                  value:
                    message: Sender is not valid
                    error_code: 422
    get:
      summary: Get a list of emails
      operationId: getSmtpEmails
      tags:
        - Emails
      x-ai-role: marketing_automation_specialist
      x-ai-description: >
        Retrieves historical delivery data for sent emails. Useful for auditing 
        campaign performance and debugging delivery issues for specific
        recipients.
      x-ai-reasoning-instructions:
        - Apply date filters (`from`, `to`) to narrow down the search window.
        - Use pagination (`limit`, `offset`) for large datasets.
      x-ai-responding-instructions:
        - Summarize the delivery status of the retrieved emails.
        - Highlight any 'Bad recipients' or bounce codes if present.
      x-ai-suggestions:
        - Filter by `recipient` to troubleshoot specific user complaints.
      x-ai-capabilities:
        confirmation:
          type: None
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
        - name: from
          in: query
          schema:
            type: string
            format: date
        - name: to
          in: query
          schema:
            type: string
            format: date
        - name: sender
          in: query
          schema:
            type: string
        - name: recipient
          in: query
          schema:
            type: string
        - name: country
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of emails
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmailRecord'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tariff.not_allowed:
                  summary: tariff.not_allowed
                  value:
                    message: Your tariff does not allow the operation
                    error_code: 422
  /smtp/emails/total:
    get:
      summary: Get total amount of sent emails
      operationId: getSmtpEmailsTotal
      tags:
        - Emails
      x-ai-role: compliance_officer
      x-ai-description: >
        Returns the cumulative count of all emails sent through the SMTP
        service.  Critical for billing reconciliation and volume monitoring.
      x-ai-reasoning-instructions:
        - >-
          Check if this matches the expected volume for the current billing
          cycle.
      x-ai-responding-instructions:
        - State the total number of emails sent to date.
      x-ai-suggestions:
        - Monitor this periodically to detect unusual spikes in traffic.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: Total count
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                smtp_user.not_found:
                  summary: smtp_user.not_found
                  value:
                    message: No such SMTP user, you need to create SMTP account first
                    error_code: 400
                tariff.not_allowed:
                  summary: tariff.not_allowed
                  value:
                    message: Your tariff does not allow the operation
                    error_code: 422
  /smtp/emails/{id}:
    get:
      summary: Get information about a specific email
      operationId: getSmtpEmailInfo
      tags:
        - Emails
      parameters: []
      x-ai-role: email_deliverability_expert
      x-ai-description: >
        Provides detailed delivery and tracking metadata for a single email 
        transaction, including SMTP response codes and client interaction
        details.
      x-ai-reasoning-instructions:
        - Look for `smtp_answer_code` to identify specific delivery failures.
        - >-
          Analyze `tracking` data to see if the recipient opened or clicked
          links.
      x-ai-responding-instructions:
        - Detail the exact delivery time and the SMTP server's response.
        - Summarize open and click events if tracking was enabled.
      x-ai-suggestions:
        - >-
          If `smtp_answer_code` is 5xx, advise the user to check the recipient
          status.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: Detailed email information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailRecord'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                email.not_found:
                  summary: email.not_found
                  value:
                    message: No such email
                    error_code: 14
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
  /smtp/emails/info:
    post:
      summary: Get information for a list of emails
      operationId: getSmtpEmailsBatchInfo
      tags:
        - Emails
      x-ai-role: marketing_automation_specialist
      x-ai-description: >
        Batch retrieval of delivery status for up to 500 messages at once. 
        Highly efficient for large-scale synchronization of delivery states.
      x-ai-reasoning-instructions:
        - Ensure the input array does not exceed 500 IDs.
      x-ai-responding-instructions:
        - Summarize the findings for the provided IDs.
      x-ai-suggestions:
        - Use this for bulk updates of internal delivery dashboards.
      x-ai-capabilities:
        confirmation:
          type: None
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - emails
              properties:
                emails:
                  type: array
                  items:
                    type: string
                  maxItems: 500
      responses:
        '200':
          description: List of email records
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmailRecord'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                emails.invalid:
                  summary: emails.invalid
                  value:
                    message: Emails param empty or incorrect
                    error_code: 832
                emails.not_found:
                  summary: emails.not_found
                  value:
                    message: No such emails
                    error_code: 14
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /smtp/bounces/day:
    get:
      summary: Get information about bounces for a 24-hour period
      operationId: getSmtpBouncesDay
      tags:
        - Bounces
      x-ai-role: email_deliverability_expert
      x-ai-description: >
        Retrieves a report of all hard and soft bounces encountered in the  last
        24 hours. Vital for maintaining a healthy sender reputation.
      x-ai-reasoning-instructions:
        - >-
          Analyze the `smtp_answer_data` to categorize the reason for the
          bounce.
        - >-
          Identify patterns that might indicate IP blacklisting or domain
          issues.
      x-ai-responding-instructions:
        - Report the total number of bounces and list the most common reasons.
        - Advise on removing high-frequency bouncers from active lists.
      x-ai-suggestions:
        - Check `total` vs `found` to see if pagination is needed.
      x-ai-capabilities:
        confirmation:
          type: None
      parameters:
        - name: date
          in: query
          schema:
            type: string
            format: date
            example: '2024-01-01'
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Bounce report
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  emails:
                    type: array
                    items:
                      type: object
                      properties:
                        email_to:
                          type: string
                        sender:
                          type: string
                        send_date:
                          type: string
                        subject:
                          type: string
                        smtp_answer_code:
                          type: integer
                        smtp_answer_subcode:
                          type: string
                        smtp_answer_data:
                          type: string
                  request_limit:
                    type: integer
                  found:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /smtp/bounces/day/total:
    get:
      summary: Get total number of bounces
      operationId: getSmtpBouncesTotal
      tags:
        - Bounces
      x-ai-role: compliance_officer
      x-ai-description: >
        Quick count of bounces for the last 24-hour window.  Provides a
        high-level health metric for delivery.
      x-ai-reasoning-instructions:
        - >-
          Compare this count with the total send volume to calculate bounce
          rate.
      x-ai-responding-instructions:
        - State the total number of bounces detected.
      x-ai-suggestions:
        - If bounce rate exceeds 2%, trigger a deeper audit of the source list.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: Total bounce count
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /smtp/unsubscribe:
    post:
      summary: Unsubscribe a recipient
      operationId: unsubscribeSmtpRecipients
      tags:
        - Unsubscribe
      x-ai-role: compliance_officer
      x-ai-description: >
        Manually adds email addresses to the global suppression list for SMTP. 
        Essential for honoring external unsubscribe requests or managing legal
        compliance.
      x-ai-reasoning-instructions:
        - Ensure all email addresses are validly formatted before submission.
      x-ai-responding-instructions:
        - Confirm that the addresses have been added to the suppression list.
      x-ai-suggestions:
        - Include descriptive comments for why the user was unsubscribed.
      x-ai-capabilities:
        confirmation:
          type: Required
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                  - email
                properties:
                  email:
                    type: string
                  comment:
                    type: string
      responses:
        '200':
          description: Unsubscribe successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                emails.empty:
                  summary: emails.empty
                  value:
                    message: Empty emails
                    error_code: 14
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    delete:
      summary: Remove an email from the unsubscribed list
      operationId: removeSmtpUnsubscribe
      tags:
        - Unsubscribe
      x-ai-role: compliance_officer
      x-ai-description: >
        Reinstates a suppressed email address, allowing future SMTP
        communications.  Should only be used when a user explicitly requests to
        re-engage.
      x-ai-reasoning-instructions:
        - Verify that the user has given consent to be re-added.
      x-ai-responding-instructions:
        - Confirm removal from the suppression list.
      x-ai-suggestions:
        - Suggest sending a resubscription confirmation email for double opt-in.
      x-ai-capabilities:
        confirmation:
          type: Required
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Removal successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                emails.empty:
                  summary: emails.empty
                  value:
                    message: Empty emails
                    error_code: 14
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    get:
      summary: Get a list of unsubscribed users
      operationId: getSmtpUnsubscribed
      tags:
        - Unsubscribe
      x-ai-role: marketing_automation_specialist
      x-ai-description: >
        Returns a list of all emails currently in the suppression list.  Used to
        synchronize external CRM systems with SendPulse state.
      x-ai-reasoning-instructions:
        - Filter by date if only recent unsubscribes are needed for sync.
      x-ai-responding-instructions:
        - Summarize the list of unsubscribed users found.
      x-ai-suggestions:
        - >-
          Use `limit` and `offset` to process large suppression lists
          incrementally.
      x-ai-capabilities:
        confirmation:
          type: None
      parameters:
        - name: date
          in: query
          schema:
            type: string
            format: date
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of unsubscribed users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    email:
                      type: string
                    unsubscribe_by_link:
                      type: integer
                    unsubscribe_by_user:
                      type: integer
                    spam_complaint:
                      type: integer
                    date:
                      type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tariff.not_allowed:
                  summary: tariff.not_allowed
                  value:
                    message: Your tariff does not allow the operation
                    error_code: 422
  /smtp/unsubscribe/search:
    get:
      summary: Get information about a contact's subscription status
      operationId: searchSmtpUnsubscribe
      tags:
        - Unsubscribe
      parameters:
        - name: email
          in: query
          required: true
          schema:
            type: string
      x-ai-role: compliance_officer
      x-ai-description: >
        Checks if a specific email address is currently suppressed.  A
        preventative check to avoid sending to users who have opted out.
      x-ai-reasoning-instructions:
        - Run this check before manually triggering a high-value email.
      x-ai-responding-instructions:
        - Clearly state if the user is currently unsubscribed or not.
      x-ai-suggestions:
        - If `result` is true, do not attempt to send emails to this address.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: Subscription status
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                email.empty:
                  summary: email.empty
                  value:
                    message: Empty email parameter
                    error_code: 422
                email.invalid:
                  summary: email.invalid
                  value:
                    message: Wrong email parameter
                    error_code: 422
  /smtp/resubscribe:
    post:
      summary: Resubscribe a recipient
      operationId: resubscribeSmtpRecipient
      tags:
        - Unsubscribe
      x-ai-role: marketing_automation_specialist
      x-ai-description: >
        Sends a formal resubscription request email to a suppressed contact. 
        This is a 'double opt-in' safety mechanism to ensure valid
        re-engagement.
      x-ai-reasoning-instructions:
        - Be aware of the 24-hour limit (max 5 emails per account).
        - Select the appropriate language (`lang`) based on the user's profile.
      x-ai-responding-instructions:
        - Confirm the request email has been sent.
        - Remind the user of the daily rate limit for this action.
      x-ai-suggestions:
        - Default to `en` if user language is unknown.
      x-ai-capabilities:
        confirmation:
          type: Required
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - sender
              properties:
                email:
                  type: string
                sender:
                  type: string
                lang:
                  type: string
                  enum:
                    - ru
                    - en
                    - ua
                    - tr
                    - es
                    - pt
                  default: en
      responses:
        '200':
          description: Resubscription email sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  id:
                    type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                email.required:
                  summary: email.required
                  value:
                    message: Argument email missing
                    error_code: 422
                email.invalid:
                  summary: email.invalid
                  value:
                    message: Argument email is invalid
                    error_code: 422
                sender.required:
                  summary: sender.required
                  value:
                    message: Argument sender missing
                    error_code: 422
                lang.string:
                  summary: lang.string
                  value:
                    message: Argument lang must be string
                    error_code: 422
                email.not_blocked:
                  summary: email.not_blocked
                  value:
                    message: Blocked email not found
                    error_code: 422
                smtp_user.not_found:
                  summary: smtp_user.not_found
                  value:
                    message: Smtp user not found
                    error_code: 503
                daily_limit.exceeded:
                  summary: daily_limit.exceeded
                  value:
                    message: No more than 5 are allowed per day
                    error_code: 422
  /smtp/ips:
    get:
      summary: Get a list of sender’s IP addresses
      operationId: getSmtpIps
      tags:
        - Configuration
      x-ai-role: email_deliverability_expert
      x-ai-description: >
        Lists the outbound IP addresses used by the SendPulse SMTP relay. 
        Essential for customers who need to whitelist specific IPs in their
        firewalls.
      x-ai-reasoning-instructions:
        - Compare these IPs against any known blacklists if delivery drops.
      x-ai-responding-instructions:
        - Provide the list of active IP addresses.
      x-ai-suggestions:
        - Advise the user to add these to their allowed network configurations.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: List of IP addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /smtp/senders:
    get:
      summary: Get a list of sender’s email addresses
      operationId: getSmtpSenders
      tags:
        - Configuration
      x-ai-role: email_deliverability_expert
      x-ai-description: >
        Retrieves all verified email addresses authorized for sending.  Only
        these addresses can be used in the `from` field of the send request.
      x-ai-reasoning-instructions:
        - Ensure the user is selecting a valid, already verified sender.
      x-ai-responding-instructions:
        - List all available sender identities.
      x-ai-suggestions:
        - If the desired email is missing, use `addSmtpSender` to add it.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: List of sender emails
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /v2/email-service/smtp/sender_domains:
    get:
      summary: Get a list of allowed domains
      operationId: getSmtpAllowedDomains
      tags:
        - Configuration
      x-ai-role: email_deliverability_expert
      x-ai-description: >
        Lists domains configured for authenticated sending.  Includes SPF/DKIM
        validation status which is critical for inbox placement.
      x-ai-reasoning-instructions:
        - Check `checks.all_checks` to see if the domain is fully authenticated.
        - Identify missing DNS records like SPF or DKIM.
      x-ai-responding-instructions:
        - Summarize the authentication health of the sending domains.
        - Highlight any domains requiring DNS configuration.
      x-ai-suggestions:
        - If `check_dkim` is false, provide the required records to the user.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: Domain list with authentication status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      result:
                        type: boolean
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/DomainRecord'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /senders:
    post:
      summary: Add a sender email
      operationId: addSmtpSender
      tags:
        - Configuration
      x-ai-role: email_deliverability_expert
      x-ai-description: >
        Registers a new email address as an authorized sender.  Triggers a
        verification process to ensure ownership and authorization.
      x-ai-reasoning-instructions:
        - Verify that the domain of the email address is also authorized.
      x-ai-responding-instructions:
        - >-
          Confirm the sender has been added and advise the user to check their
          inbox for verification.
      x-ai-suggestions:
        - >-
          Use business domains rather than free providers (gmail.com) for better
          deliverability.
      x-ai-capabilities:
        confirmation:
          type: Required
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                name:
                  type: string
      responses:
        '200':
          description: Sender added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                email.required:
                  summary: email.required
                  value:
                    message: Argument email missing
                    error_code: 422
                email.invalid:
                  summary: email.invalid
                  value:
                    message: Argument email is invalid
                    error_code: 422
                email.dmarc_error:
                  summary: email.dmarc_error
                  value:
                    message: DMARC policy error. Please, use another sender domain.
                    error_code: 422
                name.required:
                  summary: name.required
                  value:
                    message: Argument name missing
                    error_code: 422
                name.invalid:
                  summary: name.invalid
                  value:
                    message: Argument name is invalid
                    error_code: 422
                email.exists:
                  summary: email.exists
                  value:
                    message: Email already in use
                    error_code: 902
                email.blacklisted:
                  summary: email.blacklisted
                  value:
                    message: This email in blacklist
                    error_code: 904
  /v2/email-service/smtp/sender_domains/{domain}:
    post:
      summary: Add a domain
      operationId: addSmtpDomain
      tags:
        - Configuration
      parameters: []
      x-ai-role: email_deliverability_expert
      x-ai-description: >
        Adds a root domain for white-labeling and professional sender
        authentication.  Crucial for achieving 100% DKIM alignment.
      x-ai-reasoning-instructions:
        - Check if the domain is already present to avoid duplication.
      x-ai-responding-instructions:
        - >-
          Confirm the domain has been added and list the required DNS records
          for authentication.
      x-ai-suggestions:
        - Suggest adding SPF, DKIM, and DMARC records immediately.
      x-ai-capabilities:
        confirmation:
          type: Required
        security_info:
          data_handling:
            - ResourceStateUpdate
      responses:
        '200':
          description: Domain added
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      result:
                        type: boolean
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: integer
    EmailRecord:
      type: object
      properties:
        id:
          type: string
        sender:
          type: string
        total_size:
          oneOf:
            - type: integer
            - type: string
        sender_ip:
          type: string
        smtp_answer_code:
          oneOf:
            - type: integer
            - type: string
        smtp_answer_subcode:
          type: string
        smtp_answer_data:
          type: string
        used_ip:
          type: string
        recipient:
          type:
            - string
            - 'null'
        subject:
          type: string
        send_date:
          type: string
        tracking:
          type: object
          properties:
            click:
              type: integer
            open:
              type: integer
            link:
              type: array
              items:
                type: object
            client_info:
              type: array
              items:
                type: object
    DomainRecord:
      type: object
      properties:
        id:
          type: integer
        user_id:
          type: integer
        service_type:
          type: integer
        service_value:
          type: string
        status:
          type: integer
          description: 0 - inactive, 1 - active
        is_default:
          type: boolean
        ssl_type:
          type: integer
        checks:
          type: object
          properties:
            check_dkim:
              type: boolean
            check_spf:
              type: boolean
            check_dmarc:
              type: boolean
            all_checks:
              type: boolean
            spf_txt_needed:
              type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >
        Static API Key authentication.  A long-lived token generated manually in
        the SendPulse account settings.
      x-ai-description: >
        Permanent authentication token. Ideal for simple integrations without
        token refresh logic.
    oauth2:
      type: oauth2
      description: OAuth 2.0 Client Credentials flow for temporary access tokens.
      flows:
        clientCredentials:
          tokenUrl: https://api.sendpulse.com/oauth/access_token
          scopes: {}
      x-ai-description: >
        Standard OAuth 2.0 flow using Client ID and Client Secret.  Provides
        temporary tokens (valid for 1 hour) for enhanced security.
security:
  - apiKey: []
  - oauth2: []
