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 the 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 keys from your settings (SMTP & API).
If you are the 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 data-rsssl=1><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 data-rsssl=1><p>Hello,</p>This is my first transactional email sent from kasplo.</p></body></html>
"recipients": {
"toList": [{
"name": "John Doe",
"email" : "testmail@example.com".},
{
"name":"Rock Doe",
"email": "testmail2example.com"
}],
"cc": [],
"bcc":[]
},
"attachments":[]
}
},
Send your transactional email
Learn how to use the API. The best way to know what’s possible and how to use each endpoint is to go the API references.
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
Â Â Â Â đŸ’¡the sender email must be a sender registered and verified in Kasplo.
Â Â Â Â đŸ’¡the sender fromName parameter here can override the default sender name you have set.
- to: Enter your recipient email and name
Â Â Â Â Â đŸ’¡the recepient email should be a contact registered in Kapslo and assigned to a contact list. The contact should have the attributes FIRSTNAME, LASTNAME, EMAIL, DELIVERYADDRESS defined
Â Â Â Â Â Â đŸ’¡the recepient 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 emails body. Â
- template Id : Enter your template id
- params: The value we will use is {“ORDER “:12345, “DATE”: “12/06/2019”}
- toList: Enter your recipient email and name
Â Â Â Â Â Â Â đŸ’¡When providing multiple emails in the “tolist”, recipients can view all other recipients and CC emails in the email.
Â Â Â Â Â Â Â đŸ’¡If only the “to” fields is specified with a list of multiple emails , treat each emails as and individual recipient.
2. Tryout the endpoint from the interface.
For that click the “Try it” button and enter your API key.
- If everything goes well,you should get the access 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 referance interface, you cannot specify rich JSON body parameters like the params to provide DATE and ORDER , so you’ll have to use the code snippet 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 the error message and error code. Find the list of errors here.
API reference limitations and rating
When you try a end point , you will make a real call to the API .Â
Make sure to check rate limits and your credits as the API references will use them to make requests ( when sending an email or SMS for instances
Read more about kasplo sending email bandwidth and quota
Creating your API request using Kasplo API clients:
The code snippets in the API references are only there for you to test your API quickly and in the language that suits you.
For your integration, we recommend you use our API clients that will provide you with shortcuts and ease of integrations. Available API clients and their documentations: C#,Go, Java,NodeJS, Python, Ruby.
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 data-rsssl=1><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 xxxxxxxxxxxxxxxxxx
- content -type: application/ json
- accept: applicaion/ json
Check your emails! Congratulations, you've just sent your first transactional email using Kasplo API!
Status Codes
| Status Code | Description | HTTP status |
|---|---|---|
|
1000 |
Success |
200 |
|
9001 |
Throttling error. To handle the loads with increasing customer base , Kasplo has introduced autoscaling which can occasionally result in higher call rates. Kasplo supports throttling from API to handle such cases. Sending this status code will activate throttling for that request and Kasplo will send that request at later time. Note: 1. Kasplo will retry sending the message 10 times if the status is received. 2.Time interval between retries follows binary exponential backoff: 0ms, 200ms, 400ms, 800ms.. |
429 |
|
9002 |
Message sending quota exceeded |
200 |
|
9003 |
Authentication failure |
403 |
|
9004 |
Recipient address not specified |
400 |
|
9005 |
Form field missing |
400 |
|
9006 |
Soft bounce (temporarily deferred) |
200 |
|
9007 |
Hard bounce |
200 |
|
9008 |
Email reported as spam |
200 |
|
9009 |
Email unsubscribed |
200 |
|
9010 |
Email in suppression list |
200 |
|
9011 |
Sender address not verified |
200 |
|
9012 |
API rejected message |
200 |
|
9013 |
Request to API expired |
200 |
|
9014 |
API unavailable |
500 |
|
9015 |
IP not whitelisted with API |
401 |
|
9016 |
Subject field empty |
400 |
|
9017 |
Invalid sender address |
400 |
|
9018 |
Invalid email address |
400 |
|
9019 |
Recipients mail box is full |
200 |
|
9020 |
Error processing email at private API |
500 |
|
9021 |
Mailbox was not found on email server |
200 |
|
9022 |
Unsupported or unknown version (A)
In this case the supported version is to be send mandatorily , i.e the version supported by the service provider. For Example: HTTP 400 BAD REQUEST { “status”: “ERROR”, “statusCode”: 9022, “message”:”Unsupported version”, “support version”:”2.0″} |
400 |
|
9042 |
Authorization failure |
403 |
|
9452 |
Message overloading |
200 |
|
9512 |
Host email server not found |
200 |
|
9999 |
Unknown error occured |
200 |