Send a transactional email

Learn how to send a transactional email for an existing template and adding dynamic content

Transactional emails are used for all non-promotional emails: send them when a user has created an account, when they have made an order, when request a new password...

πŸ‘

What you will learn from this tutorial

In this tutorial, you will learn how to:

  • send a basic transactional email with a dummy HTML content.

  • send a transactional email where we'll insert dynamic contact attributes (ex. contact name, address)

Requirements

Get your API key from your settings (SMTP & API).

If you are new to the API, read more about how the api works.

Send a transactional email using a basic HTML content

Let's assume we would like to send the following basic email.

HTML content <html><head></head><body><p>Hello,</p>This is my first transactional email sent from Kasplo.</p></body></html>
Email subject"Hello worldl"
Sender name"Sender Alex"
Sender email"email":"senderalex@example.com"
Recipient name"John Doe"
Recipient email"email":"johndoe@example.com"

The HTTP request to send using cURL is the following:

curl --request POST \ --url https://api.kasplo.in/send-mail \ --header 'accept: application/json' \ --header 'api-key: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ --email: { "from": "senderalex@example.com", "fromName": "Sender Alex", "replyTo": [], "subject": "Hello world", "text": "", "html": "html><head></head><body><p>Hello,</p>This is my first transactional email sent from Kasplo.</p></body></html>", "recipients": { "to": [{ "name": "John Doe", "email": "testmail@example.com" }], "cc": [], "bcc": [] }, "attachments": [] } }'
curl --request POST \ --url https://api.kasplo.in/send-mail \ --header 'accept: application/json' \ --header 'api-key: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ --email: { "from": "senderalex@example.com", "fromName": "Sender Alex", "replyTo": [], "subject": "Hello world", "text": "", "html": "html><head></head><body><p>Hello,</p>This is my first transactional email sent from Kasplo.</p></body></html>", "recipients": { "toList": [{ "name": "John Doe", "email": "testmail1@example.com" },{ "name": "Rock Doe", "email": "testmail2@example.com" }], "cc": [], "bcc": [] }, "attachments": [] } }'

Send your transactional email

Let's learn how to use the API. The best way to know what's possible and how to use each endpoint is to go to the API Reference.

1. Generate a code snippet to quickly test your request:

  1. Enter the body and path parameters to send in your request. These are the ones we'll need:
  • from: Enter your sender email and name
    :bulb: the sender email must be a sender registered and verified in Kasplo
    :bulb: the sender fromName parameter here can override the default sender name you have set
  • to: Enter your recipient email and name
    :bulb: the recipient email should be a contact registered in Kasplo and assigned to a contact list. That contact should have the attributes FIRSTNAME, LASTNAME, EMAIL, DELIVERYADDRESS defined.
    :bulb: the recipient name here is the name that will be attached to the email recipient. It will appear in the email headers/metadata and not in the email body.
  • templateId : Enter your template id
  • params: the value we will use is {"ORDER": 12345, "DATE": "12/06/2019"}
  • toList: Enter your recipient email and name
    :bulb: When providing multiple emails in the "tolist," recipients can view all other recipients and CC emails in the email.
    :bulb: If only the "to" field is specified with a list of multiple emails, treat each email as an individual recipient.
  1. Try out the endpoint from the interface. For that, click the " Try it" button and enter you API key
  • If everything goes well, you should get a success API response (code 201) with a JSON body.
  • Notice that the order number and delivery date will be missing from the email received. The reason is that using the API reference interface, you cannot specify rich JSON body parameters like the params to provide DATE and ORDER, so you'll have to use the code snippets and test using cURL or using other integrations. Go to next section for more details.
  • If the parameters you entered are wrong, you'll get a 400 error along with an error message and error code. Find the list of errors here.

🚧

API Reference limitations and rating

When you try an endpoint, you will make a real call to the API.
Make sure to check rate limits and your credits as the API reference will use them to make the requests (when sending an email or an sms for instance).

Read more about Kasplo sending email bandwidth and quota

Creating your API request using Kasplo API clients:

The code snippets in the API Reference are only there for you to test your API quickly and in the language that suits you.

:+1: For your integration, we recommend you use our API clients that will provide you with shortcuts and ease of integration.
Available API clients and their documentations: C#,Go,Java,Node JS,Python, Ruby.

Here are sample codes using the API clients. Before using then, follow the installation guide from each documentation linked above.


curl --request POST \ --url https://api.kasplo.in/send-mail \ --header 'accept: application/json' \ --header 'api-key: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ --email: { "from": "senderalex@example.com", "fromName": "Sender Alex", "replyTo": [], "subject": "Hello world", "text": "", "html": "html><head></head><body><p>Hello,</p>This is my first transactional email sent from Kasplo.</p></body></html>", "recipients": { "to": [{ "name": "John Doe", "email": "testmail@example.com" }], "cc": [], "bcc": [] }, "attachments": [] } }'

πŸ‘

For each request, make sure to include the following headers:

  • api-key: Bearer xxxxxxxxxxxxxxxxx
  • content-type: application/json
  • accept: application/json

:+1: Check your emails! Congratulations, you've just sent your first transactional email using Kasplo API!


Status codes

Status CodeDescriptionHTTP Status
1000Success200
9001Throttling error.

To handle the loads with increasing customer base, Kasplo has introduced autoscaling which can occasionally result in higher call rates. Kasplos upports throttling from API end to handle such cases. Sending this status code will activate throttling for that request and Kasplowill send that request at later time.

Note:
1. Kasplowill retry sending the message 10 times if this status is received.
2. Time interval between retries follows binary exponential backoff: 0ms, 200ms, 400ms, 800ms...
429
9002Message sending quota exceeded200
9003Authentication failure403
9004Recipient address not specified400
9005From field missing400
9006Soft bounce (temporarily deferred)200
9007Hard bounce200
9008Email reported as spam200
9009Email unsubscribed200
9010Email in suppression list200
9011Sender address not verified400
9012API rejected message200
9013Request to API expired200
9014API unavailable500
9015IP not whitelisted with API401
9016Subject field empty400
9017Invalid sender address400
9018Invalid email address400
9019Recipient’s mail box is full200
9020Error processing email at Private API500
9021Mailbox was not found on email server200
9022Unsupported or unknown version (A)
In this case the supportedVersion is to be sent mandatorily, i.e., the version supported by the service provider. For example:
HTTP 400 BAD REQUEST { "status": "ERROR", "statusCode": 9022, "message": "Unsupported version", "supportedVersion": "2.0" }
400
9024Authorization failure403
9452Message overloading200
9512Host email server not found200
9999Unknown error occurred200

We hope this has enabled you to set up a decryption layer for sending Email campaigns to encrypted email addresses. Please feel free to drop in a few lines at helpdesk@kasplo.com in case you have further queries. We're always just an email away!

Updated about 1 month ago