Email

An email service lets your other services send email — sign-up confirmations, password resets, receipts, notifications — through Why.email. Nothing runs in your environment: the service holds a Why.email account and the key your apps send with, and hands that key to them through variables.

You pay 50 kobo per email delivered, counted per recipient, from your wallet. There is no monthly fee and no daily limit.

Creating an email service

1. Click + Add and choose Email.
2. Enter a name. email is a good default — your other services will refer to it by this name.
3. Click Create.

The service shows Add a domain until you have verified a domain to send from. Until then, nothing can be sent.

Adding a sending domain

Email is always sent from a domain you own. Use a subdomain such as mail.example.com rather than example.com itself: it keeps this email's reputation separate from the email your team sends, and you can set it up without touching your existing mail records.

1. Open the service panel to the Setup tab.
2. Enter the domain under Sending domains and click Add domain.
3. Publish the four records shown at your DNS provider:

4. Click Verify.

DNS changes can take a while to become visible. If verification fails straight after you publish the records, wait a few minutes and try again. Once the domain shows Verified, the service shows Ready to send.

Sending from your apps

The service publishes these variables to every other service in the environment. Reference them as ${{email.VARIABLE}}, replacing email with your service's name:

For example, to point an app that reads MAIL_HOST, MAIL_USER and MAIL_PASS at the service:

MAIL_HOST=${{email.SMTP_HOST}}
MAIL_PORT=${{email.SMTP_PORT}}
MAIL_USER=${{email.SMTP_USERNAME}}
MAIL_PASS=${{email.SMTP_PASSWORD}}

Variables are filled in when the service that references them deploys, so the key never has to be copied anywhere. Your From address must be at a verified domain, for example hello@mail.example.com.

Anything that can send over SMTP works: auth servers, frameworks like Laravel, Django and Rails, WordPress plugins, monitoring tools. Code that talks to Why.email's API directly can use WHY_EMAIL_API_KEY and WHY_EMAIL_API_URL instead.

Replacing the key

If you think the key has leaked, open Settings → API key → Replace key. The old key stops working immediately, so redeploy every service that sends email afterwards to give it the new one.

Billing and suspension

Sending is charged about every 15 minutes, as a line on your usage and on your monthly statement called Email sending (Why.email). If your workspace runs out of credit and is suspended, sending is paused along with your other services: email your apps try to send is refused until you add funds. Your domains and key are kept.

Deleting an email service

Deleting the service deletes its Why.email account, with its domains, key and sending history. Any email sent since the last charge is charged at that point. Services that reference its variables will no longer be able to send.