Skip to main content
An API key lets an app send email as your account. The REST API takes it as a Bearer token, and SMTP takes it as the password. Give each app its own key, so you can stop one without touching the others.

​
Environments

Only a production key delivers. A simulated send runs the same checks as a real one (the key, a verified domain, the rate limit), is recorded with the status simulated, and gets a normal answer. It does not count against your monthly emails. Use test keys for local development, CI and preview builds.
Read the key from an environment variable, such as HIVEKU_EMAIL_API_KEY. Give development and preview environments a test key, and production a production key.

​
Create a key

1

Open API Keys

Go to Settings > API Keys and click Create API Key.
2

Name it and pick the environment

Name the key after the app that uses it. Choose Test or Production.
3

Pick permissions

Send Emails is selected. Add others only if the app needs them. See Permissions.
4

Copy the key

Click Copy key and store it in your secret manager or the app’s environment. It is shown only this once.
The full key is shown once, when you create it. After that Hiveku shows only a short preview. If you lose a key, create a new one and delete the old one.
Your plan sets how fast every key may send. A key can also have limits of its own, set on its page, which can only lower its rate. See Limits.
Create API Key on Settings > Email Service > API Keys is a shortcut: it makes a production key that can send, with a name and nothing else to choose.

​
Permissions

Keep keys send-only unless the app must read emails back. A key with Read Emails hands every sign-in and password-reset link it sent to whoever holds it.

​
Allowed domains

A key can be limited to some of your verified domains. It then refuses any other from domain with 403 domain_not_allowed, over the API and SMTP alike. An entry such as *.acme.com allows acme.com and every subdomain of it. A key without a list may send from every verified domain of the account. The key’s page shows its list under Sends from. Keys made in the dashboard send from every verified domain. To limit a key, ask your AI assistant to create one for the domains you name.

​
Allowed IP addresses

A key can be limited to the addresses your servers send from. A call with it from any other address is refused with 403 ip_not_allowed, and the message names the key and the address the call came from. List up to 50 public IPv4 or IPv6 addresses or ranges on the key’s page, under Allowed addresses, one per line. A key without a list works from any address. Private and local addresses are refused, since a call over the internet never comes from one, and so is an address that many businesses share, such as Hiveku’s own servers or an edge network’s.
A key with allowed addresses cannot send over SMTP: the SMTP server cannot see the address a connection comes from yet, so it refuses such a key at sign-in. It does not work in a workflow’s Email Notification step either, which sends from Hiveku’s own servers. Use a key without allowed addresses for those.

​
Limits

Each key’s rate and the account’s monthly emails follow your plan. Settings > Email Service > Overview shows the numbers for your account.
  • Both count recipients: an email to three people counts three, across to, cc and bcc.
  • A minute allows 60 times the per-second number.
  • The month is the calendar month in UTC, and covers every email sent with an API key: the REST API, the Resend-compatible API and SMTP.
  • Past the monthly number, an account that pays for Starter, Standard or Premium keeps sending. Each 1,000 emails past it is billed at $0.20 on the next invoice, up to 4 times the number, where sending pauses until the 1st. Free accounts, and accounts that do not pay for their plan, stop at the number until the 1st.
  • Simulated sends from test keys are not counted.
A send that a limit refuses answers 429, with a Retry-After header and a retry_after field in seconds when waiting helps:

​
A key’s own limits

A key can have a limit of its own a second and a day, set on its page. They can only lower the plan’s rate. Once a key has sent to its own number of recipients in a second, or 60 times that in a minute, its next sends are refused with 429 rate_limit_exceeded until that second or minute passes. One send to more recipients than 60 times its limit a second, such as a large batch, is refused whole with 429 rate_limit_exceeded and no Retry-After: split it into smaller sends. A key with 500 a day stops for the day at 500 recipients, until 00:00 UTC. A test key’s simulated sends do not count toward its daily limit. A new key has no limit of its own.

​
Daily volume check

A leaked key sends far more in a day than your app ever does. So when a day’s API mail passes 5 times your usual day, and also passes what one key may send in a minute on your plan, Hiveku holds all of the account’s API mail until 00:00 UTC. API mail means the REST API, the Resend-compatible API and SMTP. Your usual day is the average of the days with API mail in the last 30 days, not counting today. With fewer than 7 such days, or a usual day under about 3 emails, there is no usual day yet, and nothing is held. Nothing lifts a hold early. If the mail is yours, send it again after 00:00 UTC. If it is not, pause the key at once.

​
Domains and keys

Past them, adding a domain or making a key answers 403 quota_exceeded, with the same message in the dashboard, through your AI assistant and through the API. Only the keys you make count: a deleted key does not, and neither do the keys made for a site’s email or the Auth SMTP (auto) key that a database’s sign-in email setup makes.

​
Pause or delete a key

Open the key from Settings > API Keys.
  • Pause switches the key off, and its status reads Paused. Every request with it is refused, over the API and SMTP, until you click Resume.
  • Delete ends the key for good. It cannot be turned back on. The emails it sent stay in the logs, and stay counted in the month’s usage and on the invoice.
The API Keys tab of Settings > Email Service lists the same keys, in the same columns, as Settings > API Keys, with buttons to open and delete each one.

​
The key’s page

It shows the key’s status and environment, the emails it sent today and this month, when it was last used, the domains it may send from, your plan’s rate with the key’s own limits and what applies, and its allowed addresses. You can rename the key and change its permissions, its own limits and its allowed addresses there. To change its environment or domains, create a new key.

​
Authentication

Send the key as a Bearer token:
A wrong, paused or deleted key is refused with 401. A key used from an address it does not allow is refused with 403 ip_not_allowed. Over SMTP, the username is apikey and the password is the key.