Send transactional emails via API

Introduction

Sending transactional emails from your application is a matter of just a few easy steps with Sidemail. Discover the new way developers tackle user communication via email. Designed for both the best DX and UX, Sidemail no-code email editor, pre-made email templates, and simple HTTP API is the true 80/20 solution.

Read on to learn how to send the following emails from your application:

  • Welcome email (onboarding email)
  • Password reset email
  • Single sign-on email (SSO email, magic login link email)
  • Failed payment email (dunning email)
  • Trial expiration
  • Account activation
  • Payment receipt
  • Canceled subscription

No HTML email knowledge required

You don't need any knowledge of HTML emails because we'll look at how to use Sidemail's no-code email editor to create the actual emails that you'll later send from your app via API - you'll reference the email template either by name or its ID in the API request.

The big problem with email development is that you can never be quite sure if your email won't break in some email clients. The testing is costly, and maintenance is a headache.

Sidemail's no-code email editor supports virtually all email clients:

  • Mobile: Gmail, iOS 9.3+, Android 4.4+, Spark
  • Web: Gmail, Outlook.com, Yahoo! Mail, AOL, Zoho Mail
  • Desktop: Apple Mail, Windows 10 Mail, Outlook, Thunderbird

See how we tested dark-mode support in email clients and became the first email provider to offer dark-mode support for our customers.


How to start sending emails from your app

Before we start, you'll need a Sidemail account - create it here if you don't have one.

Now, let's get started.

Customize the email template design (1/3)

To customize the look of your email templates, visit your project settings → click the "Tweak design" button. Here, upload your company logo and fine-tune the color combination. You can also enable dark mode, which requires to upload both the light and the dark version of your logo.

Edit template design

Looks good? Nice. That's all there's to it.

Tweak pre-made email templates (2/3)

Visit the email templates page inside of your Sidemail project, and you'll see that you already have some email templates. We pre-made the most commonly used emails as email templates to give you the best starting point - you can use them as they're, completely change them or start from scratch, it's up to you.

For example, to edit the "Password reset" email template, click on the template to show a details modal window, then, click on the "Edit content" button. Now, you're looking at the no-code email editor, you can edit the content of email templates here. The no-code editor features various elements to help you structure your emails:

  • Text element
  • Button element
  • List element
  • Table element
  • Separator element (<hr />)
  • Image element
  • Code (syntax-highlighted) element

Each no-code element has some settings you can adjust, for example, vertical spacing and horizontal alignment.

Template editor

The Sidemail no-code email editor intentionally offers little to no configuration to shift your focus to the content. It's inspired by the idea of convention over configuration.

Configure the email template's additional settings such as preheader, default subject line, or whether to automatically generate the plain-text version by clicking the "Template settings" button above the template preview.

Done? Click the "Save changes" button.

Send email template via API (3/3)

Finally, it's time to send an email via API! To make this step easy, Sidemail generates copypasteable code samples in many programming languages:

Find the code samples inside of the email template details modal window, for example, in your Sidemail project → goto email templates page → click on the "Password reset" template → at the bottom of the modal window, you'll see the code samples.

Template code examples

The code samples include your Sidemail API key, so you can go ahead and copy-paste them straight into your code and see what happens!

Ok, but what exactly is happening?

Each code sample does the same thing - creates an HTTP request and sends data encoded as JSON to the Sidemail API endpoint. In the JSON data, you tell Sidemail details like who is the recipient, who is the email from, which email template to use. See all API options below.

The code samples for PHP, Ruby, and Python contain more code because the code samples use built-in HTTP libraries, which generally require more code than custom HTTP libraries, but you're not required to install any new dependencies. If your project is already depending on a custom HTTP library, feel free to use it here as well.


Next steps

You tweaked the email design and learned how to send the pre-made email templates, and that's all you need to implement sending of any transactional email from your app! 🎉

We pre-made all typical transactional emails you might need as email templates, but if you need a custom one, you can simply create it yourself.

Next, we'll look into getting ready for production.

Or skip ahead and discover all API options, such as scheduled email delivery, and what API errors you might stumble upon.


Verify your custom domain and enable DKIM

In order to send emails from your own domain, you have to verify the domain first by setting up a few DNS records. This step is required to ensure you have the right to use the domain.

For each of your projects, we provide a pre-generated sending domain that looks like this: project.via.sidemail.net. You can use the pre-generated sending domain for development and testing. However, it's not suited for production use.

Verify your custom domain in your project's settings. During the verifying process, Sidemail will give you 3 CNAME DNS records that you need to place in your domain's DNS provider. Typically, it takes just a few minutes for DNS changes to take effect. However, it can occasionally take longer - up to 72 hours.

Domain verification

Important: If your domain's DNS provider is Cloudflare, you need to disable Cloudflare proxy (the orange icon) for each CNAME record.

After successful verification:

  • You'll be able to send emails from the verified domain and all its subdomains, for example, @sidemail.io and @subdomain.sidemail.io. The email address part before the @ can contain anything you want, for example, anything@sidemail.io is valid.
  • All emails sent from the verified domain will be signed with DKIM, there's no further configuration needed.

Why so many DNS records?

A short answer: for redundancy and maximum security.

The 3 CNAME records are used for signing your emails with DKIM. To sign an email with DKIM, you need a pair of public and secret keys - similarly, what you might be using for SSH authentication.

It's a best practice to rotate your RSA keys from time to time (preferably every 3 months), and that's exactly why we need more than 1 CNAME DNS record for. When we rotate the DKIM keys, the old pair of keys have to stay valid for a few days, then its finally removed. The rotation of the DKIM keys happens completely automatically. It has no downsides and you don't need to configure anything.


Learning Sidemail email sending API

Now, let's look at how to make an HTTP API request to send an email from scratch.

  • The URL: https://api.sidemail.io/v1/mail/send
  • The method of the request: POST

You'll need to include these HTTP headers:

  • Content-Type: application/json to tell Sidemail you're sending JSON data
  • Authorization: Bearer your-sidemail-api-key-here to authenticate the API request with your API key

With formalities out of the way, let's focused on the JSON data. Here's an example:

{
    "fromAddress": "you@domain.com",
    "toAddress": "email@recipient.com",
    "templateName": "Some email template"
}

The above example is a bare minimum. Discover all API options.

Wait! No subject line? You can safely omit the subject line, and a default subject line from the template's settings will be used instead.

Here's how the complete API request should look like:

POST https://api.sidemail.io/v1/mail/send
Authorization: Bearer xxxxxxxxxxxx
Content-Type: application/json
{
    "fromAddress": "you@domain.com",
    "toAddress": "email@recipient.com",
    "templateName": "Some email template"
 }

Discover all available API parameters

KeyTypeDescription                                                                  
toAddress (required)stringA valid email email address that will receive the email. Only ASCII characters are supported.
subjectstringAn email subject line.
fromNamestringEmail display name that appears before the actual email address. For example: "Sidemail". It has to have at least 1 character and the maximum length is 100 characters. Only ASCII characters are supported.
fromAddress (required)stringSender 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. ​To define a display name (a nicely formatted name before the actual email address) look above for the fromName.
replyToAddressstringIf you want the recipient of the email to reply to a different email address than fromAddress, specify it with replyToAddress. Only ASCII characters are supported.
templateIdstringA template ID of the template you want to send. Template ID cannot be used together with template name.
templateNamestringA template name of the template you want to send.Template name cannot be used together with template ID.
templatePropsobjectSpecify 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).
htmlstringA custom HTML version of email you're sending. Cannot be used together with a template.
textstringA 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.
isOpenTrackedbooleanWhether the email should be open tracked or not. By default open tracking is turned on (true).
scheduledAtdateSpecify a delayed email delivery by providing a valid ISO 8601 date in the future.

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

Dynamic data with template props (variables)

In the real world, emails are not just static and that's when template props come in handy. Template props are basically variables that allow you to put dynamic data in your email templates.

To use a variable inside of your email template, use curly braces {}. You can use variables in all no-code elements, even as image source URL and ALT.

This is an example JSON data to send a password reset email template:

{
    "fromAddress": "you@domain.com",
    "toAddress": "email@recipient.com",
    "templateName": "Password reset",
    "templateProps": {
        "url": "https://reset.me/123"
    }
}

Notice the templateProps field. It's a JSON object in which you can pass any values to variables inside of your email template.

In the case of the password reset email template, we need a unique link for every user that receives the password reset email and takes him to the password reset page. So, in the password reset template, the URL of the "Reset password" button should be set to {url}.

Sidemail renders the specified email template and replaces all variables with corresponding values from templateProps when you make a send email API request. If there's no corresponding variable key inside of templateProps, a variable is left as is just the curly brackets {} are removed.

Here are a few ideas of how you can utilize template props:

  • to personalize the email with user's first name, eg., Patrik
  • to include unique typically auto-generated URLs (password reset, login link), eg., https://login.me/in?token=123
  • show the charged amount for your service on a receipt, eg., $249

Values inside of template props JSON object have to be string. Make sure you convert numbers to strings, otherwise, Sidemail will return a validation error.

Sending custom HTML emails

You can send custom HTML or plain-text emails. When sending a custom email you have the ability to send HTML email or plain-text email or both. To send custom emails you'll need to specify html or text property in the JSON body when making an API request. You can use all UTF-8 characters inside of both fields.

To send custom email with both HTML and plain-text version, it'd look like this:

{
    "toAddress": "user@example.com",
    "subject": "Testing some custom emails :)",
    "html": "<html><body><h1>Hello world! 👋</h1><body></html>",
    "text": "Hello world! 👋"
}

To send only plain-text email don't add the html property, the rest will look the same:

{
    "toAddress": "user@example.com",
    "subject": "Testing plain-text only custom emails :)",
    "text": "Hello world! 👋"
}

Finally, to send only HTML version of your email, specify exclusively the html property. It'd look like this:

{
    "toAddress":  "user@example.com",
    "subject":  "Testing html only custom emails :)",
    "html":  "<html><body><h1>Hello world! 👋</h1><body></html>"
}

API errors

Sidemail uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, or that your request is malformed. Codes in the 5xx range indicate a server error on the Sidemail's side.

Typical error response structure

KeyValue
developerMessageA brief description of the error. Usually contains instruction on how to resolve the issue.
errorCodeAn error code. Search the appropriate section in this API documentation to find out more about the error.
moreInfoA link to the appropriate documentation.

List of errors when sending email via API

  • 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://client.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.