AhaSend Email API

openapi: 3.2.0
info:
  title: AhaSend Email API
  description: This is the API documentation for sending emails via AhaSend.com. To use this API you need to get your API Key from your account under the API Keys page.
  termsOfService: https://ahasend.com/terms/
  contact:
    email: support@ahasend.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.1
servers:
- url: https://api.ahasend.com/v1
tags:
- name: Email
  description: APIs for sending emails
  externalDocs:
    description: Find out more
    url: https://ahasend.com
paths:
  /email/send:
    post:
      tags:
      - Email
      summary: AhaSend Send Emails
      description: You can send emails to up to 100 recipients using this API at the same time.
      operationId: sendEmail
      parameters:
      - in: header
        name: Content-Type
        schema:
          type: string
        description: Only application/json is supported
        example: application/json
      requestBody:
        description: Email object.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Email'
        required: true
      responses:
        '201':
          description: Request was accepted. This doesn't necessarily mean immediate delivery or even queueing of the emails for delivery. It just means that the request was well-formed and accepted, but you need to check the response for success_count and fail_count to make sure about the status of your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfulResponse'
              examples:
                sendEmail201Example:
                  summary: Default sendEmail 201 response
                  x-microcks-default: true
                  value:
                    success_count: 1
                    fail_count: 1
                    failed_recipients:
                    - example_value
                    errors:
                    - example_value
        '400':
          description: The request is malformed and could not be validated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
              examples:
                sendEmail400Example:
                  summary: Default sendEmail 400 response
                  x-microcks-default: true
                  value:
                    status: example_value
        '403':
          description: You are not allowed to send for any reason such as invalid credentials, not having access to the sending domain, etc.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedResponse'
              examples:
                sendEmail403Example:
                  summary: Default sendEmail 403 response
                  x-microcks-default: true
                  value:
                    status: example_value
      security:
      - api_key:
        - write:email
        - read:email
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Attachment:
      type: object
      required:
      - data
      - file_name
      - content_type
      properties:
        data:
          type: string
          examples:
          - R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7
          description: The attachment data. If the base64 field is true, this data must be encoded using base64. Otherwise, it will be interpreted as UTF-8.
          example: example_value
        base64:
          type: boolean
          examples:
          - true
          - false
          description: If set to true, data needs to be encoded using base64. Otherwise data will be interpreted as UTF-8.
          example: true
        content_type:
          type: string
          examples:
          - image/gif
          example: example_value
        content_id:
          type: string
          examples:
          - my-image
          description: If specified, this attachment will be added as an inline attachment and a multipart/related MIME container will be generated in the message to hold it and the textual content.
          example: '500123'
        file_name:
          type: string
          examples:
          - my_image.gif
          example: Example Name
    AccessDeniedResponse:
      type: object
      example:
        status: invalid credentials
      properties:
        status:
          type: string
          description: The reason your request failed.
          examples:
          - invalid credentials
          - domain DNS config is not valid
          example: example_value
    Content:
      type: object
      required:
      - subject
      properties:
        subject:
          type: string
          examples:
          - Sample subject
          example: example_value
        text_body:
          type: string
          description: Plaintext body of the email
          examples:
          - Sample email body
          example: example_value
        html_body:
          type: string
          description: HTML body of the email
          examples:
          - <p>Sample email body</p>
          example: example_value
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          example:
          - data: example_value
            base64: true
            content_type: example_value
            content_id: '500123'
            file_name: Example Name
        reply_to:
          $ref: '#/components/schemas/Contact'
        headers:
          type: object
          description: Specify arbitary headers.
          additionalProperties:
            type: string
          example:
            X-My-Mail-ID: '12345'
            X-Comment-ID: '456789'
    BadRequestResponse:
      type: object
      example:
        status: bad request
      properties:
        status:
          type: string
          examples:
          - domain is not yours
          - domain DNS config is not valid
          example: example_value
    SuccessfulResponse:
      type: object
      properties:
        success_count:
          type: integer
          description: Number of messages that were queued for sending.
          example: 1
        fail_count:
          type: integer
          description: Number of messages that failed to be queued for sending.
          example: 1
        failed_recipients:
          type: array
          description: List of email addresses that the email was not sent to.
          example:
          - john@nasa.gov
          items:
            type: string
        errors:
          type: array
          example:
          - 'john@nasa.gov: The email account that you tried to reach does not exist.'
          items:
            type: string
            description: The reason the email failed to be sent to a recipient.
    Email:
      required:
      - from
      - recipients
      - content
      type: object
      properties:
        from:
          $ref: '#/components/schemas/Contact'
        recipients:
          type: array
          description: Specifies the list of recipients to which message will be sent.
          items:
            $ref: '#/components/schemas/Contact'
          example:
          - email: user@example.com
            name: Example Name
        content:
          $ref: '#/components/schemas/Content'
    Contact:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          examples:
          - john@nasa.gov
          - jane@nasa.gov
          example: user@example.com
        name:
          type: string
          examples:
          - John Smith
          - Jane Williams
          example: Example Name
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Api-Key
      in: header
externalDocs:
  description: Find out more about AhaSend
  url: https://ahasend.com