REST API · v1

API documentation

Connect one or more SMTP senders, then send transactional email from any application through a stable HTTPS contract. This guide covers setup, authentication, requests, errors, rotation, and operational safety.

Base URL

https://your-domain.com

Endpoint

POST /api/v1/emails

Authentication

Bearer API key

Start here

Quickstart

Complete these steps in order. The full setup normally takes only a few minutes.

Create a workspace

Connect an SMTP sender

Add Gmail, Workspace, Outlook, or custom SMTP credentials and verify the connection.

Create an API key

Copy the secret immediately and store it outside your source code.

Google app passwords

Your Google account must have two-step verification enabled before Google exposes app passwords. Never enter your normal Google password into easymail.

Identity

Authentication

Every email request requires an organization-owned API key. Dashboard session cookies are never accepted by the public email endpoint.

Authorization: Bearer gms_your_secret_key

You may alternatively send the same secret in the x-api-key header. Bearer authentication is recommended because it works consistently with proxies and standard HTTP clients.

Keys are shown once

easymail stores a hash, not the original secret. If a key is lost, create or rotate it instead of trying to recover it.

Endpoint

Send an email

Send JSON to POST /api/v1/emails. The configured workspace sender controls the From address.

curl https://your-domain.com/api/v1/emails \
  -H "Authorization: Bearer $EASYMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-order-9382" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your receipt",
    "text": "Thanks for your order."
  }'

Successful SMTP acceptance

A new send returns 201 Created. Replaying the same idempotency key returns the original record with 200 OK and duplicate: true.

Schema

Request fields

Unknown fields are rejected, preventing accidental From-address spoofing or unsupported Nodemailer options.

Field	Type	Requirement	Description
senderId	UUID	Optional	Use a specific verified SMTP sender. The workspace default is used when omitted.
to	string \| string[]	Required	One address or an array of up to 50 valid email addresses.
subject	string	Required	Message subject between 1 and 200 characters.
text	string	Conditional	Plain-text body. Either text or html must be present.
html	string	Conditional	HTML body. Either html or text must be present.
cc	string[]	Optional	Up to 20 carbon-copy recipients.
bcc	string[]	Optional	Up to 20 blind-carbon-copy recipients.
replyTo	string	Optional	Address that receives replies.

Safe retries

Idempotency

Use a stable Idempotency-Key whenever your application might retry a send after a timeout or temporary network failure.

Idempotency-Key: order-9382-receipt

Good keys

Use a business event identifier such as password-reset-user-42-attempt-1.

Scope

Keys are unique within a workspace and may contain up to 200 characters.

Contract

Success responses

Responses include the delivery record and a request ID for tracing.

{
  "data": {
    "id": "44df90ce-...",
    "status": "sent",
    "messageId": "<provider-message-id@gmail.com>",
    "accepted": ["customer@example.com"],
    "rejected": [],
    "duplicate": false
  },
  "requestId": "12d4139c-..."
}

The same request ID is also returned in the x-request-id response header.

Check request status

Call GET /api/v1/emails/{id} with the same API-key header. A status of accepted means the SMTP provider accepted at least one recipient; it does not guarantee inbox placement or that the recipient opened the message.

curl https://your-domain.com/api/v1/emails/44df90ce-... \
  -H "Authorization: Bearer $EASYMAIL_API_KEY"

Recovery

Errors

Error codes are stable and safe to use in application logic. Human messages may become clearer over time.

Status	Code	Meaning
400	INVALID_JSON	The request body is not valid JSON.
401	API_KEY_REQUIRED	No API key was supplied.
401	INVALID_API_KEY	The key is invalid, revoked, or expired.
409	SMTP_NOT_CONFIGURED	The workspace has no matching SMTP sender.
413	PAYLOAD_TOO_LARGE	The request exceeds 256 KB.
415	UNSUPPORTED_MEDIA_TYPE	Content-Type is not application/json.
422	VALIDATION_ERROR	One or more request fields are invalid.
502	DELIVERY_FAILED	The SMTP provider did not accept the message.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key is invalid or expired",
    "requestId": "12d4139c-..."
  }
}

Boundaries

Limits and timeouts

These defaults keep delivery predictable and protect every workspace from accidental overload.

Request body

256 KB

To recipients

CC / BCC

20 each

Default rate

60 / minute

The endpoint has a 30-second execution budget. Treat 502 responses and client-side timeouts as retryable only when you also supplied an idempotency key.

Credential lifecycle

Rotate an API key

Rotation creates a replacement and revokes the selected key. Plan the change so applications do not lose access.

1
Open Dashboard → API keys and identify the key used by your application.
2
Select Rotate, then immediately copy the replacement secret.
3
Update the secret in your deployment platform or secret manager.
4
Redeploy or restart the application and verify a test email.

The old key stops working

Current rotation revokes the previous key immediately. For zero-downtime changes, create a second key manually, deploy it, verify it, and then revoke the old key.

Operations

Security guidance

easymail protects credentials at the platform boundary, while your application must protect its API key.

Keep API keys in a managed secret store, never source control.

Use separate keys for development, staging, and production.

Rotate immediately after suspected exposure or staff changes.

Never log Authorization, x-api-key, or SMTP passwords.

Use idempotency keys for user-visible or financial messages.

Review provider activity and rotate unused SMTP credentials.

Help

Troubleshooting

Start with the response code and request ID, then work through the matching check.

SMTP_NOT_CONFIGURED

Connect a verified SMTP sender in the active workspace, or check senderId.

DELIVERY_FAILED

Confirm the SMTP host, port, security mode, username, and password are current.

INVALID_API_KEY

Confirm the complete secret is deployed without whitespace and has not been rotated.

Duplicate response

Your Idempotency-Key was already used. Generate a new key only for a genuinely new email event.

Client timeout

Retry with the same Idempotency-Key, then use the returned request ID for investigation.