Domains, Senders And API Keys

Forge keeps every email resource inside a project:

• an email domain proves that the project controls a sending domain;
• a sender identity is one address on that verified domain;
• an API key authorizes transactional sending from one sender or from verified senders in one project.

A project can have multiple domains and each verified domain can have multiple sender identities.

Add An Email Domain

1. Open the project.
2. Go to Email → Domains.
3. Choose Add domain.
4. Enter a domain controlled by the project.
5. Publish the exact ownership TXT record Forge displays.
6. Choose Verify after the record is visible in public DNS.

Forge displays both the fully qualified record name and the short host variant used by DNS providers that append the root domain automatically. Copy the variant required by your DNS provider; do not publish both unless your provider requires it.

Domain verification is an ownership check. It does not replace sender DKIM verification.

Add A Sender Identity

After the domain is verified:

1. Go to Email → Identities.
2. Choose Add sender.
3. Select the verified domain.
4. Enter the complete From address, display name and daily quota.
5. Keep the provided delivery settings unless your workspace has approved an external SMTP route.
6. Save the sender.

Each sender has its own quota, DKIM key, delivery policy and send history. Creating noreply@example.com does not authorize billing@example.com; create a separate identity for every From address the application uses.

Verify DKIM

Forge generates a unique DKIM selector and public key for the sender. Publish the exact TXT record shown on the sender identity, then choose Verify.

The record has this general shape:

Type:  TXT
Name:  <selector>._domainkey.example.com
Value: v=DKIM1; k=rsa; p=<public-key>

Use the value generated for the selected sender. A selector or public key copied from another project or sender will not verify.

Do not send production traffic until both domain ownership and sender DKIM are verified. SPF and DMARC records must authorize the delivery route used by your domain; follow the exact DNS guidance shown by Forge for that sender.

External SMTP Credentials

When an identity uses an approved external SMTP provider, enter its SMTP username and password through the identity credential workflow. Require TLS unless the provider uses implicit TLS. Credentials are write-only in normal settings and encrypted at rest.

Active SMTP credentials are replaced through Email → SMTP Rotations:

1. Create a rotation for the sender.
2. Enter the replacement credentials and a controlled test recipient.
3. Verify authentication and test delivery.
4. Switch to the verified credential.
5. Observe delivery before revoking the previous credential at the provider.
6. Complete the rotation to destroy retained rollback material.

Do not place SMTP credentials in a project’s ordinary variable list or Doppler configuration unless the application itself, rather than Forge Email, directly owns that SMTP connection.

API Keys

Forge issues transactional keys with the email:send scope:

• Project key: can use any verified sender in one project. Include from when the project has more than one verified sender.
• Sender key: can use only the selected sender identity.

To create a key:

1. Go to Email → API Keys.
2. Choose project or sender scope.
3. Give the key a purpose-specific name.
4. Create it and store the displayed token immediately; Forge shows it once.

Keys begin with ef_. Forge stores a hash rather than the plaintext token. Revocation is permanent, so create a replacement before revoking a key used by a running service.

Store the key as a secret on only the application services that need to send email. Do not reuse one project’s key in another project.

Permissions And Safety

• Domain verification prevents use of an unowned domain.
• Sender DKIM keys are unique and their private material is encrypted.
• API keys are project- or sender-scoped and revocable.
• SMTP credentials are write-only by default and use a protected rotation workflow.
• Permanent bounces, complaints and provider incidents can suppress delivery before SMTP submission.