Inbox API

Inbox API allows delivery of simple text messages to mobile apps.

The PowerAuth application is always derived from credentials which are used when accessing the REST API, so the API can be used with multiple PowerAuth applications by switching REST API credentials.

Possible Error Codes

The API may return one of the following error codes:

HTTP	Error Code	Description
`400`	`ERROR_INBOX`	Error related to working inbox.
`400`	`ERROR_INBOX_NOT_FOUND`	Inbox was not found for given user / app.
`400`	`ERROR_REQUEST`	Request did not pass validation (mandatory property missing, null/invalid value).
`401`	`ERROR_UNAUTHORIZED`	Returned in the case authentication fails (invalid application credentials).
`404`	`ERROR_NOT_FOUND`	Returned in the case URL is not present (calling wrong API).
`500`	`ERROR_GENERIC`	Unknown error occurred while processing request.
`500`	`ERROR_INTERNAL_API`	Communication with internal service failed.

Services

To send messages to inbox, you can use a simple API call addressed by the user ID.

post /v2/inbox/messages Send New Message

Send a new message to inbox to given user and notify the user via a push notification, unless supressed.

Request

{
  "userId": "$USER_ID",
  "type": "$TYPE",
  "subject": "$SUBJECT",
  "summary": "$SUMMARY",
  "body": "$BODY",
  "silent": false
}

Request Params

Attribute	Type	Description
`userId`*	`String`	User ID.
`type`*	`String`	Type of the message, either `text` or `html`.
`subject`*	`String`	Subject of the message.
`summary`*	`String`	Summary of the message.
`body`*	`String`	Body of the message, in simple HTML format.
`silent`	`boolean`	If set to `true`, the message is delivered in the inbox silently, without a push notification informing the user about the message. Default: `false` (inform the user).

Response

If the message is successfully sent, API returns additional information about the new message.

{
  "id": "8819ac31-ad29-40d1-ac60-1b54293abe61",
  "userId": "$USER_ID",
  "type": "$TYPE",
  "subject": "$SUBJECT",
  "summary": "$SUMMARY",
  "body": "$BODY",
  "timestamp": "$TIMESTAMP",
  "read": false
}

Attribute	Type	Description
`id`*	`String`	Inbox message ID.
`userId`*	`String`	User ID.
`type`*	`String`	Type of the message, either `text` or `html`.
`subject`*	`String`	Subject of the message.
`summary`*	`String`	Summary of the message.
`body`*	`String`	Body of the message, in simple HTML format.
`timestamp`*	`String`	Timestamp when message was created, in Unix format.
`read`*	`String`	Indication of if the message was ready by the user.

Sending a message to inbox failed due to business logic error.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INBOX",
    "message": "Missing subject field"
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

get /v2/inbox/messages/${id} Get Message Details

Get a message from inbox by given ID.

Request

Path Params

Param	Type	Description
`id`*	`String`	Inbox message ID.

Response

Returns information about the message with provided ID.

{
  "id": "${ID}",
  "userId": "$USER_ID",
  "type": "$TYPE",
  "subject": "$SUBJECT",
  "summary": "$SUMMARY",
  "body": "$BODY",
  "timestamp": "$TIMESTAMP",
  "read": false
}

Attribute	Type	Description
`id`*	`String`	Inbox message ID.
`userId`*	`String`	User ID.
`type`*	`String`	Type of the message, either `text` or `html`.
`subject`*	`String`	Subject of the message.
`summary`*	`String`	Summary of the message.
`body`*	`String`	Body of the message, in simple HTML format.
`timestamp`*	`String`	Timestamp when message was created, in Unix format.
`read`*	`String`	Indication of if the message was ready by the user.

Sending a message to inbox can fail due to business logic error.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INBOX",
    "message": "Missing subject field"
  }
}

In case message with given ID was not found, or the system user who requested it is not authorized to access apps where the message is sent.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INBOX_NOT_FOUND",
    "message": "Inbox message was not found."
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

Last updated on Jan 13, 2023 (00:34) View product