Eve Swagger JS

Class: Mail

Mail

An api adapter over the end points handling the mail inbox for a character via functions in the mail ESI endpoints. You should not usually instantiate this directly as its constructor requires an internal api instance.

This is a function class so instances of Mail are functions and can be invoked directly, besides accessing its members. Its default function action is equivalent to get or inbox if no id is given.

new Mail(agent, characterId, token)

Create a new Mail function for the character, including its SSO token.

Parameters:
Name Type Description
agent ESIAgent

The ESI agent
characterId Number

The id of the character whose mail is accessed
token String

The SSO access token for the character

Members

labels :Labels

A Labels instance for this character, allowing access to the labels they have created.

Type:

Methods

all()

Fetch all mails for the character as a single array. This makes multiple calls to inbox. Use with caution as certain characters could have substantial amounts of mail.

Returns:
Type
Promise.<Array.<Object>>

cspaCost(toIds)

Takes a source character ID in the url and a set of target character ID's in the body, returns a CSPA charge cost.

This makes an HTTP POST request to /characters/{character_id}/cspa/. The route version is v3.

The route parameter, characters, is built implicitly by the function. The function argument toIds maps to the characters property of the characters route parameter. The array length of toIds must be between 1 and 100.

On success, this resolves to aggregate cost of sending a mail from the source character to the target characters, in ISK hundredths. Note that the type schema of the response is modified from what is defined in ESI. Specifically, it returns only the cost property.

This function must be used with an SSO token that has the following scopes:

  • esi-characters.read_contacts.v1
Parameters:
Name Type Description
toIds Array.<Number>

Characters array.

Returns:

A Promise that resolves to cost integer.

Type
Promise.<Number>

get(id)

Get a Message instance for the given message or mail id.

Parameters:
Name Type Description
id

The message id
Returns:
Type
Message

inbox(labelIds, lastMailId)

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. This route is cached for up to 30 seconds.

This makes an HTTP GET request to /characters/{character_id}/mail/. The route version is v1.

The array length of labelIds must be between 1 and 25.

On success, this resolves to the requested mail. An example result is:

[
  {
    "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-30T16:07:00Z"
  }
]

This function must be used with an SSO token that has the following scopes:

  • esi-mail.read_mail.v1
Parameters:
Name Type Default Description
labelIds Array.<Number>

Fetch only mails that match one or more of the given labels. If empty, no filtering is performed.
lastMailId Number 0

List only mail with an ID lower than the given ID, if present. If 0, the most recent mails are returned.
Returns:

A Promise that resolves to the parsed JSON of the response.

Type
Promise.<Array.<Object>>

lists()

Return all mailing lists that the character is subscribed to. This route is cached for up to 120 seconds.

This makes an HTTP GET request to /characters/{character_id}/mail/lists/. The route version is v1.

On success, this resolves to mailing lists. An example result is:

[
  {
    "mailing_list_id": 1,
    "name": "test_mailing_list"
  }
]

This function must be used with an SSO token that has the following scopes:

  • esi-mail.read_mail.v1
Returns:

A Promise that resolves to the parsed JSON of the response.

Type
Promise.<Array.<Object>>

send(mail)

Create and send a new mail.

This makes an HTTP POST request to /characters/{character_id}/mail/. The route version is v1.

An example value for mail is shown below:

{
  "approved_cost": 0,
  "body": "body string",
  "recipients": [
    {
      "recipient_id": 0,
      "recipient_type": ""
    }
  ],
  "subject": "subject string"
}

On success, this resolves to the id of the created entity.

This function must be used with an SSO token that has the following scopes:

  • esi-mail.send_mail.v1
Parameters:
Name Type Description
mail Object

The mail to send. The mail descriptor
Returns:

A Promise that resolves to an id.

Type
Promise.<Number>

unreadCount()

This makes a request to the labels route and then filters the result to just return the total unread count.

Return a list of the users mail labels, unread counts for each label and a total unread count. This route is cached for up to 30 seconds.

This makes an HTTP GET request to /characters/{character_id}/mail/labels/. The route version is v3.

On success, this resolves to a list of mail labels and unread counts. Note that the type schema of the response is modified from what is defined in ESI. Specifically, it returns only the total_unread_count property.

This function must be used with an SSO token that has the following scopes:

  • esi-mail.read_mail.v1
Returns:

A Promise that resolves to total_unread_count integer.

Type
Promise.<Number>