Authentication

Authenticate email submissions with an API key from your SendMero workspace. Send the complete key in the HTTP Authorization header:

Authorization: Bearer YOUR_API_KEY

The key identifies your workspace. You do not supply a workspace ID, username, or dashboard session token in the request. The same API key is also your password for SMTP.

Activate the current configuration

The submission API is an unreleased preview. Intake remains disabled while trusted configuration provisioning and delivery integration are unfinished. An enabled endpoint requires your workspace's current API keys and sending configuration; no customer setup endpoint is available. Creating, rotating, or revoking a key in the dashboard does not yet automatically synchronize that change with the API.

Get your API key

1. Sign in to the SendMero dashboard and select the workspace you want to send from.
2. Open Credentials (the page is titled API Keys) and choose Create credential. If you cannot create credentials, ask a workspace administrator with the required permission.
3. Enter a recognizable name, such as Production backend.
4. Choose Never expires, 6 months, or 1 year, then select Create.
5. Copy the full secret from Save this secret now into your backend's secrets manager or environment configuration. The secret is shown once and cannot be retrieved later; the identifier shown in the credential list is only a prefix.
6. Ask your administrator to activate the current workspace configuration on the endpoint you will use. An existing active API key can also be reused after this step.

Issued keys contain live_ followed by 64 hexadecimal characters. Copy the full value exactly as issued. A workspace can have multiple active keys; they all share that workspace's request-rate limit and daily recipient allowance. Creating more keys does not increase those limits.

Use the key

Examples call https://api.sendmero.com directly. Replace YOUR_API_KEY in the Bearer header with your full workspace API key, including its live_ prefix. Run requests from your backend and keep the real key in backend configuration or a secrets manager.

This test-mode request demonstrates the headers. Replace the sender with an address on your verified domain and the recipient with your test address:

curl --request POST 'https://api.sendmero.com/v1/messages' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "from": "hello@example.com",
    "to": "recipient@example.net",
    "subject": "Check my API connection",
    "text": "This request checks my configured email submission access.",
    "options": { "test_mode": true }
  }'

Each POST creates a separate submission. Repeating this test does not send production email, but it uses another request slot and returns fresh IDs when validation succeeds. The Send Email reference explains all supported fields.

The API currently provides no message-status lookup. Retain the POST response and any returned IDs for your records.

Use the key for SMTP

The same key authenticates SMTP. Connect to smtp.sendmero.com with the username sendmero and your complete API key, including its live_ prefix, as the password. There is no separate SMTP credential. Over SMTP the key is checked when a message is sent, not when you connect; a wrong key gets a 535 reply to the first message. See SMTP for ports, TLS and examples.

Verify your API key

Call GET /v1/auth/verify to check a key without sending email. It runs the same key check as a send request, but needs no request body and creates no submission. Use it to confirm a new or rotated key before switching your backend over, or to test the connection from a tool that sends through SendMero.

curl 'https://api.sendmero.com/v1/auth/verify' \
  --header 'Authorization: Bearer YOUR_API_KEY'

A valid, active, unexpired key returns HTTP 200:

{ "status": "valid" }

A missing key returns 401 missing_api_key, and an unknown, revoked, or expired key returns 401 invalid_api_key. See Authentication errors.

This endpoint checks the key only. It doesn't check your sender domain, sending permissions, or recipient allowance; those are checked when you send.

What the API validates

For an authenticated operation, the API checks that the supplied key matches a currently active, unexpired API key in the workspace's current private configuration. If that configuration is missing, expired, or unavailable, the API can return 503 service_unavailable because it cannot reliably confirm authorization.

For a new submission, the API also checks that the exact from domain belongs to the same workspace, has completed verification, permits sending, and is ready to use. A valid key alone does not authorize an unverified or disabled sender. Domain verification in the dashboard must also be reflected in the configuration active on the API endpoint.

A send request first checks its headers, body size, JSON, and email fields. If any of those are invalid, you receive that validation error before an API-key error. A valid message then goes through API-key and workspace request-rate checks, followed by sending-domain checks. Test mode follows the same validation, authentication, and sender-readiness rules as a production submission.

Rotate or revoke a key

Use the actions in API Keys:

• Rotate replaces the secret for that credential while keeping its name, ID, and expiry. Save the new secret immediately; it is displayed once. Coordinate the backend update with your administrator and verify that the changed configuration is active. The API does not provide a rotation grace period after that updated configuration becomes active.
• Revoke marks that credential as revoked. Have your administrator arrange the updated configuration and confirm that the API rejects the old key before enabling intake. Other active keys in the workspace are separate credentials.

Do not treat a dashboard success message as proof that the live API has applied a change. This preview requires administrator coordination for key activation, rotation, and revocation. If you suspect exposure, ask the administrator to disable the affected key promptly and verify the change at the API endpoint.

Authentication errors

HTTP	Code	Meaning and next step
401	missing_api_key	The authorization header is absent. Add Authorization: Bearer followed by the full API key.
401	invalid_api_key	The supplied credential is malformed, unknown, inactive, expired, or does not match the active configuration. Check the complete secret and ask your administrator to verify its activation.
503	service_unavailable	The endpoint or current authorization configuration is unavailable. Inspect submission acceptance before trying another POST. Follow Retry-After for a known rejection; contact your administrator if the outcome is uncertain or the problem persists.
429	rate_limit_exceeded	A request-rate or traffic-protection limit rejected the request. Follow Retry-After before trying again.

For example, an otherwise valid submission without an Authorization header, on an enabled endpoint with available dependencies and within its IP traffic limit, returns HTTP 401:

{
  "error": {
    "code": "missing_api_key",
    "message": "Supply a Bearer API key.",
    "retryable": false,
    "request_id": "req_00000000000000000000000000000001",
    "acceptance": "not_accepted"
  }
}

The response includes WWW-Authenticate: Bearer and X-Request-Id. Match on the lowercase error code, not the human-readable message. Include the request ID when reporting a problem, and keep your API key out of the report.

Submission errors include an acceptance field. Acceptance describes only the current POST. A later failure does not cancel an earlier request. If an earlier production outcome is uncertain, retain the available message/request IDs and contact your administrator before submitting again; there is no status lookup. See Error Codes and Rate Limits & Retries.

Keep credentials private

Store API keys only in backend configuration or a secrets manager. Use HTTPS, and keep secrets out of source control, request URLs, logs, screenshots, browser code, and mobile app bundles. A website or mobile app should call your backend, which adds the API key when it calls SendMero.

Only the full API key belongs in the Bearer header. A displayed prefix or dashboard login token cannot replace it.

Continue your integration

• Send Email — submit a test request and read the response.
• Test Mode — validate your integration before a production submission.
• Submission Outcomes — interpret accepted, validated, and uncertain results.
• Rate Limits & Retries — share the workspace limits across your applications.
• Error Codes — distinguish authentication, sender, validation, and service failures.