Overview

CleverTap supports integrating any Email Service Provider (ESP) using the SMTP protocol to send Email campaigns.

Integrate Email Service Provider

To integrate the ESP with CleverTap, follow these steps:

1. Go to Settings > Email from the dashboard and click + Provider.
2. Select SMTP from the Provider dropdown.
3. Enter the following details:

4. Click Save to save your settings.
5. Click Send a test email. After the setup is complete, you will receive an email in your inbox. If you do not receive the email, refer to Troubleshooting.

SMTP Callbacks

SMTP Callbacks provide insights into delivery success, failures, unsubscribes, and spam reports of your SMTP email provider. These insights help optimize strategies and improve email campaign performance through the following:

• Notification Failed Event: The Notification Failed event is raised to track delivery issues such as hard and soft bounces. The type parameter in this event specifies the reason for the failure, such as hard bounce, soft bounce, spam, or unsubscribed.
• Profile Unsubscribes: When users unsubscribe, mark emails as spam, or experience a hard bounce (excluding soft bounces), their profiles are automatically unsubscribed from future communications, triggering the Channel Unsubscribed event.

Callback requests must be made to CleverTap's Callback URL. The ESP must add this URL to their Email Provider Settings to pass these callback events. You can find the CleverTap Callback URL under the Provider Setup tab on the CleverTap dashboard.

Configure SMTP Callback

In the outgoing email SMTP payload, CleverTap sends the X-CleverTap_META key with a specific value. The provider must send the same value in the callback payload to CleverTap's callback URL within the meta key. When received along with the incoming callback payload, this helps attribute a callback to a specific profile and campaign.

Send Callback Events

To send callback events to CleverTap, customers must send a POST request to CleverTap's Callback URL. The following is a sample callback payload:

{
  "version": "v2",
  "events": {
    "failed": [
      {
        "type": "unsubscribed", // Indicates the reason for failure, in this case, the user has unsubscribed		
        "email": "user1@example.com",		// The email address of the affected user
        "meta": "user1@example.com|1568798080|1730714617|20241104|0|wzrk_default|-17005907|",		
        "description": "Hard bounce detected"		// Additional details of the failure reason
      },
      {
        "type": "hard_bounce",
        "email": "user3@example.com",
        "meta": "user3@example.com|1568798080|1730799638|20241105|0|wzrk_default|-17005910|",
        "description": "Hard bounce detected"
      },
      {
        "type": "soft_bounce",
        "email": "user5@example.com",
        "meta": "usert5@example.com|1568798080|1730714617|20241104|0|wzrk_default|-17005905|",
        "description": "Recipient Inbox Full"
      },
      {
        "type": "spam",
        "email": "user4@example.com",
        "meta": "user4@example.com|1568798080|1730714617|20241104|0|wzrk_default|-17005904|",
        "description": "Marked as spam"
      }
    ]
  }
}

The following table provides a brief description of the keys present in the callback payload:

📘

Note

If the payload includes additional key-value pairs apart from the ones that are defined in the acceptable sample payload for each event, CleverTap does not throw any errors, but simply disregards those.

Incoming Payload Mapping to System Events

CleverTap maps the following incoming payloads with their respective system events:

• Notification Failed: This event is raised if the callback event fieldtype has values such as hard_bounce or soft_bounce. The event property Error of the Notification Failed event specifies the type of failure, that is, hard bounce or soft bounce.

• Channel Unsubscribed: This event is raised if the callback event field type has values such as unsubscribed, spam, or bounce. The event property Type of the Channel Unsubscribed event specifies the reason for profile unsubscription.

Response Codes

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

Sample Response

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": []
}

The following is the sample response sent by CleverTap to the providers upon partial processing of callback events:

{
    "error": "2 event(s) failed to process",
    "TOTAL_EVENTS": 4,
    "PROCESSED_EVENTS": 2,
    "UNPROCESSED_EVENTS": [
        {
            "type": "hard_bounce",
            "email": "user1@clevertap.com",
            "description": "User hard bounce",
            "errorDescription": "invalid meta"
        },
        {
            "email": "user2@clevertap.com",
            "meta": "user2@clevertap.com|1568798080|1733728287|20241209|0|wzrk_default|-17006141|",
            "description": "User soft bounce",
            "errorDescription": "Could not map event to any bounce type"
        }
    ]
}

The following is the sample error response:

{
    "error": "Exception occurred while reading input stream",
    "TOTAL_EVENTS": 0,
    "PROCESSED_EVENTS": 0,
    "UNPROCESSED_EVENTS": []
}

Handle Bounces

When a recipient’s email server rejects an email, it is called a bounce. There are two types of bounces:

• Soft Bounces: Soft bounces typically indicate a temporary delivery issue to an address. Some reasons for a soft bounce could be that the recipient’s mailbox is full or the Mail Server is down. Soft bounces are included in the campaign reports; the users are not marked unsubscribed.
• Hard Bounces: A hard bounce indicates a permanent reason an email cannot be delivered. Hard bounces are included in the campaign reports; the users are marked as unsubscribed.
  To handle bounced email messages, you must make an HTTP request to the callback URL specified under the Setup tab of Settings > Channels > Email page on the CleverTap dashboard.

Handle Unsubscriptions

To share unsubscription data from custom pages directly, you need to make an HTTP request to the callback URL specified under the Setup tab of Settings > Channels > Email page on the CleverTap dashboard.

For more information about handling unsubscription requests from users, refer to Handling Unsubscribes.

Troubleshooting

• As you are using your SMTP gateway, some email providers, such as Gmail and Yahoo, might not deliver the email to your inbox.
• Check if you have set up DKIM and SPF correctly.
• Check if Spamhaus has blacklisted your IP/domain.

🚧

Unsubscription Link

The Unsubscribe link does not work test emails sent when creating an email cmapign.

Errors

The following table lists the errors that you may encounter after sending a campaign: