Create a Callback (API)

Create a callback for a mailbox, including filters, retries, timeout, and success code settings.

To create a new callback record, use the following request:

Method	Request URL*
POST	/api/v1/envelope/callback/add

Create callback

URL
Method	POST
request URL	/api/v1/envelope/callback/add
Headers
content-type	application/json
authorization	Bearer {token}, where {token} is the authorization token that the user received after successful authorization on the platform
mailbox	UUID of the mailbox to which you configured callbacks

REQUEST BODY

{
  "filter": {
      "label": ["string"],
      "status": ["COMPLETED"],
      "subject": "string",
      "receiveDateFrom": "2023-02-16T12:34:26.606Z",
      "receiveDateTo": "2023-02-16T12:34:26.606Z",
      "expireDateFrom": "2023-02-16T12:34:26.606Z",
      "expireDateTo": "2023-02-16T12:34:26.606Z",
      "template": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "sender": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "scope": ["inbox"]
  },
  "url": "string",
  "retries": 10,
  "timeout": 60000,
  "successCode": 200,
  "login": "string",
  "password": "string"
}

Request body parameters are described below:

filter *	It is an object with a filter that determines which callbacks will be triggered. It can be empty if you do not want to use any filters.
label	Filter envelopes by a label assigned to the envelope
status	Filter envelopes by status. Allowed statuses for callbacks are WAITING, COMPLETED, CANCELLED, EXPIRED (case insensitive)
subject	Filter envelopes by the respective subject of the envelope. The filter works according to the content rule. This means that if you apply a filter by subject agreement, all envelopes with the word agreement will be added to the callback queue, and a callback will be sent.
receiveDateFrom	Filter envelopes by receive date FROM the specified date and time
receiveDateTo	Filter envelopes by receive date TO the specified date and time
expireDateFrom	Filter envelopes by envelope expiration date FROM the specified date and time
expireDateTo	Filter envelopes by envelope expiration date TO the specified date and time
template	Filter envelopes by a specific template (the template from which the envelope was created). Allowed values are template UUIDs
sender	Filter envelopes by envelope sender. Allowed values are the sender's UUID
scope	Filter envelopes by direction of the email. Allowed values are inbox and outbox (case insensitive)
url *	The parameter defines the URL where the callback will be sent
retries *	The parameter defines the number of callback retry attempts. Retries may be applied if the URL is unreachable or if the success code received from the URL is different from the expected one. Allowed values are from 0 to 10. If 0 is set in the callback, the system tries to send the callback once and does not retry.
timeout *	The parameter defines a timeout in milliseconds for which the system waits for a response with a success code. If the timeout is reached, the retry procedure starts, if configured. Allowed values are from 100 to 60000.
successCode	The parameter defines the status code that the system expects for a successfully sent callback. If the status code received from the URL is different from the required one, the retry procedure is initiated, if configured. If no value is set, the default value (Status code: 200) is applied.
login	The parameter defines the login for Basic auth (if the URL is reachable only with Basic auth, this parameter has to be defined)
password	The parameter defines the password for Basic auth (if the URL is reachable only with Basic auth, this parameter has to be defined)

* - defines attribute as required

RESPONSE

In response, you get a 201 status code in case of successful callback creation and JSON data of the callback.

Response example (JSON):

{
  "id": "f8c97405-9185-4998-a3c0-2c4d0edaf43b",
  "filter": {
      "label": ["string"],
      "status": ["COMPLETED"],
      "subject": "string",
      "receiveDateFrom": null,
      "receiveDateTo": null,
      "expireDateFrom": null,
      "expireDateTo": null,
      "template": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "sender": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "scope": ["inbox"]
  },
  "url": "string",
  "retries": 10,
  "timeout": 60000,
  "successCode": 200,
  "authType": "BASIC"
}