Generic SMTP

Overview

While we highly recommend using a reputable email service provider (ESP) such as Amazon SES, Postmark, or SendGrid. You can also integrate any other SMTP gateway to send emails.

Set Up Email Provider

This process involves the following three major steps:

  1. Set Up CleverTap dashboard.
  2. Handle Bounces.
  3. Handle Unsubscriptions.

Set Up CleverTap Dashboard

To set up the CleverTap dashboard:

  1. Navigate to Settings > Email from the dashboard and click + Provider.
  2. Select SMTP from the Provider dropdown.
  3. Enter the following details:
FieldDescription
HostIn the Host text box, fill your publicly accessible IP address or hostname of your SMTP server
PortIn the Port text box, fill in your SMTP port.
Username and PasswordUsername and Password values must be your SMTP credentials needed to connect to the service.
From AddressFrom Address value is the sender’s email address. Most people will not open an email unless they recognize the sender.
  1. Click Save to save your settings.
  2. Click Send a test email. You will receive an email in your inbox after the setup is complete. If you do not receive the email, refer to Troubleshooting.

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 need to make an HTTP request to the callback URL specified under Dashboard > Settings > Integration > Email > Setup provider tab > Nickname.

Ensure that the request is be of type HTTP POST with the payload in the following format:

// if you're not sure of the time of the bounce, just set it to the current epoch

[
    {
        "event": "softbounce",
        "data": [
            {
                "e": "[email protected]",  // email id that soft bounced
                "ts": 1435322805                  // time of the bounce
            },
            {
                "e": "[email protected]", // email id that soft bounced
                "ts": 1435322805                  // time of the bounce
            }
        ]
    },
    {
        "event": "hardbounce",
        "data": [
            {
                "e": "[email protected]",   // email id that hard bounced
                "ts": 1435322805
            }
        ]
    }
]

Handle Unsubscriptions

To share unsubscription data from custom pages directly, you need to make an HTTP request to the callback URL that is specified in Dashboard > Settings > Channels > Email > Setup tab. Ensure that the request is of type HTTP POST with the payload in the following format.

// if you're not sure of the time of the unsubscribe, just set it to the current epoch

[
    {
        "event": "unsubscribe",
        "data": [
            {
                "e": "[email protected]",  // email id of the user
                "ts": 1504632929                  // time of the unsubscribe
            },
            {
                "e": "[email protected]", // email id of the user
                "ts": 1500630929                  // time of the unsubscribe
            }
        ]
    }
]

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 unsubscription link does not work for test emails sent from the notification creation page.

Errors

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

ErrorDescription
SMTP invalid email IDCause 1: The SMTP invalid email ID error occurs when the provided email address is not formatted correctly or does not exist. Typos or errors in the email address commonly cause this error. Resolution: Double-check the email address and ensure the email ID is valid to fix this error. Cause 2: This error can also occur if you are using a test email address. Resolution: We recommend using an actual email address. Contact your ESP's customer support for further assistance if the issue persists.
SMTP dispatching failedCause: The SMTP dispatching failed error occurs when the email message cannot be delivered to the recipient's email address.Some of the other common causes could be:
  • The email address that you are trying to send to is incorrect.
  • The email address's domain is invalid.
  • The recipient's ESP blocks your IP address.
  • The ESP is experiencing a temporary outage.
Resolution: To fix this error, you can check the recipient's email address and ensure that the email address is valid and that the email infrastructure is working correctly. If the issue persists, contact your provider's customer support.
SMTP connection error Cause: The SMTP connection error occurs when CleverTap is unable to establish a connection with your ESP's SMTP server.Some of the other common causes could be:
  • Incorrect server details such as the server's hostname, port, or credentials. You can check the server details you have entered to confirm they are correct.
  • Network issue that prevents the application from connecting to the SMTP server. It could be a temporary issue on your ESP's end.
Resolution: Contact your provider's customer support for further assistance if the issue persists.
SMTP timeoutCause: The SMTP timeout error occurs when CleverTap cannot connect with your ESP's SMTP server, or the connection takes longer than expected. Some of the other common causes could be:
  • The email-sending process has taken longer than the allocated time frame for connection establishment or completion.
  • The SMTP server of your ESP is experiencing high traffic.
  • Your sending IP has been flagged as a source of spam.
  • There is an issue with your ESP's infrastructure.
Resolution: Contact your provider's customer support for further assistance if the issue persists.