openapi: 3.1.0
info:
  title: Mailjet Email API
  description: >-
    The Mailjet Email API enables sending transactional and marketing emails
    programmatically via JSON requests. The API also exposes resources for
    managing contacts, contact lists, segments, campaigns, templates, sender
    addresses, statistics, and event tracking. All requests use HTTP Basic
    authentication with an API key and secret pair issued from the Mailjet
    account dashboard.
  version: '3.1'
  contact:
    name: Mailjet API Support
    url: https://documentation.mailjet.com/hc/en-us
  termsOfService: https://www.mailjet.com/legal/terms/
externalDocs:
  description: Mailjet API Reference
  url: https://dev.mailjet.com/email/reference/
servers:
  - url: https://api.mailjet.com/v3.1
    description: Send API v3.1
  - url: https://api.mailjet.com/v3
    description: REST API v3
security:
  - BasicAuth: []
tags:
  - name: Send
    description: Send transactional and marketing emails
  - name: Contacts
    description: Manage contacts and properties
  - name: Contact Lists
    description: Manage contact lists and recipients
  - name: Campaigns
    description: Manage campaigns and drafts
  - name: Templates
    description: Manage reusable email templates
  - name: Senders
    description: Manage verified sender addresses
  - name: Statistics
    description: Retrieve aggregated sending statistics
  - name: Event
    description: Retrieve real-time event data
paths:
  /send:
    post:
      operationId: sendEmail
      summary: Send transactional emails (v3.1)
      description: >-
        Send one or more transactional emails using the Send API v3.1. Each
        message in the Messages array specifies its own sender, recipients,
        subject, content, and optional template.
      tags:
        - Send
      servers:
        - url: https://api.mailjet.com/v3.1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendV31Request'
      responses:
        '200':
          description: Send acknowledged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendV31Response'
        '400':
          description: Validation error
        '401':
          description: Authentication failed
  /contact:
    get:
      operationId: listContacts
      summary: List contacts
      tags:
        - Contacts
      servers:
        - url: https://api.mailjet.com/v3
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Contact list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedContacts'
    post:
      operationId: createContact
      summary: Create a contact
      tags:
        - Contacts
      servers:
        - url: https://api.mailjet.com/v3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '201':
          description: Contact created
  /contact/{id}:
    get:
      operationId: getContact
      summary: Get a contact
      tags:
        - Contacts
      servers:
        - url: https://api.mailjet.com/v3
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Contact details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
    put:
      operationId: updateContact
      summary: Update a contact
      tags:
        - Contacts
      servers:
        - url: https://api.mailjet.com/v3
      parameters:
        - $ref: '#/components/parameters/PathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '200':
          description: Contact updated
  /contactslist:
    get:
      operationId: listContactsLists
      summary: List contact lists
      tags:
        - Contact Lists
      servers:
        - url: https://api.mailjet.com/v3
      responses:
        '200':
          description: Contact lists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedContactsLists'
    post:
      operationId: createContactsList
      summary: Create a contact list
      tags:
        - Contact Lists
      servers:
        - url: https://api.mailjet.com/v3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactsList'
      responses:
        '201':
          description: Contact list created
  /contactslist/{id}:
    get:
      operationId: getContactsList
      summary: Get a contact list
      tags:
        - Contact Lists
      servers:
        - url: https://api.mailjet.com/v3
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Contact list details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactsList'
    delete:
      operationId: deleteContactsList
      summary: Delete a contact list
      tags:
        - Contact Lists
      servers:
        - url: https://api.mailjet.com/v3
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '204':
          description: Contact list deleted
  /contactslist/{id}/managemanycontacts:
    post:
      operationId: manageManyContacts
      summary: Bulk add or remove contacts in a list
      tags:
        - Contact Lists
      servers:
        - url: https://api.mailjet.com/v3
      parameters:
        - $ref: '#/components/parameters/PathId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Action:
                  type: string
                  enum: [addnoforce, addforce, remove, unsub]
                Contacts:
                  type: array
                  items:
                    $ref: '#/components/schemas/Contact'
      responses:
        '201':
          description: Job submitted
  /campaign:
    get:
      operationId: listCampaigns
      summary: List campaigns
      tags:
        - Campaigns
      servers:
        - url: https://api.mailjet.com/v3
      responses:
        '200':
          description: Campaigns
  /campaigndraft:
    get:
      operationId: listCampaignDrafts
      summary: List campaign drafts
      tags:
        - Campaigns
      servers:
        - url: https://api.mailjet.com/v3
      responses:
        '200':
          description: Campaign drafts
    post:
      operationId: createCampaignDraft
      summary: Create a campaign draft
      tags:
        - Campaigns
      servers:
        - url: https://api.mailjet.com/v3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Draft created
  /campaigndraft/{id}/send:
    post:
      operationId: sendCampaignDraft
      summary: Send a campaign draft
      tags:
        - Campaigns
      servers:
        - url: https://api.mailjet.com/v3
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '201':
          description: Campaign sent
  /template:
    get:
      operationId: listTemplates
      summary: List templates
      tags:
        - Templates
      servers:
        - url: https://api.mailjet.com/v3
      responses:
        '200':
          description: Templates
    post:
      operationId: createTemplate
      summary: Create a template
      tags:
        - Templates
      servers:
        - url: https://api.mailjet.com/v3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Template created
  /sender:
    get:
      operationId: listSenders
      summary: List sender addresses
      tags:
        - Senders
      servers:
        - url: https://api.mailjet.com/v3
      responses:
        '200':
          description: Senders
    post:
      operationId: createSender
      summary: Create a sender address
      tags:
        - Senders
      servers:
        - url: https://api.mailjet.com/v3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Email:
                  type: string
                  format: email
                Name:
                  type: string
      responses:
        '201':
          description: Sender created
  /statcounters:
    get:
      operationId: getStatCounters
      summary: Get sending statistic counters
      tags:
        - Statistics
      servers:
        - url: https://api.mailjet.com/v3
      parameters:
        - name: SourceID
          in: query
          schema:
            type: integer
        - name: CounterSource
          in: query
          schema:
            type: string
        - name: CounterTiming
          in: query
          schema:
            type: string
        - name: CounterResolution
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Statistic counters
  /messagehistory/{id}:
    get:
      operationId: getMessageHistory
      summary: Get the event history of a message
      tags:
        - Event
      servers:
        - url: https://api.mailjet.com/v3
      parameters:
        - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Event history
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: API key and secret used as HTTP Basic credentials
  parameters:
    Limit:
      name: Limit
      in: query
      schema:
        type: integer
        default: 10
    Offset:
      name: Offset
      in: query
      schema:
        type: integer
        default: 0
    PathId:
      name: id
      in: path
      required: true
      schema:
        type: string
  schemas:
    EmailAddress:
      type: object
      required: [Email]
      properties:
        Email:
          type: string
          format: email
        Name:
          type: string
    SendV31Message:
      type: object
      required: [From, To]
      properties:
        From:
          $ref: '#/components/schemas/EmailAddress'
        To:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        Cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        Bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        Subject:
          type: string
        TextPart:
          type: string
        HTMLPart:
          type: string
        TemplateID:
          type: integer
        TemplateLanguage:
          type: boolean
        Variables:
          type: object
          additionalProperties: true
        CustomID:
          type: string
        EventPayload:
          type: string
        Headers:
          type: object
          additionalProperties:
            type: string
        Attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        InlinedAttachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    Attachment:
      type: object
      required: [ContentType, Filename, Base64Content]
      properties:
        ContentType:
          type: string
        Filename:
          type: string
        Base64Content:
          type: string
        ContentID:
          type: string
    SendV31Request:
      type: object
      required: [Messages]
      properties:
        Messages:
          type: array
          items:
            $ref: '#/components/schemas/SendV31Message'
        SandboxMode:
          type: boolean
    SendV31Response:
      type: object
      properties:
        Messages:
          type: array
          items:
            type: object
            properties:
              Status:
                type: string
              To:
                type: array
                items:
                  type: object
                  properties:
                    Email:
                      type: string
                    MessageUUID:
                      type: string
                    MessageID:
                      type: integer
                    MessageHref:
                      type: string
    Contact:
      type: object
      properties:
        ID:
          type: integer
        Email:
          type: string
          format: email
        Name:
          type: string
        IsExcludedFromCampaigns:
          type: boolean
        CreatedAt:
          type: string
          format: date-time
    PaginatedContacts:
      type: object
      properties:
        Count:
          type: integer
        Total:
          type: integer
        Data:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
    ContactsList:
      type: object
      properties:
        ID:
          type: integer
        Name:
          type: string
        SubscriberCount:
          type: integer
        IsDeleted:
          type: boolean
        CreatedAt:
          type: string
          format: date-time
    PaginatedContactsLists:
      type: object
      properties:
        Count:
          type: integer
        Total:
          type: integer
        Data:
          type: array
          items:
            $ref: '#/components/schemas/ContactsList'