Add dynamic values in email API using metadata

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

This section includes the API requests that use metadata parameters 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 metadata parameters. A metadata is 'key-value' pair separated by comma. An email API request with metadata can have a maximum of 20 metadata key-value pairs.

In a metadata 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 metadata can be 10MB.

To use metadata values in the email body:

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

Example of metadata with two key-value pairs:
"metadata" : {"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": [],

  "metadata": {
    "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 Metadata

The following example email request has metadata 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"
    }
  ],
  "metadata": {
    "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": "metadata",
        "message": "Characters in metadata parameter exceeded"
    }
}

API Request with exceeding characters in Metadata key

The following API request has its metadata 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"
    }
  ],
  "metadata": {
    "qunatity": "charactersInThisKeyOfMetadataExceededLimitcharactersInThisKeyOfMetadataExceededLimitcharactersInThisKeyOfMetadataExceededLimitcharactersInThisKeyOfMetadataExceededLimit",
    "dMarketValue": "819167.0000"
  }
}

The following error message is displayed.

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

Did this page help you?