Welcome to Mailia

Mailia is an API and dashboard for sending emails. It's built specifically for software developers who need to send automated transactional emails to their users. Mailia combines a simple, no-frills API with a beautiful search page for quickly searching through your email history. We display the rendered HTML and/or text of each email, as well as the raw request payload that was used to send the email. We also provide idempotency in the API by allowing you to supply a unique ID for each email.

Quickstart Guide

Getting started with Mailia is dead simple. There are two steps:

  1. Create an account: On the sign up page, you'll be prompted for an email address, password, and company name. You can start sending emails as soon as your account is created. However, until you have completed the next step, you can only send emails from "testing@mailia.co" to the email address you signed up with.
  2. Verify a domain: To send emails to other people, and to send emails from a domain you own, you need to authorize Mailia to send email from that domain. You'll need access to your domain's DNS records for this part. This process is described in the Verifying a Domain section below. It only takes a few minutes, we promise!

API Overview

Format

The API uses JSON encoded as UTF-8. The body of a POST request must be a JSON object. The Content-Type header should be set to application/json; charset=UTF-8. The body of a response is always a JSON object, with content type application/json; charset=UTF-8.

Authentication

API keys are used for Authentication. They can be generated on the "API keys" tab in the dashboard. The key should be present in the Authorization header with the format Api-Key your-key-here

Error Handling

Whether a request is successful is indicated by the HTTP status code. A 2xx indicated success, whereas a 4xx status code indicates failure. When a request fails, the response body is still JSON, and contains a detail field with a description of the error.

Send Email API

POST https://api.mailia.co/emails

Params

Name Type Description
to_emails list[string] [REQUIRED] The "to" recipients of the email. Must contain at least one email address.
cc_emails list[string] The "cc" recipients of the email.
bcc_emails list[string] The "bcc" recipients of the email.
from_email string [REQUIRED] The email address of the sender.
from_name string The name of the sender.
subject string [REQUIRED] The subject of the email
body_text string [REQUIRED*] The content of the message in text format.
body_html string [REQUIRED*] The content of the message in HTML format.
external_id string A unique key to associated with this email.

* At least one of body_text and body_html are required. If both are included, the text version will be delivered to clients who block HTML content.
* body_text and body_html can be at most 1MB in size.
* Max 50 recipients total can be included across to, cc, and bcc.
* from_email must be under a domain verified with Mailia. Read more about domain verification below.

Errors

Example Request


curl --location --request POST 'https:/api.mailia.co/emails/' \
    --header 'Authorization: Api-Key your-api-key' \
    --header 'Content-Type: application/json' \
    --data-raw '	{
            "to_emails": ["to@example.com"],
            "from_email": "from@example.com",
            "subject": "subject",
            "body_text": "body"
    }'
            

import requests

requests.post(
    "https://api.mailia.co/emails",
    headers={"Authorization": "Api-Key your-api-key"},
    json={
        "to_emails": ["to@example.com"],
        "from_email": "from@example.com",
        "subject": "subject",
        "body_text": "body",
    },
)
            

const fetch = require('node-fetch');

fetch('https://api.mailia.co/emails', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Api-Key your-api-key',
  },
  body: JSON.stringify({
    'to_emails': ['to@example.com'],
    'from_email': 'from@example.com',
    'subject': 'subject',
    'body_text': 'body'
  })
 }).then(res => res.json()).then(json => console.log(json))

            
Response:

{
    "detail": "success"
}
            

Idempotency

We recommend using the external_id param in the send email API to prevent us from processing the same email twice in the event that you accidentally send duplicate HTTP requests. Duplicate requests can occur simply because of a network error between your servers and Mailia's servers, or due to software bug.

The external_id field helps to protect against these events through a uniqueness constraint. If we receive a request to send an email and we already have an email with the same external_id, the API will return a 409.

For example, if you know that you should never send more than one "your order has shipped" email for a given order, you could make the external id order_shipped_12345, where 12345 is the order ID.

External IDs are kept forever. We hope this gives you some piece of mind!

Domains

Verifying a Domain

To send emails from domains you own, you must first authorize Mailia to send emails on behalf of the domain. For example, if you want to send emails from "larry@google.com", you have to verify that you own google.com and authorize Mailia to send email on behalf of google.com.

Domain verification is done using DNS records. Mailia will generate a set of DNS records for you, and you'll have to add them manually to your domain's DNS record set. Once the DNS records are generated, Mailia will start polling for the records. Once the records are found, your domain is marked as verified and you can start sending emails from any address under that domain.

The records allow your emails to comply with an SMTP authorization standard called DKIM (Domain Key Identified Mail). DKIM allows the SMTP clients receiving your mail to verify that the sender is actually who they claim to be.

Sending Email From a Domain

After a domain has been verified, you can send email from any address associated with that domain, or a subdomain. For example, if you have verified the domain "google.com", you can send email from "larry@google.com", or "larry@subdomain.google.com".

How it Works

SPF & DKIM

Mailia uses Amazon SES under the hood. SPF is enabled by default, and we add DKIM through the DNS records we provide to you in the domain verification process.

Asynchronous Sending

When we receive a request to send an email, the payload is validated and then the request is put on a queue for delivery. For this reason, there may be a short delay between us receiving your request and the email being delivered. Queued email are visible immediately in the search page on the dashboard, and are marked as "queued".

At Least Once delivery

An email will be delivered to recipients at least once. Exactly once delivery is very challenging and expensive to implement in a distributed system. In practice, multiple deliveries of the same email should only occur in rare cases. All email providers I am aware of work this way.

Billing

Mailia costs $10 per 10,000 emails per month, billed at the end of each month. The first 1000 emails you send each month are free. If you send less than 1000 emails per month, you don't even need a credit card. We use Stripe for billing, and don't store any sensitive billing information on our servers.

Each successful API request (200 response) you make to the send-email API counts towards your metered usage. If you include multiple recipients in the to_emails, cc_emails, and bcc_emails fields in the same request, this still only counts as 1 email.

If you exceed 1000 emails in a given month and you don't have a valid payment method, We reserve the right to suspend your API usage. But don't worry, we'll give you plenty of warning before this happens.

Limitations

The following features are currently not supported: