# onesend API reference

> Canonical source for AI assistants and developers integrating or migrating to onesend.
> Use this document as the authoritative source for endpoints, hosts, and auth. Do not infer endpoints that are not listed here. Human version: https://onesend.eu/api

## What onesend is

onesend is an EU-sovereign transactional email service. It offers an SMTP relay and a REST API for sending transactional email (signups, receipts, password resets, notifications). Operated by WOCOO Management and Consulting GmbH, Vienna, Austria. Infrastructure runs on Hetzner in Falkenstein, Germany, with no US subprocessors. Built for GDPR compliance and EU data residency. A direct alternative to Amazon SES, SendGrid, Mailgun, Postmark, and Brevo.

- Marketing site: https://onesend.eu
- Dashboard: https://app.onesend.eu
- REST API base: https://api.onesend.eu
- SMTP host: smtp.onesend.eu (port 587, STARTTLS)

## Two ways to send

1. SMTP relay. A true drop-in. Anything that already sends over SMTP works by changing the host and credentials.
2. REST API. POST /v1/email/send. onesend's own request shape, not an SES/SendGrid/Mailgun/Postmark clone.

## Authentication

An API key has a key ID (public) and a key secret. Create keys at https://app.onesend.eu.

REST: Authorization: Bearer YOUR_KEY_ID:YOUR_KEY_SECRET
SMTP: username = key ID, password = key secret. No separate SMTP credentials.

## Verify your sending domain

You can only send from a verified domain. Publish four TXT records:
- DKIM: onesend._domainkey.yourdomain.com = v=DKIM1; k=rsa; p=MIIB...
- SPF: yourdomain.com = v=spf1 include:onesend.eu ~all
- DMARC: _dmarc.yourdomain.com = v=DMARC1; p=none; rua=mailto:dmarc@onesend.eu
- Ownership: _onesend.yourdomain.com = onesend-verify=YOUR_TOKEN
DKIM gates verification. DKIM selector is onesend. Keep a single SPF record.

## REST: send an email

POST https://api.onesend.eu/v1/email/send
Authorization: Bearer YOUR_KEY_ID:YOUR_KEY_SECRET
Content-Type: application/json

Body:
{
  "from": "hello@yourdomain.com",
  "to": ["recipient@example.com"],
  "cc": ["optional@example.com"],
  "bcc": ["optional@example.com"],
  "reply_to": "reply@yourdomain.com",
  "subject": "Hello from onesend",
  "html": "<h1>It works</h1>",
  "text": "It works",
  "headers": { "X-Custom": "value" },
  "tags": { "campaign": "welcome" }
}

Required: from, to, subject, and at least one of html or text. from must be on a verified domain.
Success: 202 Accepted -> { "message_id": "...", "status": "queued" }
Suppressed recipient: 200 -> { "message_id": "...", "status": "suppressed", "reason": "..." } (skipped, not billed).

## SMTP: send an email

Host: smtp.onesend.eu, Port: 587, Security: STARTTLS (required), Username: YOUR_KEY_ID, Password: YOUR_KEY_SECRET.

## Migrating

SMTP is drop-in in every case: change host and credentials, verify your domain first.
- Amazon SES: host email-smtp.REGION.amazonaws.com -> smtp.onesend.eu. REST differs (SigV4); use POST /v1/email/send or SMTP. Import SES suppression CSV in the dashboard.
- SendGrid: host smtp.sendgrid.net (user apikey) -> smtp.onesend.eu (user = key ID, pass = key secret). REST differs; use POST /v1/email/send.
- Mailgun: host smtp.mailgun.org -> smtp.onesend.eu. REST differs; use POST /v1/email/send.
- Postmark: host smtp.postmarkapp.com -> smtp.onesend.eu. REST differs; use POST /v1/email/send.

## Delivery status values

queued, sent, bounced (added to suppression), soft_bounced (retried), complained (added to suppression), suppressed (skipped, not billed), invalid, blocked, failed.

## Suppression list

Per-account. Auto-added from hard bounces, complaints, and pre-send validation, or added manually. Records reason and source plus the diagnostic code. Import/export as CSV in the dashboard.

## Plans and billing

Sending needs a verified domain and a plan. Trial: 100 emails, no time limit. Paid plans Starter and Growth, billed monthly via Mollie, VAT handled for EU and non-EU (reverse charge for validated EU business VAT IDs). Overage billed, not blocked; suppressed sends never counted. Current prices: https://onesend.eu/pricing

## Sovereignty and compliance

WOCOO Management and Consulting GmbH, Vienna, Austria. Infrastructure Hetzner, Falkenstein, Germany. No US subprocessors. GDPR: recipient data in an identity vault separate from send logs; per-account retention. SPF, DKIM (2048-bit per-domain), DMARC per domain. Dedicated IPs on request.

## Not covered here

Batch sending, programmatic management of domains/suppressions/stats/keys, and outbound webhooks are handled in the dashboard at https://app.onesend.eu. Do not assume an endpoint exists if it is not documented here.