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 or Text body of the emails using params field parameters. A params field 'key-value' pair is separated by comma. An email API request with 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 100
  • The maximum size of the total params field can be 10MB.

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 or html_body as {{username}}, {{quantity}}. 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"}

{
  "dynamic_content": true,
  "from": "[email protected]",
  "from_name": "No Reply Email from Kaleyra",
  "to": "[email protected]",
  "subject": "{{subjectStartsWith}}  Sample Test Email from Email API,Please Ignore!!!! On {{currentdate}}",

    "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"
  }
}

The following success response is displayed.

{
    "data": [
        {
            "message_id": "a064e2f1-a36d-4846-926c-81953ec909e5:1",
            "to": "[email protected]",
            "from": "[email protected]",
            "subject": "Staging EU  Sample Test Email from Email API,Please Ignore!!!! On 11/18/2021 16"
        }
    ],
    "error": {}
}

Example of the email body from the recipient's mail box 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"
    }
}