Overview

The Generic HTTP feature enables flexible integration with any third-party Email Service Provider (ESP) using the HTTP protocol. It supports sending email campaigns using custom payloads, headers, and dynamic fields. It also enables callback tracking for delivery success and failures, as well as user interactions such as clicks or unsubscribes.

Set Up Email Provider in CleverTap

To configure any third-party ESP using the Generic HTTP provider in your CleverTap account, perform the following steps:

1. Go to Settings > Channels > Email.
2. Click + Provider and select Generic HTTP from the Provider dropdown.
3. Enter the following provider details:

4. Click Save and click Send Test Email to verify the setup.

Set Up Message Payload

You can configure headers and define the JSON payload structure for sending emails through your Generic HTTP provider, which supports dynamic values and batching.

Headers

Specify headers to pass authentication details (such as API keys or credentials) and campaign-level metadata. Authentication headers are typically static, for example, a username/password or token, and should be added as fixed key-value pairs. If your provider requires additional metadata (such as campaign identifiers) to be sent as headers, use dynamic placeholders to populate those at runtime.

You can either specify one of the following types of headers:

• Static Headers: In this case, you must specify fixed values. For example, Authorization: Bearer <API_KEY> or Content-Type: application/json.
• Dynamic Headers: Dynamic headers let you personalize your HTTP request payload with campaign- and user-level values at send time. These placeholders are defined using the $$ prefix and are replaced with actual values during message delivery. For instance, you can include placeholders such as $$UserName or $$CampaignID in the request headers. These are dynamically populated with actual values defined during campaign setup. To learn about Dynamic Replacement Parameters, refer to System Dynamic Replacements and Custom Dynamic Replacements.

In the following example, "UserName": "$$UserName" is a dynamic placeholder used in the payload. The part that follows the $$ (in this case, UserName) must match the key you define in the Request Headers section during campaign setup.

CleverTap uses this mapping to replace the placeholder with the corresponding value when sending the campaign.

When using the GET method, parameters are passed via the Request Query Parameters section. This section lets you define dynamic values that CleverTap sends to the query string of your HTTP endpoint.

🚧

Note

Do not use dynamic placeholders such as $$HTML or any large body content in the query string of the request. Including such content can significantly increase the URL length and may lead to request failures.

In the following example, you define a value for PromoCode during campaign creation.

Body Parameters

For a POST request type, these parameters are included in the request body to define recipient details and message content. You can also configure batch processing to send multiple messages in a single request.

Sample Request Without Batching

{
  "peid": "1202159255273620968",
  "tmid": "1202159255273620968",
  "cid": "$$CampaignID",   "fromName": "$$FromName",
  "fromAddress": "$$FromAddress",   "to": "$$To",
  "cc": "$$cc",   "bcc": "$$bcc",
  "mid": "$$MessageID",   "uid": "$$userid",
  "variables": "$$TemplateVariables",   "typeB": "$$HTML",
  "plaintext": "$$Plaintext",   "amp": "$$AMPHTML",
  "replyTo": "$$ReplyToAddress",   "tid": "$$Subject"
}

Sample Request With Batching

If your provider supports batching, structure your payload as shown below. In the following example, the msgs array holds multiple personalized email messages. Ensure all dynamic parameters that require user-level or campaign-level personalization (such as $$CampaignID) are included within each object inside msgs.

{
  "peid": "1202159255273620968",       // Static Global key-value pair
  "tmid": "1202159255273620968",       // Static Global key-value pair
  "msgs": [
    {
      "seq": 1,                        // Static parameter
      "cid": "$$CampaignID",                   "type": "$$FromName",
      "typeA": "$$FromAddress",       "to": "$$To",
      "cc": "$$cc",       "bcc": "$$bcc",
      "mid": "$$MessageID",       "uid": "$$userid",               // Dynamic custom parameter, value for userID key should be provided during campaign setup
      "typeB": "$$HTML",       "plaintext": "$$Plaintext",
      "amp": "$$AMPHTML",       "replyTo": "$$ReplyToAddress",
      "tid": "$$Subject"     },     {       "seq": 2,       "cid": "$$CampaignID",
      "type": "$$FromName",       "typeA": "$$FromAddress",
      "to": "$$To",       "cc": "$$cc",
      "bcc": "$$bcc",       "mid": "$$MessageID",
      "uid": "$$userid",       "typeB": "$$HTML",
      "plaintext": "$$Plaintext",       "amp": "$$AMPHTML",
      "replyTo": "$$ReplyToAddress",       "tid": "$$Subject"
    }
  ]
}

📘

Batch Size Limit

CleverTap supports a maximum batch size of 1000 records in a single request.

System Dynamic Replacements

You can use the following dynamic replacements within your payload. At send time, CleverTap replaces each placeholder with the corresponding value.

📘

Attachment Keys

The three attachment key placeholders must be used together within an array object in the request body, and cannot be used individually or outside an array. For more information, refer to Sending Attachments.

Custom Dynamic Replacements

Custom dynamic replacements allow you to pass additional metadata, such as user preferences or campaign-level attributes, into your payload. These placeholders are defined during campaign setup and are replaced by CleverTap at send time.

{
  "cid": "432",                            // Global Key-Value pair
  "msgs": [                               // Start of batched message array
    {
      "from": "$$FromName",              // System Dynamic Parameter: sender display name       "senderaddr": "$$FromAddress",   // System Dynamic Parameter: sender email address
      "to": "$$To",                    // System Dynamic Parameter: recipient email address       "mid": "$$MessageID",           // System Dynamic Parameter: unique message ID (used in callbacks)
      "name": "$$name",             // Custom Dynamic Parameter: recipient’s name (user-level personalization)       "uid": "$$userID",    // Custom Dynamic Parameter: user’s ID (user-level personalization)
      "content": "$$HTML",      // System Dynamic Parameter: HTML email body       "heading": "$$Subject"   // System Dynamic Parameter: email subject
    }
  ]
}

In a batching scenario, the JSON payload consists of the following two parts

• Global Key-Value Pairs: Apply uniformly across the entire batch; do not support personalization. In the above example, cid : 432 is a global key-value pair.
• Message-level Key-Value Pairs: Specific to individual messages within the batch, supports personalization. In the above example, all the parameters within the msgs array are message body key-value pairs.

When the campaign is sent, CleverTap resolves all placeholders and sends the payload to your email service provider (refer to the following sample JSON payload):

{
  "cid": "43a",
  "discountPercentage": "$$DiscountPercentage",
  "msgs": [
    {
      "from": "Acme Deals",
      "senderaddr": "[email protected]",
      "to": "[email protected]",
      "mid": "[email protected]|1568798080|1730799638|20241105|0|wzrk_default|-17005910|",
      "name": "Sara",
      "uid": "user_9021",
      "content": "<html><body>Hello Sara, enjoy your exclusive 20% discount today!</body></html>",
      "heading": "Your 20% Discount Awaits!"
    }
  ]
}

Sending Attachments

When the campaign is sent, CleverTap replaces the attachment placeholders with actual base64-encoded attachment data.

The array key name (for example, attachments, files, or any other name) and all field names remain exactly as you defined them in the template. CleverTap replaces the placeholder values $AttachmentFileName, $AttachmentType, $AttachmentContent) with the actual attachment data at send time.

Without Batching

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Your Invoice",
  "html": "<p>Please find attached…</p>",
  "attachments": [
    {
      "file_name": "$$AttachmentFileName",
      "content_type": "$$AttachmentType",       "content": "$$AttachmentContent"
    }
  ]
}

With Batching

{
  "fromName": "$$FromName",
  "fromAddress": "$$FromAddress",   "msgs": [     {       "to": "$$To",
      "mid": "$$MessageID",       "subject": "$$Subject",
      "html": "$$HTML",       "files": [         {           "file_name": "$$AttachmentFileName",
          "content_type": "$$AttachmentType",           "content": "$$AttachmentContent"
        }
      ]
    }
  ]
}