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, failures, and 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 allow you to personalize your HTTP request payload with campaign-level 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 at the time of sending the campaign.

When using the GET method, parameters are passed via the Request Query Parameters section. This section allows you to define dynamic values that CleverTap sends into 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.

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

Set Up Callbacks

CleverTap enables real-time tracking of delivery status and user interactions, such as bounces, unsubscribes, spam reports, and clicks, through HTTP callbacks sent to CleverTap's Callback URL displayed during provider setup.

During provider setup, you must include a key in your outgoing payload (for example, mid) with $$MessageID as its value. CleverTap replaces this dynamic placeholder with a unique identifier for each message sent. This identifier must be returned in the callback payload to allow CleverTap to attribute the callback to the appropriate campaign and user profile.

Sample Callback Request

The following is an example payload structure of a callback request that can be sent to the CleverTap callback URL:

{
  "version": "v2",
  "events": {
    "success": [
      {
        "type": "delivered",	//Indicates the message was delivered to the intended recipient 
        "email": "[email protected]",	//recipient email address
        "meta": "[email protected]|1568798080|1730799638|20241105|0|wzrk_default|-17005910|"
      }
    ],
    "failed": [ 
      {
        "type": "unsubscribed", // Indicates the user has unsubscribed		
        "email": "[email protected]",		// The email address of the affected user
        "meta": "[email protected]|1568798080|1730714617|20241104|0|wzrk_default|-17005907|",
        "description": "User Unsubscribed"
      },
      {
        "type": "hard_bounce",
        "email": "[email protected]",
        "meta": "[email protected]|1568798080|1730799638|20241105|0|wzrk_default|-17005910|",
        "description": "Hard bounce detected"
      },
      {
        "type": "soft_bounce",
        "email": "[email protected]",
        "meta": "[email protected]|1568798080|1730714617|20241104|0|wzrk_default|-17005905|",
        "description": "Recipient Inbox Full"
      },
      {
        "type": "spam",
        "email": "[email protected]",
        "meta": "[email protected]|1568798080|1730714617|20241104|0|wzrk_default|-17005904|",
        "description": "Marked as spam"
      }
    ]
  }
}

Ensure your callback payload includes the following keys:

Incoming Payload Mapping to System Events

CleverTap maps the incoming payloads with their respective system events. You can view these on the CleverTap dashboard.

Response Codes

CleverTap sends the following status codes and descriptions as a response to the ESP upon receiving callbacks:

The following is the sample response sent by CleverTap to the provider upon processing the callback payload successfully:

{
  "TOTAL_EVENTS": 4,
  "PROCESSED_EVENTS": 4,
  "UNPROCESSED_EVENTS": []
}

📘

Retry Mechanism for Errors

In case of HTTP 5XX errors, we recommend retrying after 10 minutes with exponential backoff as CleverTap does not deduplicate requests.