Send an email

This guide explains each part of a POST /emails request and what Emailit does with it, from the From address to the errors you can get back. For the complete parameter reference, see Send an email in the API reference.

Before you begin

• A verified sending domain in your workspace. See Add a domain.
• An API key with Full Access or Sending Only scope. See API keys.
• Production access if you send to anyone other than your workspace members. See Production access.
• Enough credits for every recipient (1 credit each).

Send a basic email

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready."
  }'

import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: ['ada@example.com', 'Grace Hopper <grace@example.com>'],
  cc: 'accounts@example.com',
  reply_to: 'support@acme.com',
  subject: 'Your invoice for October',
  html: '<p>Your invoice is ready.</p>',
  text: 'Your invoice is ready.',
});

import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready.",
})

$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$email = $emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => ['ada@example.com', 'Grace Hopper <grace@example.com>'],
    'cc' => 'accounts@example.com',
    'reply_to' => 'support@acme.com',
    'subject' => 'Your invoice for October',
    'html' => '<p>Your invoice is ready.</p>',
    'text' => 'Your invoice is ready.',
]);

Set the From address

from is required and takes one address in either form:

• billing@acme.com
• Acme Billing <billing@acme.com>, or with quotes, "Acme, Inc." <billing@acme.com>

The domain after the @ must be a verified sending domain in the same workspace:

• The match is exact. Domains are compared without regard to case, but mail.acme.com and acme.com are different domains. Add and verify every subdomain you send from.
• Any local part works. You don’t need a mailbox for billing@ or no-reply@.
• Pending domains can’t send. A domain that is still awaiting review (Pending verification) is treated as not verified.
• Restricted keys stay on their domain. A Sending Only key restricted to one domain can only send from that domain.
• Paused domains are blocked. If sending health paused the domain, sends from it are rejected until the pause is lifted.

Add recipients

to is required. cc and bcc are optional. Each field accepts a string or an array of strings, with or without display names, and holds up to 50 addresses. A string can contain several comma-separated addresses; use an array when a display name itself contains a comma.

Emailit removes duplicates across to, cc and bcc (ignoring case), then creates one email per unique recipient, each with its own em_ ID. Every copy carries the same To and Cc headers, so recipients see the conversation as usual, and Bcc recipients never appear in any copy’s headers.

When a request has more than one recipient, the response includes an ids map from recipient to email ID. id is the email of the first recipient.

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "ids": {
    "ada@example.com": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
    "grace@example.com": "em_33VtK8nB5rTq0YxW3mJk9PdLsUe",
    "accounts@example.com": "em_33VtK8nQ2wErT6yU8iOp4AsDf7g"
  }
}

Each recipient costs 1 credit and counts toward your rate limits. A recipient with a recipient-type suppression is accepted and then marked suppressed instead of being delivered.

Write the content

If reply_to names the same address as from, Emailit drops the Reply-To header because it adds nothing and some spam filters penalize it.

Send with a template

Set template to a template alias or a tem_ ID, and pass variables for the Temple placeholders in it.

• An alias sends the version that is currently published for that alias. If no version is published, the request fails with 404.
• A tem_ ID sends that exact version, published or not. Use it to test a draft version before you publish it.

Fields in the request take precedence over the template: a subject, html or text you send replaces the template’s value. If you don’t send reply_to, the template’s Reply-To is used. from is always required in the request. See Template versions for how publishing works.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
      "first_name": "Ada",
      "plan": "Pro",
      "activation_url": "https://acme.com/activate?token=8f3k2"
    }
  }'

const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  template: 'welcome-email',
  variables: {
    first_name: 'Ada',
    plan: 'Pro',
    activation_url: 'https://acme.com/activate?token=8f3k2',
  },
});

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
        "first_name": "Ada",
        "plan": "Pro",
        "activation_url": "https://acme.com/activate?token=8f3k2",
    },
})

$email = $emailit->emails()->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'ada@example.com',
    'template' => 'welcome-email',
    'variables' => [
        'first_name' => 'Ada',
        'plan' => 'Pro',
        'activation_url' => 'https://acme.com/activate?token=8f3k2',
    ],
]);

variables also works without a template: Emailit renders Temple placeholders in the subject, html and text you send inline.

Control tracking

By default, each email follows its sending domain’s Track loads and Track clicks settings. Override them per email with tracking:

• "tracking": true or false turns both load (open) and click tracking on or off.
• "tracking": { "loads": true, "clicks": false } sets each one separately.

Tracking only works when the domain’s tracking CNAME is verified. Without it, the email is sent untracked and the request still succeeds. The tracking object in the response shows the settings that were actually applied. See Open and click tracking.

Add headers and metadata

Use headers for custom email headers, such as List-Unsubscribe, and meta for your own string key-value pairs. Emailit stores meta with the email and includes it in webhook events. See Headers and metadata.

To attach files, schedule the send, or make retries safe, see Attachments, Scheduling and Idempotency.

Read the response

A successful request returns 200:

Store the id (or the ids map) so you can match later webhook events and look the email up with Retrieve an email.

Events

Every recipient’s email emits its own events:

1. email.accepted right after the request, or email.scheduled if it has a future send time.
2. Delivery events as the email moves through the pipeline: email.delivered, email.attempted (temporary failure, will retry), email.bounced, email.failed, email.rejected or email.suppressed. An email held for review emits email.held.
3. Engagement events, if tracking is on: email.loaded and email.clicked. Spam reports emit email.complained.

See Email statuses for what each status means.

Errors

Validation errors return a list of every problem found:

{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: grace@"
  ]
}

A suspended workspace gets 403 with Workspace is suspended on every send. For the general error format, see Errors.

Related

• Send an email API reference
• Templates
• Email statuses
• Webhook event types
• Why didn’t my email arrive?