Add Dynamic Values in Email API Using Params field

Add params field in email API to send real-time values in the email body.

This section includes the API requests that use params field to display dynamic values and the related errors.

Add dynamic values in email API request

You can add dynamic values into the HTML body, Text body, and the subject line of the emails using the params field parameters. A params field 'key-value' pair is separated by comma. An email API request with the params field can have a maximum of 20 key-value pairs.

In a 'params' field key-value pair:

  • Each key can have a character limit of 20.
  • Each value can have a character limit of 4000.

To use params field values in the email body:

  • Set the parameter "dynamic_content" to 'true'.
  • Use the params field parameters in double curly braces within the text_body, html_body, or the subject line as {{username}}, {{quantity}}, or {{subjectname}}. This substitutes the params field value in the email body.

Example of params field with two key-value pairs:
"params" : {"Model”:”abc”, “Client-Id”:”345","subjectBrandName":"samplebrandname"}

The following API request accepts dynamic values in the text_body and in the subject line using the 'params' field.

{
  "dynamic_content": true,
  "from": "[email protected]",
  "from_name": "No Reply Email from Kaleyra",
  "to": "[email protected]",
  "subject": "Thanks for shopping with {{subjectBrandName}}",
  "text_body": "Hi:{{username}}, Good day...Thank you for purchasing {{quantity}}Kg of goods from us.The market value of the goods is {{dMarketValue}}",
    "html_body": "",
  "reply_to": "[email protected]",
  "attachments": [],

  "params": {
    "username":"Tom",
    "quantity": "50",
    "dMarketValue": "819167.0000",
    "subjectBrandName": "samplebrandname"  }
}

The following success response is displayed.

{
    "data": [
        {
            "message_id": "a064e2f1-a36d-4846-926c-81953ec909e5:1",
            "to": "[email protected]",
            "from": "[email protected]",
            "subjectBrandName": "Thanks for shopping with samplebrandname"
        }
    ],
    "error": {}
}

Example of the email body from the recipient's mailbox is shown:

API Request with exceeding number of keys in Params field

The following example email request has params field keys more than 20.

{
  "from": "[email protected]",
  "from_name": "No Reply Email from Kaleyra",
  "to": "[email protected]",
  "Subject": "Sample Test Email from Email API,Please Ignore!!!!",
  "text_body": "",
  "html_body": "",
  "reply_to": "[email protected]",
  "attachments": [
    {
      "content": "hdhd7373",
      "content_type": "text/html",
      "filename": "filewithbase64.txt"
    },
    {
      "content": "hdhd7373",
      "content_type": "text/html",
      "filename": "file.txt"
    }
  ],
  "params": {
    "quantity": "5000",
    "dMarketValue": "819167.0000",
    "symbol": "PMBND",
    "yield": "6.000000",
    "daysInHolding": "23",
    "dProfile": "HI-GRD",
    "dAnnualInterestAmtt": "60.000000",
    "price": "160.000000",
    "issuer": "Phillip Morris",
    "sin": "Y",
    "dAccruedInterest": "4.000000",
    "faceValue": "1000.000000",
    "rating": "A",
    "#id": "Security_id_1",
    "#type": "Security",
    "warnMargin": "3.000000",
    "name": "Boeing",
    "restricted": "false",
    "maxPctHiGrade": "75.000000",
    "number": "1640",
    "twentyFirstKey":"23434"
  }
}

The following error message is displayed.

HTTP/1.1 400
{
    "error": {
        "code": "E14509",
        "type": "Limit Exceeded",
        "parameter": "params",
        "message": "Characters in params field exceeded"
    }
}

API Request with exceeding characters in params field

The following API request has its params field key value exceeding 100 characters.

{
  "from": "[email protected]",
  "from_name": "No Reply Email from Kaleyra",
  "to": "[email protected]",
  "Subject": "Sample Test Email from Email API,Please Ignore!!!!",
  "text_body": "",
  "html_body": "",
  "reply_to": "[email protected]",
  "attachments": [
    {
      "content": "hdhd7373",
      "content_type": "text/html",
      "filename": "filewithbase64.txt"
    },
    {
      "content": "hdhd7373",
      "content_type": "text/html",
      "filename": "file.txt"
    }
  ],
  "params": {
    "qunatity": "charactersInThisKeyOfparamsExceededLimitcharactersInThisKeyOfparamsExceededLimitcharactersInThisKeyOfparamsExceededLimitcharactersInThisKeyOfparamsExceededLimit",
    "dMarketValue": "819167.0000"
  }
}

The following error message is displayed.

{
    "error": {
        "code": "E14509",
        "type": "Limit Exceeded",
        "parameter": "params",
        "message": "Characters in charactersInThisKeyOfparamsExceededLimitcharactersInThisKeyOfparamsExceededLimitcharactersInThisKeyOfpMetadatExceededLimitcharactersInThisKeyOfMetadatExceededLimit parameter exceeded"
    }
}