API reference

The usend API is a REST API with JSON request and response bodies.

#Base URL

https://api.usend.et

All requests must use HTTPS.

#Authentication

Authenticate with an API key in the Authorization header:

curl https://api.usend.et/domains \
  -H "Authorization: Bearer us_123456789"

sending_access keys can call only POST /emails and POST /emails/batch. Every other endpoint needs a full_access key.

#Requests

• Send JSON bodies with Content-Type: application/json.
• IDs are UUID strings, for example 4ef9a417-02e9-4d39-ad75-9611e0fcc33c.
• Timestamps are RFC 3339 strings in UTC, for example 2026-10-11T09:12:43Z.
• Request bodies can be up to 50 MB.

#Responses

Successful requests return 200 with a JSON body. Single resources usually include an object field naming their type (email, domain, template...). Lists look like this:

{
  "object": "list",
  "data": [],
  "has_more": false
}

has_more is present on paginated lists.

Errors return a non-2xx status with an error object:

{ "statusCode": 422, "name": "validation_error", "message": "The `to` field is required." }

#SDKs

usend has official SDKs for Node.js and Python, both published as usend:

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

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

# pip install usend
import os
from usend import Usend

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

Both SDKs read the API key from USEND_API_KEY when you don't pass one, and the base URL from USEND_BASE_URL (default https://api.usend.et). Node.js methods return { data, error }; Python methods return dicts and raise UsendError on failure. In other languages, use your HTTP client of choice: the examples in this reference use cURL.

#Endpoints