Create Email Callback Profiles with Dynamic Variables

You can create an Email callback profile within the Kaleyra.io user interface to get information about the Email delivery status. The wizard to set up the callback profile for the Email channel provides a list of dynamic variables specific to the Email channel that you can individually select to get the latest information about your email message that you are interested in.
After successfully creating an Email callback profile, you must use the ‘callback profile ID’ parameter in an Email API request (POST) to fetch all the Email delivery information in an endpoint that you specify.

📘

Note:

  • If you have more than one Callback Profile created for different channels, make sure you add the correct callback profile Id in the Email API requests.
  • A callback profile created for the Email channel cannot be used for other channel API requests.
  • Once a callback profile is created for the Email channel, you can only edit the list of dynamic variables you want to receive in the callback from Kaleyra or delete the profile.

To create an Email callback profile:

  1. On the account profile drop-down list, select the Callback Profiles option.
    The Callback Profiles page appears.
  1. On the Callback Profiles page, click Add New.

The Add Callback Profile window appears.

Perform the following steps to add all the relevant information in the ‘Add callback profile’ page.

  1. In the Title field, enter a title for the callback profile. This is a mandatory field.

  2. From the Select Channel API list, select the option ‘email - Email Gateway APIs' to create a callback profile that you can use to receive the updated information about the Email delivery status.
    Once you select the option ‘email - Email Gateway APIs’, the Events for the selected channel field is automatically set to the ‘Email Send’ option.

  3. In the HTTP Method field, select a method you want Kaleyra to use when calling your system to send you back the information about email messages.

    📘 Note: Only the POST method supports the use of dynamic variables for the Email channel.

  4. In the Enter Endpoint field, enter the URL at which the callback information should be received.

  5. In the Dynamic Variables field, click View to view and select the dynamic variables for the Email channel. The dynamic variables represent all the possible information that you can retrieve about the Email as part of the callback that kaleyra.io will send to your system. You may select all of them, or only the fields you are interested in.
    The List Dynamic Variables for the Email channel appears.

  1. In the List Dynamic Variables window, to select all the dynamic variables,
  • Click Select All or manually select the dynamic variables check-boxes that you want to receive in the callback sent from Kaleyra to your system.
  • After selecting the variables, click Copy to Clipboard.
  • Click ‘X’ (CLOSE) on the window to close the window.
  1. Using the mouse, right click and paste the selected dynamic variables either in the Request Body field (POST method).
  2. In the Enable form data or urlencoded headers field, select the 'form data' or the 'urlencoded header'.
  • Form data headers are used for complex data while submitting forms with file uploads.
  • URL Encoded headers are used for simpler text in HTTP requests with the data encoded in key-value pairs.
  1. In the Header fields, enter the key-value pair values to add additional information to be added to the HTTPS request generated from Kaleyra to your system, for example, authentication details.
  1. Use the +Add more button to add multiple Header fields.
  2. Use the Enable Encryption toggle button to enable encryption of the callback information.
    When you enable this toggle button, the Algorithm, Key, and the Initialization Vector, and Parameters fields appear.
    Enter values in these fields. To know more about these fields, see: https://developers.kaleyra.io/docs/callback-profiles-in-accountssettings
    The Enable Callback Required Options toggle button is NOT applicable for the Email channel.
  3. To check if the callback profile that you have created is ok, click Test.
    A dummy version of a callback will be triggered from Kaleyra to your system applying the configuration done so far.
  4. After filling in all the details, click Save to save the callback profile for the Email channel with the specified dynamic variables and configuration.
    Once you save the callback profile on the UI, you can see the callback profile ID as shown on the Callback Profiles list.
  1. Copy the callback profile ID from the list and add it to the ‘callback_profile_id’ parameter in the ‘send Email API request’ as shown in the following example, along with the other necessary Email API parameters.
    "callback_profile_id": "IN_453d2677-2c91-4610-9c01-eefbeec5f697".
    See Single Email page: Send Single Email for more details on using the callback_profile_id parameter in an API request.

The following table shows the field descriptions on the Add Callback profile window.

ColumnDescriptionExample
TitleThe name of the Email callback profile.
You can use the callback title for searching the callback profiles.
email_callback_profile
Selected Channel APIThe channel for which the callback profile is created.email - Email Gateway APIs
Events for the selected channelThe events of the selected channel for which the callback information is obtained.
The relevant information for the selected event will be received using the callback.
Email Send
HTTP MethodThis section provides the options to select the HTTP methods for the Email channel APIs -
Select MethodOnly the POST method is supported.
Note: .The dynamic variables get added in the body of the JSON request for the POST method.
POST
Enter endpointThis is the URL to which the callback data is returned.<https://webhook.site/xxxxdcb3-a524-47e9-8eac-ef4cee045635>
Dynamic variablesAll the relevant dynamic variables for the Email channel are listed here.
You can select the dynamic variables for which you want to receive the values through the callback.
Note: See the table below for dynamic variables descriptions
"delivery_status": "<delivery_status>" "from_mail": "<from_mail>"
Enable form data or urlencoded Headers

Form data
URLencoded
Headers (Optional)
The header information should be given as a key-value pair.
Form data headers are used for complex data while submitting forms with file uploads.
URL Encoded headers are used for simpler text in HTTP requests with the data encoded in key-value pairs.
Note:
Use these fields to add any additional HTTP headers and related values you want to receive in the callback.
Use Headers for authentication purposes or to indicate how the callback response should be presented using the content_type.
api-key:xxxx51f2c0ac28bb395016083d40axxxx
Enable EncryptionThis toggle button is to enable encryption for the callback information. When this option is enabled, the callback data is encrypted. Use this feature to secure the callback data.For information on encryption algorithm and the related fields for this feature, see:
Callback Profiles page.
Enable Callback Required OptionThis option is not applicable to the Email channel.NA

The following table shows the dynamic variables for Email channel and their descriptions with examples.

ColumnDescriptionExample
message_idThe unique identification number of the email.64702e3a-7596-47a1-bc50-fa4bbf9b0f9d:1
delivery_status.The delivery status of the email sent.
(see below for the full list of possible statuses).
Bounce
from_mailThe from address of the email.[email protected]
recipient_mailThe recipient's address for the email.[email protected]
delivery_timeThe time at which the email is delivered.2023-09-29T11:23:35.586Z
error_codeThe error code in case of an error in the email delivery.550

Note: This error code is different from the error codes that Kaleyra assigns to the API request errors that are shown in the API Response.
error_statusThe error status in case of an error.5.1.1.
error_messageThe error message of the error that occurred during the email delivery.550 5.1.1 The email account that you tried to reach does not exist.

The following table shows the Email delivery statuses and their descriptions.

StatusDescription
BlockedAn email request is marked as 'blocked' by Kaleyra for the reasons such as, the usage of unapproved templates, too many mails to a specific mail id in a short span of time.
BounceAn email delivery status is ‘bounce’ when the recipient address is incorrect.
DeferredWhen an email bounces not because of an incorrect recipient address but for other reasons, such as the recipient’s inbox is full, the email status is ‘deferred’.
DeliveredWhen an email is delivered to the recipient.
AcceptedWhen an email is accepted by Kaleyra and it is in processing.
FailedAn email is marked as ‘failed’ due to insufficient balance or an internal error.
OpenWhen an email is opened by the recipient.
SuppressedIf the recipient address is in the suppression list, then for that recipient email delivery status is ‘suppressed’.