openapi: 3.1.0
info:
  title: Brevo Contacts Agent Status Email Activity API
  description: The Brevo Contacts API provides programmatic access to contact management features including creating, updating, and deleting contacts. Developers can organize contacts into lists, apply attributes and tags, import contacts in bulk, and build audience segments for targeted campaigns. The API also supports managing folders, contact attributes, and custom fields to structure contact data according to business needs.
  version: '3.0'
  contact:
    name: Brevo Support
    url: https://help.brevo.com
  termsOfService: https://www.brevo.com/legal/termsofuse/
servers:
- url: https://api.brevo.com/v3
  description: Brevo Production API Server
security:
- apiKeyAuth: []
tags:
- name: Email Activity
  description: Track and retrieve transactional email activity including delivery status, opens, clicks, and bounces.
paths:
  /smtp/statistics/events:
    get:
      operationId: getTransactionalEmailEvents
      summary: Get transactional email activity events
      description: Retrieves all transactional email activity as unaggregated events. Returns individual event records for deliveries, opens, clicks, bounces, spam reports, and other email activity.
      tags:
      - Email Activity
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: startDate
        in: query
        description: Start date for the event query in YYYY-MM-DD format.
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: End date for the event query in YYYY-MM-DD format.
        schema:
          type: string
          format: date
      - name: event
        in: query
        description: Filter by event type such as delivered, opened, clicked, hardBounce, softBounce, blocked, spam, or unsubscribed.
        schema:
          type: string
          enum:
          - sent
          - delivered
          - opened
          - clicked
          - hardBounce
          - softBounce
          - blocked
          - spam
          - invalid
          - deferred
          - unsubscribed
      - name: email
        in: query
        description: Filter events by recipient email address.
        schema:
          type: string
          format: email
      - name: messageId
        in: query
        description: Filter events by the unique message identifier.
        schema:
          type: string
      - name: templateId
        in: query
        description: Filter events by the template ID used for sending.
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Transactional email events retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailEventReport'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /smtp/statistics/aggregatedReport:
    get:
      operationId: getAggregatedEmailReport
      summary: Get aggregated transactional email statistics
      description: Retrieves aggregated statistics for transactional email activity over a specified period. Returns totals for requests, delivered, opens, clicks, bounces, and other metrics.
      tags:
      - Email Activity
      parameters:
      - name: startDate
        in: query
        description: Start date for the report in YYYY-MM-DD format.
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: End date for the report in YYYY-MM-DD format.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Aggregated email statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatedEmailReport'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    offsetParam:
      name: offset
      in: query
      description: Number of results to skip for pagination.
      schema:
        type: integer
        format: int64
        default: 0
    limitParam:
      name: limit
      in: query
      description: Maximum number of results to return per request.
      schema:
        type: integer
        format: int64
        default: 50
  schemas:
    AggregatedEmailReport:
      type: object
      properties:
        range:
          type: string
          description: Date range for the aggregated statistics.
        requests:
          type: integer
          format: int64
          description: Total number of email send requests.
        delivered:
          type: integer
          format: int64
          description: Total number of successfully delivered emails.
        hardBounces:
          type: integer
          format: int64
          description: Total number of hard bounces.
        softBounces:
          type: integer
          format: int64
          description: Total number of soft bounces.
        clicks:
          type: integer
          format: int64
          description: Total number of link clicks.
        uniqueClicks:
          type: integer
          format: int64
          description: Total number of unique link clicks.
        opens:
          type: integer
          format: int64
          description: Total number of email opens.
        uniqueOpens:
          type: integer
          format: int64
          description: Total number of unique email opens.
        spamReports:
          type: integer
          format: int64
          description: Total number of spam reports.
        blocked:
          type: integer
          format: int64
          description: Total number of blocked emails.
        invalid:
          type: integer
          format: int64
          description: Total number of invalid email addresses.
        unsubscribed:
          type: integer
          format: int64
          description: Total number of unsubscribes.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code identifying the type of error.
        message:
          type: string
          description: Human-readable description of the error.
    EmailEventReport:
      type: object
      properties:
        events:
          type: array
          description: List of transactional email activity events.
          items:
            type: object
            properties:
              email:
                type: string
                format: email
                description: Recipient email address associated with the event.
              date:
                type: string
                format: date-time
                description: UTC date-time when the event occurred.
              messageId:
                type: string
                description: Unique identifier of the email message.
              event:
                type: string
                description: Type of email event that occurred.
                enum:
                - sent
                - delivered
                - opened
                - clicked
                - hardBounce
                - softBounce
                - blocked
                - spam
                - invalid
                - deferred
                - unsubscribed
              reason:
                type: string
                description: Reason for the event if applicable, such as bounce details.
              tag:
                type: string
                description: Tag assigned to the email for categorization.
              subject:
                type: string
                description: Subject line of the email message.
              templateId:
                type: integer
                format: int64
                description: Template ID used for the email if applicable.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: Brevo API key passed in the api-key request header for authentication.
externalDocs:
  description: Brevo Contacts Documentation
  url: https://developers.brevo.com/docs/how-it-works