Why does my key return 403 forbidden?

The three scopes do not nest. A read key reads, and it also manages mailbox state: it can create and delete a label, and move, star or mark a thread. A send key sends a message and cancels a scheduled message. An admin key does both, and it also manages keys, domains, inbound routes, suppressions, billing and spend caps. Treat a read key as read plus mailbox organization, not as read-only.

I lost my API key. Can I read it again?

No. Sendara returns the plaintext secret exactly once, at creation. Store it at that moment. To recover, rotate the key. A rotation issues a new secret and invalidates the old one.

How do I simulate a bounce or a complaint?

Use a test key, and let the local part of the recipient address choose the outcome. An address at bounced@ or bounce@ produces a bounce. An address at complained@ or complaint@ produces a complaint. Every other address produces a delivery.

Sendara is one platform for everything you send

Sendara authenticates a request with an API key. Send the key as a Bearer token in the Authorization header. A request without a valid key returns 401 unauthorized.

Authorization: Bearer sk_live_xxx

Treat a key as a password. Never commit a key. Never put a key in client-side code. Send every API call from your backend.

The 3 scopes

Every key carries exactly one scope. Issue the narrowest scope that the service needs.

send. The key sends a message, and it cancels a scheduled message. The scopes do not nest. A send key cannot call a read-only route. Use a read key or an admin key for a read.
read. The key reads messages, events, usage and inbound mail. It also lists suppressions.
admin. The key sends and reads. It also manages API keys, domains, inbound routes, billing, suppressions and spend caps.

A request with a key that does not carry the required scope returns 403 forbidden.

An administrative action needs a key with the admin scope. These actions need admin: create, rotate or revoke an API key; add or remove a domain; manage an inbound route; add, import or delete a suppression; start a billing checkout; set a spend cap. A read key lists messages, events, usage, suppressions, domains and templates, and it also organizes a mailbox: it can create and delete a label, and move, star or mark a thread. Treat a read key as read plus mailbox organization, not as read-only. Issue an admin key only to the backend that manages your account. Keep your daily sending on a send key.

The live mode and the test mode

A key runs in one of two modes. A live key (sk_live_…) sends a real message, and Sendara bills it. A test key (sk_test_…) simulates the delivery. Sendara calls no provider and bills nothing. Sendara still writes the events and calls your webhooks, so your handlers run.

In the test mode the local part of the recipient address selects the simulated outcome. A send to bounced@… or bounce@… produces a bounce. A send to complained@… or complaint@… produces a complaint. Every other address produces a delivery.

Build your send flow and your webhook flow with a test key. Then replace the secret with sk_live_… in production.

Create & rotate a key

Create a key in the dashboard, or over the API with an admin key. Sendara returns the plaintext secret exactly once, at creation. Store it at that moment.

curl https://api.sendara.dev/v1/keys \
  -H "Authorization: Bearer sk_live_admin_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "send", "test_mode": false }'

Rotate a key to issue a new secret and to invalidate the old secret. Revoke a key to disable it. See the API keys reference.

Common questions

Why does my key return 403 forbidden?: The three scopes do not nest. A read key reads, and it also manages mailbox state: it can create and delete a label, and move, star or mark a thread. A send key sends a message and cancels a scheduled message. An admin key does both, and it also manages keys, domains, inbound routes, suppressions, billing and spend caps. Treat a read key as read plus mailbox organization, not as read-only.
I lost my API key. Can I read it again?: No. Sendara returns the plaintext secret exactly once, at creation. Store it at that moment. To recover, rotate the key. A rotation issues a new secret and invalidates the old one.
Does a test key reach Amazon SES?: No. A test key (sk_test_) simulates the delivery. Sendara calls no provider and bills nothing. Sendara still writes the events and sends real signed webhook requests, so your handlers run end to end.
How do I simulate a bounce or a complaint?: Use a test key, and let the local part of the recipient address choose the outcome. An address at bounced@ or bounce@ produces a bounce. An address at complained@ or complaint@ produces a complaint. Every other address produces a delivery.