EVE Online

EVE Online Mail API

The Mail API from EVE Online — 13 operation(s) for mail.

GitHub OpenAPI

Documentation

📖
Documentation
https://developers.eveonline.com/docs/services/esi/
📖
BestPractices
https://developers.eveonline.com/docs/services/esi/best-practices/
📖
RateLimits
https://developers.eveonline.com/docs/services/esi/rate-limiting/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/eve-online/refs/heads/main/openapi/eve-online-mail-api-openapi.yml

Other Resources

🔗
APIExplorer
https://developers.eveonline.com/api-explorer
🔗
Swagger
https://esi.evetech.net/ui
🔗
GitHubRepo
https://github.com/esi/esi-docs
🔗
GitHubRepo
https://github.com/esi/esi-issues
🔗
GitHubRepo
https://github.com/esi/esi-routes
🔗
GitHubRepo
https://github.com/esi/eve-glue
🔗
SupportIssues
https://github.com/esi/esi-issues

OpenAPI Specification

eve-online-mail-api-openapi.yml Raw ↑ 
openapi: 3.0.0
info:
  description: An OpenAPI for EVE Online
  title: EVE Swagger Interface Alliance Mail API
  version: '1.36'
servers:
- url: https://esi.evetech.net/latest
tags:
- name: Mail
paths:
  /characters/{character_id}/mail/:
    get:
      description: 'Return the 50 most recent mail headers belonging to the character that match the query criteria. Queries can be filtered by label, and last_mail_id can be used to paginate backwards


        ---

        Alternate route: `/dev/characters/{character_id}/mail/`


        Alternate route: `/legacy/characters/{character_id}/mail/`


        Alternate route: `/v1/characters/{character_id}/mail/`


        ---

        This route is cached for up to 30 seconds'
      operationId: get_characters_character_id_mail
      parameters:
      - $ref: '#/components/parameters/character_id'
      - $ref: '#/components/parameters/datasource'
      - $ref: '#/components/parameters/If-None-Match'
      - description: Fetch only mails that match one or more of the given labels
        in: query
        name: labels
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            format: int32
            minimum: 0
            type: integer
          minItems: 1
          maxItems: 25
          uniqueItems: true
        example:
        - 1
      - description: List only mail with an ID lower than the given ID, if present
        in: query
        name: last_mail_id
        schema:
          type: integer
          format: int32
        example: 1001
      - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: The requested mail
          headers:
            Cache-Control:
              description: The caching mechanism used
              schema:
                type: string
            ETag:
              description: RFC7232 compliant entity tag
              schema:
                type: string
            Expires:
              description: RFC7231 formatted datetime string
              schema:
                type: string
            Last-Modified:
              description: RFC7231 formatted datetime string
              schema:
                type: string
          content:
            application/json:
              schema:
                description: 200 ok array
                items:
                  description: 200 ok object
                  properties:
                    from:
                      description: From whom the mail was sent
                      format: int32
                      title: get_characters_character_id_mail_from
                      type: integer
                    is_read:
                      description: is_read boolean
                      title: get_characters_character_id_mail_is_read
                      type: boolean
                    labels:
                      description: labels array
                      items:
                        description: label integer
                        format: int32
                        title: get_characters_character_id_mail_label
                        type: integer
                      maxItems: 25
                      minimum: 0
                      title: get_characters_character_id_mail_labels
                      type: array
                      uniqueItems: true
                    mail_id:
                      description: mail_id integer
                      format: int32
                      title: get_characters_character_id_mail_mail_id
                      type: integer
                    recipients:
                      description: Recipients of the mail
                      items:
                        description: recipient object
                        properties:
                          recipient_id:
                            description: recipient_id integer
                            format: int32
                            title: get_characters_character_id_mail_recipient_id
                            type: integer
                          recipient_type:
                            description: recipient_type string
                            enum:
                            - alliance
                            - character
                            - corporation
                            - mailing_list
                            title: get_characters_character_id_mail_recipient_type
                            type: string
                        required:
                        - recipient_type
                        - recipient_id
                        title: get_characters_character_id_mail_recipient
                        type: object
                      maxItems: 52
                      minItems: 0
                      title: get_characters_character_id_mail_recipients
                      type: array
                      uniqueItems: true
                    subject:
                      description: Mail subject
                      title: get_characters_character_id_mail_subject
                      type: string
                    timestamp:
                      description: When the mail was sent
                      format: date-time
                      title: get_characters_character_id_mail_timestamp
                      type: string
                  title: get_characters_character_id_mail_200_ok
                  type: object
                maxItems: 50
                title: get_characters_character_id_mail_ok
                type: array
              examples:
                response:
                  value:
                  - from: 90000001
                    is_read: true
                    labels:
                    - 3
                    mail_id: 7
                    recipients:
                    - recipient_id: 90000002
                      recipient_type: character
                    subject: Title for EVE Mail
                    timestamp: 2015-09-30 16:07:00+00:00
        '304':
          description: Not modified
          headers:
            Cache-Control:
              description: The caching mechanism used
              schema:
                type: string
            ETag:
              description: RFC7232 compliant entity tag
              schema:
                type: string
            Expires:
              description: RFC7231 formatted datetime string
              schema:
                type: string
            Last-Modified:
              description: RFC7231 formatted datetime string
              schema:
                type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request'
              examples:
                response:
                  value:
                    error: Bad request message
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
              examples:
                response:
                  value:
                    error: Unauthorized message
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/forbidden'
              examples:
                response:
                  value:
                    error: Forbidden message
        '420':
          description: Error limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_limited'
              examples:
                response:
                  value:
                    error: Error limited message
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error'
              examples:
                response:
                  value:
                    error: Internal server error message
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service_unavailable'
              examples:
                response:
                  value:
                    error: Service unavailable message
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway_timeout'
              examples:
                response:
                  value:
                    error: Gateway timeout message
      security:
      - evesso:
        - esi-mail.read_mail.v1
      summary: EVE Online Return Mail Headers
      tags:
      - Mail
      x-alternate-versions:
      - dev
      - legacy
      - v1
      x-cached-seconds: 30
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      description: 'Create and send a new mail


        ---

        Alternate route: `/dev/characters/{character_id}/mail/`


        Alternate route: `/legacy/characters/{character_id}/mail/`


        Alternate route: `/v1/characters/{character_id}/mail/`

        '
      operationId: post_characters_character_id_mail
      parameters:
      - $ref: '#/components/parameters/character_id'
      - $ref: '#/components/parameters/datasource'
      - $ref: '#/components/parameters/token'
      requestBody:
        content:
          application/json:
            schema:
              description: mail object
              properties:
                approved_cost:
                  default: 0
                  description: approved_cost integer
                  format: int64
                  title: post_characters_character_id_mail_approved_cost
                  type: integer
                body:
                  description: body string
                  maxLength: 10000
                  title: post_characters_character_id_mail_body
                  type: string
                recipients:
                  description: recipients array
                  items:
                    description: recipient object
                    properties:
                      recipient_id:
                        description: recipient_id integer
                        format: int32
                        title: post_characters_character_id_mail_recipient_id
                        type: integer
                      recipient_type:
                        description: recipient_type string
                        enum:
                        - alliance
                        - character
                        - corporation
                        - mailing_list
                        title: post_characters_character_id_mail_recipient_type
                        type: string
                    required:
                    - recipient_type
                    - recipient_id
                    title: post_characters_character_id_mail_recipient
                    type: object
                  maxItems: 50
                  minItems: 1
                  title: post_characters_character_id_mail_recipients
                  type: array
                subject:
                  description: subject string
                  maxLength: 1000
                  title: post_characters_character_id_mail_subject
                  type: string
              required:
              - recipients
              - subject
              - body
              title: post_characters_character_id_mail_mail
              type: object
            examples:
              PostCharactersCharacterIdMailRequestExample:
                summary: Default post_characters_character_id_mail request
                x-microcks-default: true
                value:
                  approved_cost: 1
                  body: example
                  recipients:
                  - recipient_id: 1001
                    recipient_type: alliance
                  subject: example
        description: The mail to send
        required: true
      responses:
        '201':
          description: Mail created
          content:
            application/json:
              schema:
                description: Mail ID
                format: int32
                title: post_characters_character_id_mail_created
                type: integer
              examples:
                response:
                  value: 13
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request'
              examples:
                response:
                  value:
                    error: Bad request message
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
              examples:
                response:
                  value:
                    error: Unauthorized message
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/forbidden'
              examples:
                response:
                  value:
                    error: Forbidden message
        '420':
          description: Error limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_limited'
              examples:
                response:
                  value:
                    error: Error limited message
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error'
              examples:
                response:
                  value:
                    error: Internal server error message
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service_unavailable'
              examples:
                response:
                  value:
                    error: Service unavailable message
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway_timeout'
              examples:
                response:
                  value:
                    error: Gateway timeout message
        '520':
          description: Internal error thrown from the EVE server. Most of the time this means you have hit an EVE server rate limit
          content:
            application/json:
              schema:
                description: Error 520
                properties:
                  error:
                    description: Error 520 message
                    title: post_characters_character_id_mail_520_error_520
                    type: string
                title: post_characters_character_id_mail_error_520
                type: object
              examples:
                response:
                  value:
                    error: Error 520 message
      security:
      - evesso:
        - esi-mail.send_mail.v1
      summary: EVE Online Send a New Mail
      tags:
      - Mail
      x-alternate-versions:
      - dev
      - legacy
      - v1
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /characters/{character_id}/mail/labels/:
    get:
      description: 'Return a list of the users mail labels, unread counts for each label and a total unread count.


        ---

        Alternate route: `/dev/characters/{character_id}/mail/labels/`


        Alternate route: `/v3/characters/{character_id}/mail/labels/`


        ---

        This route is cached for up to 30 seconds'
      operationId: get_characters_character_id_mail_labels
      parameters:
      - $ref: '#/components/parameters/character_id'
      - $ref: '#/components/parameters/datasource'
      - $ref: '#/components/parameters/If-None-Match'
      - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: A list of mail labels and unread counts
          headers:
            Cache-Control:
              description: The caching mechanism used
              schema:
                type: string
            ETag:
              description: RFC7232 compliant entity tag
              schema:
                type: string
            Expires:
              description: RFC7231 formatted datetime string
              schema:
                type: string
            Last-Modified:
              description: RFC7231 formatted datetime string
              schema:
                type: string
          content:
            application/json:
              schema:
                description: 200 ok object
                properties:
                  labels:
                    description: labels array
                    items:
                      description: label object
                      properties:
                        color:
                          default: '#ffffff'
                          description: color string
                          enum:
                          - '#0000fe'
                          - '#006634'
                          - '#0099ff'
                          - '#00ff33'
                          - '#01ffff'
                          - '#349800'
                          - '#660066'
                          - '#666666'
                          - '#999999'
                          - '#99ffff'
                          - '#9a0000'
                          - '#ccff9a'
                          - '#e6e6e6'
                          - '#fe0000'
                          - '#ff6600'
                          - '#ffff01'
                          - '#ffffcd'
                          - '#ffffff'
                          title: get_characters_character_id_mail_labels_color
                          type: string
                        label_id:
                          description: label_id integer
                          format: int32
                          minimum: 0
                          title: get_characters_character_id_mail_labels_label_id
                          type: integer
                        name:
                          description: name string
                          maxLength: 40
                          title: get_characters_character_id_mail_labels_name
                          type: string
                        unread_count:
                          description: unread_count integer
                          format: int32
                          minimum: 0
                          title: get_characters_character_id_mail_labels_unread_count
                          type: integer
                      title: get_characters_character_id_mail_labels_label
                      type: object
                    maxItems: 30
                    title: get_characters_character_id_mail_labels_labels
                    type: array
                  total_unread_count:
                    description: total_unread_count integer
                    format: int32
                    minimum: 0
                    title: get_characters_character_id_mail_labels_total_unread_count
                    type: integer
                title: get_characters_character_id_mail_labels_ok
                type: object
              examples:
                response:
                  value:
                    labels:
                    - color: '#660066'
                      label_id: 16
                      name: PINK
                      unread_count: 4
                    - color: '#ffffff'
                      label_id: 17
                      name: WHITE
                      unread_count: 1
                    total_unread_count: 5
        '304':
          description: Not modified
          headers:
            Cache-Control:
              description: The caching mechanism used
              schema:
                type: string
            ETag:
              description: RFC7232 compliant entity tag
              schema:
                type: string
            Expires:
              description: RFC7231 formatted datetime string
              schema:
                type: string
            Last-Modified:
              description: RFC7231 formatted datetime string
              schema:
                type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request'
              examples:
                response:
                  value:
                    error: Bad request message
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
              examples:
                response:
                  value:
                    error: Unauthorized message
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/forbidden'
              examples:
                response:
                  value:
                    error: Forbidden message
        '420':
          description: Error limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_limited'
              examples:
                response:
                  value:
                    error: Error limited message
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error'
              examples:
                response:
                  value:
                    error: Internal server error message
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service_unavailable'
              examples:
                response:
                  value:
                    error: Service unavailable message
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway_timeout'
              examples:
                response:
                  value:
                    error: Gateway timeout message
      security:
      - evesso:
        - esi-mail.read_mail.v1
      summary: EVE Online Get Mail Labels and Unread Counts
      tags:
      - Mail
      x-alternate-versions:
      - dev
      - v3
      x-cached-seconds: 30
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      description: 'Create a mail label


        ---

        Alternate route: `/dev/characters/{character_id}/mail/labels/`


        Alternate route: `/legacy/characters/{character_id}/mail/labels/`


        Alternate route: `/v2/characters/{character_id}/mail/labels/`

        '
      operationId: post_characters_character_id_mail_labels
      parameters:
      - $ref: '#/components/parameters/character_id'
      - $ref: '#/components/parameters/datasource'
      - $ref: '#/components/parameters/token'
      requestBody:
        content:
          application/json:
            schema:
              description: label object
              properties:
                color:
                  default: '#ffffff'
                  description: Hexadecimal string representing label color, in RGB format
                  enum:
                  - '#0000fe'
                  - '#006634'
                  - '#0099ff'
                  - '#00ff33'
                  - '#01ffff'
                  - '#349800'
                  - '#660066'
                  - '#666666'
                  - '#999999'
                  - '#99ffff'
                  - '#9a0000'
                  - '#ccff9a'
                  - '#e6e6e6'
                  - '#fe0000'
                  - '#ff6600'
                  - '#ffff01'
                  - '#ffffcd'
                  - '#ffffff'
                  title: post_characters_character_id_mail_labels_color
                  type: string
                name:
                  description: name string
                  maxLength: 40
                  minLength: 1
                  title: post_characters_character_id_mail_labels_name
                  type: string
              required:
              - name
              title: post_characters_character_id_mail_labels_label
              type: object
            examples:
              PostCharactersCharacterIdMailLabelsRequestExample:
                summary: Default post_characters_character_id_mail_labels request
                x-microcks-default: true
                value:
                  color: '#0000fe'
                  name: Example Name
        description: Label to create
        required: true
      responses:
        '201':
          description: Label created
          content:
            application/json:
              schema:
                description: Label ID
                format: int32
                title: post_characters_character_id_mail_labels_created
                type: integer
              examples:
                response:
                  value: 128
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request'
              examples:
                response:
                  value:
                    error: Bad request message
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
              examples:
                response:
                  value:
                    error: Unauthorized message
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/forbidden'
              examples:
                response:
                  value:
                    error: Forbidden message
        '420':
          description: Error limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_limited'
              examples:
                response:
                  value:
                    error: Error limited message
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error'
              examples:
                response:
                  value:
                    error: Internal server error message
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service_unavailable'
              examples:
                response:
                  value:
                    error: Service unavailable message
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway_timeout'
              examples:
                response:
                  value:
                    error: Gateway timeout message
      security:
      - evesso:
        - esi-mail.organize_mail.v1
      summary: EVE Online Create a Mail Label
      tags:
      - Mail
      x-alternate-versions:
      - dev
      - legacy
      - v2
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /characters/{character_id}/mail/labels/{label_id}/:
    delete:
      description: 'Delete a mail label


        ---

        Alternate route: `/dev/characters/{character_id}/mail/labels/{label_id}/`


        Alternate route: `/legacy/characters/{character_id}/mail/labels/{label_id}/`


        Alternate route: `/v1/characters/{character_id}/mail/labels/{label_id}/`

        '
      operationId: delete_characters_character_id_mail_labels_label_id
      parameters:
      - $ref: '#/components/parameters/character_id'
      - $ref: '#/components/parameters/datasource'
      - description: An EVE label id
        in: path
        name: label_id
        required: true
        schema:
          type: integer
          format: int32
        example: 1001
      - $ref: '#/components/parameters/token'
      responses:
        '204':
          description: Label deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request'
              examples:
                response:
                  value:
                    error: Bad request message
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
              examples:
                response:
                  value:
                    error: Unauthorized message
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/forbidden'
              examples:
                response:
                  value:
                    error: Forbidden message
        '420':
          description: Error limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_limited'
              examples:
                response:
                  value:
                    error: Error limited message
        '422':
          description: Default labels cannot be deleted
          content:
            application/json:
              schema:
                description: Unprocessable entity
                properties:
                  error:
                    description: Unprocessable entity message
                    title: delete_characters_character_id_mail_labels_label_id_422_unprocessable_entity
                    type: string
                title: delete_characters_character_id_mail_labels_label_id_unprocessable_entity
                type: object
              examples:
                response:
                  value:
                    error: Unprocessable entity message
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error'
              examples:
                response:
                  value:
                    error: Internal server error message
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service_unavailable'
              examples:
                response:
                  value:
                    error: Service unavailable message
        '504':
          description: Gateway timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway_timeout'
              examples:
                response:
                  value:
                    error: Gateway timeout message
      security:
      - evesso:
        - esi-mail.organize_mail.v1
      summary: EVE Online Delete a Mail Label
      tags:
      - Mail
      x-alternate-versions:
      - dev
      - legacy
      - v1
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /characters/{character_id}/mail/lists/:
    get:
      description: 'Return all mailing lists that the character is subscribed to


        ---

        Alternate route: `/dev/characters/{character_id}/mail/lists/`


        Alternate route: `/legacy/characters/{character_id}/mail/lists/`


        Alternate route: `/v1/chara

# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/eve-online/refs/heads/main/openapi/eve-online-mail-api-openapi.yml