Before you start
Request access, verify a sender address, and create a key with only the scopes your server needs. The public browser must never hold a CPaaS API key. Each product and environment gets its own tenant and key.
Send an email
Use POST /v1/emails with an Idempotency-Key of 8–128 characters. Reuse the same key only for the same request. A repeated request returns the original message; a changed request returns 409.
curl https://cpaas.grasany.com/v1/emails \
-H "Authorization: Bearer $CPAAS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_1042_receipt" \
-d '{"from":"[email protected]","to":"[email protected]",
"subject":"Your receipt","text":"Thank you for your order."}'Successful queueing returns 202 and a message ID. A same-key replay returns 200 with the same ID.
Check status
curl https://cpaas.grasany.com/v1/emails/{message_id} \
-H "Authorization: Bearer $CPAAS_API_KEY"The response is scoped to the key's tenant. Another tenant's message ID returns 404.
Read usage
curl https://cpaas.grasany.com/v1/usage \
-H "Authorization: Bearer $CPAAS_API_KEY"The rolling 24-hour response reports request and outcome counts. It is operational visibility, not an invoice or wallet debit.
Understand states
| State | Meaning |
|---|---|
| queued | Saved for worker processing. |
| sending | Claimed by a worker; a provider result is pending. |
| accepted | The provider accepted the request. Inbox delivery is not yet proven. |
| rejected | The provider rejected it, or suppression prevented dispatch. |
| unknown | The provider outcome is ambiguous and is not automatically retried. |
Errors and retries
Retry only with the same idempotency key and same payload. Do not create a fresh key after a timeout until the original result is reconciled; doing so could send twice. Sending is limited to verified senders and unsuppressed recipients. Expect 401 for invalid keys, 403 for missing scopes or sender/suppression checks, 409 for a changed replay, and 429 for the tenant limit.
For account setup or migration support, contact Grasany →