listAccounts #

Lists registered accounts with the recipient types, audiences and capabilities of their provider. By default every account is returned, whatever its provider; the optional providerId argument restricts the list to one provider, audience to the providers able to reach that kind of recipient (human or technical), and capability to the providers able to carry that kind of message (text, html, json, file).

Each entry carries the identifier of the provider it belongs to, so the result can be used directly as the providerId and accountId arguments of sendMessage and removeAccount.

Query Syntax #

HTTP #

URL: http://kuzzle:7512/_/hermes/accounts[?providerId=<provider id>][&audience=<audience>[,<audience>]][&capability=<capability>[,<capability>]]
Method: GET

Other protocols #

{
  "controller": "hermes",
  "action": "listAccounts",
  "providerId": "smtp",   // optional
  "audience": "human",    // optional, a string or an array of strings
  "capability": "file"    // optional, a string or an array of strings
}

Kourou #

# every account
kourou hermes:listAccounts

# only SMTP accounts
kourou hermes:listAccounts -a providerId=smtp

# only accounts able to notify a person
kourou hermes:listAccounts -a audience=human

# only accounts able to carry a file
kourou hermes:listAccounts -a capability=file

Arguments #

• providerId (optional): identifier of a registered provider (smtp, twilio, sendgrid, smsenvoi or a custom provider id). When given, only the accounts of that provider are returned. An unknown provider is an error.
• audience (optional): a string or an array of strings (comma separated in HTTP query strings). Only the accounts of providers accepting at least one recipient type whose audiences include one of these values are returned (see hermes:listRecipientTypes). An unknown audience returns an empty list. Combines with providerId.
• capability (optional): a string or an array of strings (comma separated in HTTP query strings). Only the accounts of providers having every requested capability are returned (see hermes:listProviders). Combines with the other arguments.

Response #

Returns the registered accounts. Each account has:

• accountId: the account identifier, unique within its provider; the value of the accountId argument
• displayName: label for user interfaces, as given to addAccount (defaults to accountId)
• providerId: the identifier of the provider owning the account (smtp, twilio, sendgrid, smsenvoi or a custom provider id); the value of the providerId argument
• acceptedRecipientTypes: names of the recipient types accepted by the provider, i.e. the formats allowed in the recipients of sendMessage through this account; their definitions come from hermes:listRecipientTypes
• capabilities: the capabilities of the provider (text, html, json, file, or custom values), see hermes:listProviders
• audiences: the audiences the account can address, i.e. those of its provider (union of the audiences of its accepted recipient types). Handy to filter accounts client-side without a second request.

The parameters an account was created with (body.params of addAccount) are never returned: they hold credentials.

{
  "requestId": "d16d5e8c-464a-4589-938f-fd84f46080b9",
  "status": 200,
  "error": null,
  "controller": "hermes",
  "action": "listAccounts",
  "result": {
    "accounts": [
      {
        "accountId": "common",
        "displayName": "common",
        "providerId": "smtp",
        "acceptedRecipientTypes": ["email"],
        "capabilities": ["text", "html", "file"],
        "audiences": ["human"]
      },
      {
        "accountId": "ilayda",
        "displayName": "ilayda",
        "providerId": "smtp",
        "acceptedRecipientTypes": ["email"],
        "capabilities": ["text", "html", "file"],
        "audiences": ["human"]
      },
      {
        "accountId": "common",
        "displayName": "common",
        "providerId": "twilio",
        "acceptedRecipientTypes": ["phoneNumber"],
        "capabilities": ["text"],
        "audiences": ["human"]
      }
    ]
  }
}