Send emails

Send an email with a single POST /emails request. usend validates it, stores it and queues it for delivery, then returns its ID.

curl -X POST https://api.usend.et/emails \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Your order has shipped",
    "html": "<p>Your order <strong>#1042</strong> is on its way.</p>",
    "text": "Your order #1042 is on its way."
  }'

import { Usend } from '@usend/node';

const usend = new Usend(process.env.USEND_API_KEY);

const { data, error } = await usend.emails.send({
  from: 'Acme <[email protected]>',
  to: ['[email protected]'],
  subject: 'Your order has shipped',
  html: '<p>Your order <strong>#1042</strong> is on its way.</p>',
  text: 'Your order #1042 is on its way.',
});

import os
from usend import Usend

usend = Usend(os.environ["USEND_API_KEY"])

email = usend.emails.send({
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Your order has shipped",
    "html": "<p>Your order <strong>#1042</strong> is on its way.</p>",
    "text": "Your order #1042 is on its way.",
})

{ "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }

A 200 response means the email was accepted and queued, not yet delivered. Follow its progress with webhooks or GET /emails/{id}.

#Sender

from accepts [email protected] or Name <[email protected]>. The address must be on a verified domain of your organization, or on a subdomain of one: when acme.com is verified you can also send from [email protected]. Otherwise the request fails with 403:

{
  "statusCode": 403,
  "name": "forbidden",
  "message": "The acme.com domain is not verified. Please add and verify your domain."
}

#Recipients

Each address may include a display name (Ann <[email protected]>). An email can have at most 50 recipients across to, cc and bcc together. To reach more people, use batch sending or broadcasts.

Recipients on your suppression list are skipped at send time.

#Content

At least one of html or text is required. Send both when you can: some clients show only plain text, and spam filters like to see it.

Instead of html and text, you can reference a published template.

#Custom headers

Add headers with the headers object:

{
  "headers": {
    "X-Entity-Ref-ID": "order-1042"
  }
}

Headers usend sets itself cannot be overridden: From, To, Cc, Bcc, Subject, Date, Message-ID, MIME-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received and Sender. Sending one of them fails with 422 validation_error.

#Tags

Tags are name/value pairs attached to an email. They are returned by the API and included in every webhook event for the email, so you can link events back to your own records.

{
  "tags": [
    { "name": "category", "value": "order_shipped" },
    { "name": "order_id", "value": "1042" }
  ]
}

Names and values may contain only ASCII letters, numbers, underscores and dashes, up to 256 characters each.

#More options

#Email status

GET /emails/{id} returns the email with its latest status in last_event:

last_event never moves backwards to a less important event: an opened that arrives after a bounced does not hide the bounce. For the full history, call GET /emails/{id}/events.

See the Emails API reference for every field.