Sending emails

Send transactional emails.
POST https://api.sidemail.io/v1/mail/send

Parameters

Key

Type

Description

toAddress (required)

string

A valid email email address that will receive the email. Only ASCII characters are supported.

subject

string

An email subject line.

fromName

string

The name of sender. For example: "Sidemail". It has to have at least 1 character and maximum length is 100 characters. Only ASCII characters are supported.

fromAddress (required)

string

Sender email address. Has to be verified. Manage verified email addresses at project settings in the UI. For example: "info@sidemail.io". Only ASCII characters are supported.

templateId

string

A template ID of the template you want to send. Template ID cannot be used together with template name.

templateName

string

A template name of the template you want to send.Template name cannot be used together with template ID.

templateProps

object

Specify values of template variables here. Use exactly the same key name (whitespace sensitive) as you did in your email template and the value will be used.

If a variable has been defined in your email template, but you didn't add it to templateProps when making an API request, the key name of the variable will be used as a fallback.

Properties of templateProps are required to be string type (objects, booleans, integers, etc. are not supported).

html

string

A custom HTML version of email you're sending. Cannot be used together with a template.

text

string

A custom plain-text email. Cannot be used together with a template. Combine with html to create both a plain-text and html version of your email.

At least one of: templateId, templateName, html or text is required.

Example

Send Single sign-on email using email template to user@example.com.

Node.js
PHP
Ruby
Python
cURL
Other
/**
* Require the Sidemail library.
*
* If you haven't already, install it with either:
* - npm install @sidemail/sdk-js
* - yarn @sidemail/sdk-js
**/
const configureSidemail = require("@sidemail/sdk-js");
// Create Sidemail instance and set your API key.
const sidemail = configureSidemail({
apiKey: "xxxxx",
});
try {
const response = await sidemail.sendMail({
fromAddress: "your@startup.com",
toAddress: "user@email.com",
templateName: "Single sign-on",
templateProps: { url: "https://your.app/sso?token=123" },
});
// Response will contain scheduled email ID
console.log(
`An email with ID '${response.id}'
was successfully scheduled to be send. :)`
);
} catch (err) {
// Uh-oh, we have an error! You error handling logic...
console.error(err);
}

sendMail will throw an Error if there will be a problem. So, it's recommended to use sendMail inside the try catch block to handle any errors that might occur. If no errors were thrown, the processing was successful.

<?php
// Don't hard-code sidemail API key here, this is just for a demonstration.
// Use environment variables to store the sidemail API key instead.
const SIDEMAIL_API_KEY = "xxxxx";
$payload = [
"fromAddress" => "your@startup.com",
"toAddress" => "user@example.com",
"templateName" => "Single sign-on",
"templateProps" => [
"url" => "https://your.app/sso?token=123",
],
];
$context_options = [
'http' => [
'method' => 'POST',
'header'=> "Content-type: application/json\r\n"
. "Authorization: Bearer " . SIDEMAIL_API_KEY . "\r\n",
'content' => json_encode($payload)
]
];
$context = stream_context_create($context_options);
$fp = fopen('https://api.sidemail.io/v1/mail/send', 'r', false, $context);
$response = json_decode(stream_get_contents($fp));
fclose($fp);
// Email was successfully scheduled
echo "Email ID: " . $response->id . " has status: " . $response->status;

200 Response:

{
"id": "xxxxxx",
"status": "queued"
}
require 'uri'
require 'net/https'
require 'json'
# Don't hard-code sidemail API key here, this is just for a demonstration.
# Use environment variables to store the sidemail API key instead.
SIDEMAIL_API_KEY = 'xxxxx'
url = URI("https://api.sidemail.io/v1/mail/send")
payload = {
:fromAddress => "your@startup.com",
:toAddress => "user@example.com",
:templateName => "Single sign-on",
:templateProps => {
:url => "https://your.app/sso?token=123",
}
}
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request['Authorization'] = 'Bearer ' + SIDEMAIL_API_KEY
request.body = JSON.generate(payload)
response = https.request(request)
puts response.read_body

200 Response:

{
"id": "123",
"status": "queued"
}
import http.client
import json
# Don't hard-code sidemail API key here, this is just for a demonstration.
# Use environment variables to store the sidemail API key instead.
SIDEMAIL_API_KEY = 'xxxxx'
connection = http.client.HTTPSConnection("api.sidemail.io")
payload = {
'fromAddress': 'your@startup.com',
'toAddress': 'user@example.com',
'templateName': 'Single sign-on',
'templateProps': {
'url': 'https://your.app/sso?token=123'
}
}
headers = {
'content-type': 'application/json',
'Authorization': 'Bearer ' + SIDEMAIL_API_KEY
}
connection.request("POST", "/v1/mail/send", json.dumps(payload), headers)
response = connection.getresponse()
data = json.loads(response.read().decode("utf-8"))
# Email was successfully scheduled
print(data)

200 Response:

{
"id": "xxxxxx",
"status": "queued"
}
curl --request POST \
--url https://api.sidemail.io/v1/mail/send \
--header 'Authorization: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data '{"fromAddress": "your@startup.com", "toAddress": "user@example.com", "templateName": "Single sign-on", "templateProps": {"url": "https://your.app/sso?token=123"}}'

200 Response:

{
"id": "xxxxxx",
"status": "queued"
}
# To send a transational email with Sidemail create a POST HTTP request to:
"https://api.sidemail.io/v1/mail/send"
# Because Sidemail API is using JSON, you'll need to include this header:
"Content-Type: application/json"
# To authorize the API request, include this header with this project's API key:
"Authorization: Bearer xxxxx"
# Then, it's just a matter of sending the right JSON data.
# To send a 'Single sign-on' email using the Sidemail template,
# the data would look like this:
{
"fromAddress": "your@startup.com",
"toAddress": "user@example.com",
"templateName": "Single sign-on",
"templateProps": {
"url": "https://your.app/sso?token=123"
}
}
# If you receive response code 200, the email was successfully scheduled to be sent.
# The JSON response will look like this:
{
"id": "123",
"status": "queued"
}

Errors

Visit responses section for more information about typical error response structure.

  • This email address is not verified. Make sure the fromAddress is verified. To manage verified addresses and domains go to your project settings.

  • Upgrade your sending plan for custom HTML emails. Free plan users can only send email templates. If you need more flexibility, such as custom HTML emails, plain-text emails or both consider upgrading to a premium plan.

  • This project has been suspended due to large bounce or complaint rate. Please, contact us at support@sidemail.io for more information. Sidemail tolerates bounce rate under 4.95% and complaint rate under 0.095%. For new projects with small amount of total sent emails there is limit based on maximum bounces and complaints you can have rather than rate in percentage. This is because in worst case scenario you could get 100% bounce rate if your first sent email was a bounce and your project would be therefore suspended. Sidemail enforces these rules to make sure your emails are delivered reliably and as quickly as possible. If you have high bounce or complaint rates you might be doing something wrong. If you have any questions, contact us.

  • Missing authorization token. Check the authentication section on how to properly authenticate API calls.

  • Misconfigured request. Request has to have Bearer token. Check the authentication section on how to properly authenticate API calls.

  • Looks like you ran out of the free sending limit. Visit https://app.sidemail.io/settings/billing and upgrade your sending limit. You ran out of your free sending limit. Consider upgrading to a premium plan where you can set your own sending limit.

  • Looks like the provided template doesn't exist. Supply template ID or template name or custom HTML. Provided template ID or template name doesn't exist. Both fields are case sensitive and whitespace sensitive.