API Overview

SendMero accepts email two ways: a REST API that takes a JSON request, and SMTP for apps and plugins that already send mail that way. Both use the same workspace API key and verified sending domain, and both go through the same checks, limits and credits. Use the result to track whether the submission was accepted for processing.

Preview availability

These guides describe the current implemented email submission API. A public endpoint and integrated email delivery have not been released. Your administrator must provide an enabled test endpoint and activate your workspace's current configuration before you can try it.

Choose how to send

	REST API	SMTP
Best for	New code that can make HTTP requests	Existing apps, frameworks and plugins that already send over SMTP
Connect to	https://api.sendmero.com/v1/messages	smtp.sendmero.com, ports 587 or 2587 (STARTTLS), 465 or 2465 (SSL/TLS)
Login	Authorization: Bearer YOUR_API_KEY	Username sendmero, password your API key
Request	JSON body	A normal email message
Result	JSON with a message ID	A 250 reply that ends queued as msg_…
Errors	error.code and an HTTP status	SMTP reply codes
metadata	Yes, in the body	Yes, in the X-SendMero-Metadata header
Test mode	Yes	No
Custom headers	Any header that is not reserved	List-* and X- headers
Sender domain, limits and credits	Same	Same

Both integrations use the same API key, so you can start with one and add the other later. See Authentication.

REST API endpoints

Method and path	Purpose	Response
POST /v1/messages	Submit one email, or validate it with test mode.	HTTP 200 with a message ID, recipient IDs, and accepted or validated status.
GET /v1/auth/verify	Check that an API key is valid, without sending email.	HTTP 200 with status: "valid", or 401 for a missing or invalid key.
GET /health	Check process liveness.	HTTP 200; this does not establish sending or delivery readiness.
POST /v1/messages.mime	Reserved raw MIME path; sending is unavailable.	Always HTTP 422 feature_not_available.

JSON submission requires Bearer authentication. There is no message-status lookup endpoint. Keep the original submission response and its IDs; use Submission Outcomes to interpret the result.

The API base URL is https://api.sendmero.com. Examples use the complete endpoint URL directly. Replace YOUR_API_KEY with your full workspace API key, including its live_ prefix, and run requests from your backend.

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

SMTP settings

Setting	Value
Host	smtp.sendmero.com
Port with STARTTLS	587 (or 2587)
Port with SSL/TLS	465 (or 2465)
Username	sendmero
Password	Your API key, including its live_ prefix

See SMTP for language examples, how a message is read, limits and reply codes.

Prepare your workspace

1. Select the workspace that owns your sending domain.
2. Create an API Key under Credentials, or reuse an existing active key from that workspace. The same key works for both the REST API and SMTP. See Authentication.
3. Add and verify the exact sender domain in the dashboard. For example, hello@example.com requires example.com; verification of that domain does not automatically allow mail.example.com.
4. Ask your administrator to confirm that your key, sending permissions, domain readiness, and recipient allowance are active on the enabled endpoint. Dashboard changes are not yet automatically synchronized with the submission API.
5. For the REST API, follow Test Mode to validate a request before enabling real submissions. For SMTP, send a test email to an address you own.

Start with test mode

Send this body to POST /v1/messages, replacing the sender with an address on your configured domain and the recipient with your test address:

{
  "from": "Example App <hello@example.com>",
  "to": ["recipient@example.net"],
  "subject": "Welcome to Example App",
  "text": "Thanks for signing up. Your account is ready.",
  "options": { "test_mode": true }
}

A successful test returns HTTP 200 with status: "validated". Test mode checks the request, credentials, and sender readiness without creating a production queue job or using the daily recipient allowance. It still counts toward the request-rate limit.

When production sending is enabled and you want to submit a real email, omit test_mode or set it to false. This creates a separate production submission with new message and recipient IDs.

Follow Test Mode for the full testing workflow. The Send Email reference provides read-only request examples in six languages, request fields, and submission response formats. File encoding and inline content examples are in Attachments & Inline Images.

What happens to a request

For a new email submission, the API (and for SMTP, the SMTP gateway that turns each message into the same submission):

1. Checks the request headers, API key, and workspace request rate.
2. Reads the bounded JSON body and validates required fields, addresses, attachments, and supported options.
3. Checks the sender domain, sending permissions, daily recipient allowance.
4. For production submissions, confirms that the email has been queued and saves its acceptance record before returning success. Test mode returns a validation result without creating a production send.

Every POST is an independent request. Repeating the same content can create another email with fresh message and recipient IDs and its own production recipient charge. The API does not prevent duplicate submissions. See Rate Limits & Retries before repeating a request after a timeout or uncertain outcome.

accepted confirms queued processing, not delivery. The current implementation ends at submission and queue acceptance. It does not yet provide integrated email delivery, delivery receipts, opens, clicks, or bounce reporting.

Limits to plan for

Limit	Current behavior
Request rate	Default 1,000 requests per 10 seconds per workspace (100/second on average), shared across its API keys in each Cloudflare location. Approximate window; bursts allowed.
Daily recipient allowance	Configured per workspace and reset at the start of each UTC day.
JSON body	At most 1,000,000 UTF-8 bytes, including JSON syntax, escaping, and Base64 attachment content.
Recipients	At most 100 supplied entries across to, cc, and bcc combined.

Test requests and repeated POSTs use the same request-rate budget. See Rate Limits & Retries for counting rules, response headers, and retry delays.

Supported message content

Each request describes one email with a shared subject and body. You can include plain text, HTML, reply-to addresses, Cc/Bcc recipients, embedded Base64 attachments, permitted custom headers, tags, and string-valued metadata.

Raw MIME submission, templates, scheduling, and batches of independent emails are not enabled. SMTP sends plain, HTML and attachment content too, and takes metadata in a header; see SMTP. Unknown request fields are rejected. Use the documented contract rather than another provider's SDK or request format.

Continue your integration

• Authentication — obtain an API key and connect it to the correct workspace.
• SMTP — connection settings, language examples, limits and reply codes.
• Send Email — build a request and interpret its result.
• Attachments & Inline Images — encode file content and reference inline images.
• Test Mode — validate a message before submitting a production email.
• Submission Outcomes — interpret the POST result and handle uncertain acceptance.
• Rate Limits & Retries — manage throughput, recipient allowance, and repeated attempts.
• Error Codes — handle validation failures, rejected senders, and temporary errors.