Help Domains and sending
Sending email from your app
This page explains how your application sends email through Amazon SES in your own AWS account. It covers how to create, rotate and revoke a domain's sending credentials, the SMTP and API settings, the configuration set and headers each email needs, test emails, and the limits that apply.
How sending works
Your application connects to Amazon SES directly. SendForever is never in between: it does not relay, queue or store your email. SendForever sets up what SES needs for each domain and shows you the exact settings to use.
Everything a domain needs for sending is on its SMTP & API tab. To open it, choose the domain in the header, open the domain's Settings and click the SMTP & API tab. You can also click Send email at the top of the page. The tab is filled in for the domain with your account's region, the domain's configuration set and, for an isolated domain, its tenant.
Copy AI prompt, at the top of the tab, copies instructions you can paste into an AI coding assistant so it sets up your app. They include the domain's settings, how to connect, the rules for every email and, when the stack supports it, how to add people from your app. The prompt holds no credentials. The assistant reads them from your app's environment.
If the domain's checks are not done yet, the tab shows This domain is not ready to send yet. Finish the DNS records first. Otherwise, mail goes out unsigned or gets rejected. See DNS records.
Sending credentials
Each domain gets its own sending user in your AWS account. It is an IAM user under the IAM path /sendforever/, named sendforever- followed by the domain with its dots replaced by dashes (for example sendforever-example-com). It can only send as that domain, through the domain's configuration set. The permissions boundary of the SendForever stack limits it, whatever policy is attached.
Only team owners and admins can create, rotate or revoke credentials. Members can see the tab but not change the credentials.
Create credentials
- Open the domain's Settings and the SMTP & API tab.
- Under 1. Sending credentials, click Create sending credentials.
- A dialog shows the credentials once:
- SMTP user name / Access key ID
- SMTP password
- Secret access key (API only)
- SMTP host
- Copy them into your application's configuration, then click I have saved them. You cannot close the dialog any other way.
SendForever keeps only the access key ID. It never stores the SMTP password or the secret access key, so it cannot show them again. After creation, the card shows the access key ID, the IAM user, and when the key was created and last rotated.
Rotate credentials
If you lost the password or secret, or want a new key, click Rotate credentials and confirm. SendForever deletes every access key of the sending user and creates a new one. The dialog shows the new key once. The old key stops working immediately, so anything that uses it stops sending until you give it the new one.
Revoke credentials
Click Revoke and confirm. SendForever deletes the sending user, with its keys and policy, from your AWS account. Anything that uses those credentials stops sending immediately. You can create new credentials afterwards.
Connect with SMTP
SMTP works with any framework or tool and needs no SDK. Under 2. Connect your application, choose SMTP. The settings are:
| Field | Value |
|---|---|
| Host | email-smtp.<region>.amazonaws.com, the region your AWS account is connected in |
| Port | 587 |
| Encryption | STARTTLS |
| From address | A suggested address at the domain: notifications@ for a transactional domain, newsletter@ for a marketing one |
| Username | The access key ID from step 1 |
| Password | The SMTP password shown in step 1 |
If your tool does not support STARTTLS, port 465 with implicit TLS also works. The SMTP password is derived from the secret access key for your account's region, so it only works with that region's SMTP host.
The headers every email needs
Add this header to every message so it goes through the domain's configuration set:
X-SES-CONFIGURATION-SET: sendforever-example-com
If the domain is isolated, every message must also name its tenant with the Isolation header. Without it, the email still goes out, but it counts against the whole account instead of the domain. See Domains.
X-SES-TENANT: example-com
The tab shows examples you can copy for Laravel, Node.js (Nodemailer), PHP (Symfony Mailer), Python and Test from the terminal (swaks). For the domain example.com in us-east-1, they look like this. The tenant lines only appear for an isolated domain.
# .env
MAIL_MAILER=smtp
MAIL_HOST=email-smtp.us-east-1.amazonaws.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=your-smtp-user-name
MAIL_PASSWORD=your-smtp-password
[email protected]
MAIL_FROM_NAME="${APP_NAME}"
// app/Providers/AppServiceProvider.php
use Illuminate\Mail\Events\MessageSending;
use Illuminate\Support\Facades\Event;
Event::listen(MessageSending::class, function (MessageSending $event) {
$event->message->getHeaders()->addTextHeader('X-SES-CONFIGURATION-SET', 'sendforever-example-com');
$event->message->getHeaders()->addTextHeader('X-SES-TENANT', 'example-com');
});
import nodemailer from 'nodemailer';
const transport = nodemailer.createTransport({
host: 'email-smtp.us-east-1.amazonaws.com',
port: 587,
secure: false, // STARTTLS
auth: { user: process.env.SES_SMTP_USER, pass: process.env.SES_SMTP_PASSWORD },
});
await transport.sendMail({
from: '[email protected]',
to: '[email protected]',
subject: 'Hello',
text: 'Sent through Amazon SES.',
headers: { 'X-SES-CONFIGURATION-SET': 'sendforever-example-com', 'X-SES-TENANT': 'example-com' },
});
swaks --to [email protected] --from [email protected] \
--server email-smtp.us-east-1.amazonaws.com:587 --tls \
--auth-user "$SES_SMTP_USER" --auth-password "$SES_SMTP_PASSWORD" \
--header "X-SES-CONFIGURATION-SET: sendforever-example-com" \
--header "X-SES-TENANT: example-com" \
--header "Subject: SendForever test" --body "It works."
Connect with the Amazon SES API
Use the API if you send more than a few messages per second. Choose API under 2. Connect your application. The API uses the same credentials: the access key ID and the secret access key from step 1, instead of the SMTP password. You pass the configuration set (and the tenant, for an isolated domain) as parameters instead of headers.
The tab shows the IAM policy attached to the sending user. It allows sending and nothing else:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["ses:SendEmail", "ses:SendRawEmail"],
"Resource": [
"arn:aws:ses:us-east-1:YOUR_ACCOUNT_ID:identity/example.com",
"arn:aws:ses:us-east-1:YOUR_ACCOUNT_ID:configuration-set/sendforever-example-com",
"arn:aws:ses:us-east-1:YOUR_ACCOUNT_ID:tenant/example-com/*"
]
}]
}
The tab shows examples for Laravel, Node.js (AWS SDK v3), PHP (AWS SDK) and Python (boto3). For Laravel, which needs the aws/aws-sdk-php package:
# .env
MAIL_MAILER=ses-v2
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_DEFAULT_REGION=us-east-1
[email protected]
MAIL_FROM_NAME="${APP_NAME}"
// config/services.php
'ses' => [
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
'options' => [
'ConfigurationSetName' => 'sendforever-example-com',
'TenantName' => 'example-com',
],
],
The configuration set
Every domain sends through its own configuration set, named sendforever- followed by the domain with dashes (sendforever-example-com). The set requires TLS, tracks reputation metrics and records the domain's emails in the activity log. It also holds the domain's choices for opens and clicks, kept copies and the webhook.
Amazon SES applies the configuration set an email names in the X-SES-CONFIGURATION-SET header or the ConfigurationSetName parameter. SendForever gives a domain its own set when you add the domain, or when you click Apply recommended settings on the domain's Configuration tab. It then also makes that set the domain's default configuration set in Amazon SES. SES uses the default set for an email that names no set. So name the domain's own set, or none. An email that names a different set gets that set's options instead.
A domain that was already in Amazon SES keeps the configuration set it had until you apply the recommended settings. When a domain moves from a shared set to its own, emails may still name the old set for a while. Until they stop, the domain's Configuration tab shows Emails use this domain's configuration set with a warning. In the meantime, the sending user may still send through the old set, so nothing breaks. With Deliverability insights on, that check also names any other set your app names for the domain, with how many emails went through it. If your app names that set on purpose, owners and admins can click Ignore, and the check stops naming it.
Rules for every email
3. Rules for every email lists what only your application can do:
- Send only from addresses at the domain, with a consistent name people recognize.
- Never email an address that bounced or complained. The account suppression list blocks most of them. Skip the rest using your own data. See Suppressions.
- On a transactional domain, do not send newsletters or campaigns. Send them from a marketing subdomain.
- On a marketing domain, Gmail and Yahoo require one-click unsubscribe on bulk mail, and people who unsubscribed must not get it. Campaigns sent from SendForever do both. For bulk mail your app sends to an audience, first call
contacton the subscriptions API for each person, naming the audience. Skip anyone whoseaudiencessaysfalsefor that audience or who hasunsubscribed_from_all. Putunsubscribe_urlin the email, and add these two headers with it:
List-Unsubscribe: <unsubscribe_url>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
A one-click unsubscribe from the header, or a click on the link, takes the person off that audience. The next campaign to that audience skips them, and so does your app, as long as it calls contact before each send. Each key can make up to 600 calls a minute, so use a campaign for a bigger list. You create keys with Add from your app on the Audiences page. See Audiences and contacts.
Send a test email
- Open the domain's Settings.
- Open the actions menu (the ... button at the top right of the page) and click Send me a test email.
Owners and admins see the option once the domain is ready to send. SendForever sends one email from the domain's suggested address to your own account's email. It goes through your Amazon SES, the domain's configuration set and its tenant. If it arrives, DKIM, SPF and the custom MAIL FROM are in place. It also appears in the activity log within a minute.
A domain sends up to 5 test emails an hour, including tests of templates sent from it.
Limits and the sandbox
A new Amazon SES account starts in the sandbox. There it only delivers to verified addresses, up to 200 emails a day. The domain page, the team Overview and the AWS account page say so until AWS grants production access. See Production access.
In the sandbox, Amazon SES refuses a test email to an address that is not verified. SendForever then asks Amazon SES to verify your address, and Amazon SES emails it a link. Open the link, then send the test again. The link expires after a day. To get a new one, delete the address in the Amazon SES console and send the test again. Each verification request counts toward the hourly test limit.
SendForever does not show your account's daily sending quota or maximum send rate. Amazon SES sets both for your account. Campaigns send at the account's maximum send rate unless you give them a pace, and a campaign that reaches the daily quota stops. See Campaigns.
Common questions
I lost the SMTP password. Can I see it again?
No. SendForever never stores the SMTP password or the secret access key. Click Rotate credentials to get new ones. The old key stops working immediately.
Does my email pass through SendForever?
No. Your app sends to Amazon SES in your own AWS account. SendForever only keeps the access key ID of the sending user, and the events of your emails stay in your account.
Can one set of credentials send for several domains?
No. Each domain's sending user may only send as that domain and through its configuration set. Create credentials on each domain's SMTP & API tab.
What happens if I leave out the X-SES-CONFIGURATION-SET header?
Amazon SES uses the domain's default configuration set, which SendForever sets to the domain's own set when it creates that set. Adding the header makes the choice explicit. If you name a different set, its options apply instead.
Why does my isolated domain need the X-SES-TENANT header?
Only emails that name the tenant use the domain's own reputation, pause switch and suppression list. Without the header, the email still goes out, but it counts against the whole account.
The test email did not arrive. What now?
If the page says the account is in the sandbox, open the verification link Amazon SES emailed you and send the test again. Otherwise, open the domain's Activity. The test appears there within a minute, with what happened to it. If the page says a domain sends up to 5 test emails an hour, wait the number of minutes it shows.
Creating credentials says another domain would share the IAM user. Why?
Two domains can map to the same user name, such as a-b.com and a.b.com. Only one of them can have sending credentials in the account. If this one should have them, revoke the other domain's credentials first.
Who can create or revoke credentials?
Team owners and admins. Members see No sending credentials yet. A team owner or admin can create them here. or the existing key ID, without the buttons.
Can my sending credentials add people to audiences?
No. They only send. Your app adds people through the subscriptions API, with a subscription key of the domain.
Still stuck?