Skip to content
Invitation-only alpha. Features and limits may change as we learn from testing.

API keys and SMTP credentials

Your application authenticates with a credential. There are two kinds:

Kind Used for Scopes
API key https://api.weneed.email Send only, or send, read email metadata and read usage
SMTP credential smtp.weneed.email Send only. A username starting with smtp_ and a password

A credential lets your application connect. It doesn’t allow sending by itself: messages still need the project’s sending permission. Eligible invited accounts receive this automatically when setup is ready. See How sending becomes available.

Open your project, then API keys & SMTP, then Create API key or Create SMTP login. You need a verified domain first.

Enter your exact sender address. When there is one domain and one stream, Control selects them automatically. The label is prefilled and can be changed. Advanced settings contains optional expiry (no expiry by default; 7, 30 or 90 days for temporary access) and API permissions: send only, or also read status and usage.

Creating a credential asks for your authenticator code. The secret is shown once. Copy it straight into your secret manager before you leave the page; a reload or a later lookup shows only the credential’s details, never the secret.

If the response gets lost while you create one, use Check request result instead of submitting the form again. That way you don’t end up with two credentials.

  • Each credential sends from exactly one address. There are no wildcard senders.
  • An organization can have up to 20 active credentials, API and SMTP together.
  • Keys and passwords do not expire by default. Rotate or revoke them when needed. If you choose a temporary expiry, replace the credential before that date.

Use this when you want to rotate a key or password, or before a temporary credential expires.

  1. On the credential card, select Replace API key or Replace SMTP login. The form is prefilled from the old one.
  2. Create the replacement and store its secret.
  3. Switch your application to it and confirm messages are accepted.
  4. Revoke the old credential.

Until you revoke the old one, both work and both count toward the limit of 20. If you’re at the limit, revoke an unused credential first. Messages already accepted with the old credential stay with it; the replacement doesn’t take them over.

Select Remove API key or Remove SMTP login, type REVOKE and confirm. From then on:

  • new requests with that credential are refused;
  • an SMTP connection that is already signed in is refused at its next message;
  • messages it submitted that haven’t been sent yet are held for review.

Revoking isn’t a recall. A message that is already being delivered may still go out.

If a secret leaks, revoke it straight away, then create a replacement.

The one-time key or password is at the top of the result page. Store it, then choose Continue to first email. If you selected both sending methods, Control first guides you to the other credential. IDs and management actions are under Credential details and management.