Email through your own domain
Send your organisation's invitations, reminders and notices from an address on your own domain, through the email provider you already use. It takes five steps: prove the domain to Plotwork, verify it at your provider, make a send-only token, save the connector, and send a test.
TL;DR
| Question | Answer |
|---|---|
| Which plan? | Enterprise. |
| Who can do it? | The owner or an admin of the organisation, signed in to the portal. |
| What do I need? | An email domain you control, access to its DNS, and an account at Resend, SendGrid, Postmark, Mailgun or Brevo. |
| Which address can I send from? | Any address on a domain the organisation verified under Single sign-on. The domain must match exactly: acme.com does not cover mail.acme.com, so verify the subdomain too if you send from it. |
| Can I change the token later? | Yes. Paste a new one and save. Leave the field empty to keep the token already saved. |
| Can I add a second provider? | Yes. Add it on the same tab; choose which one is the default. The others take over in turn when the default fails. |
| How do I stop? | Turn a connector off to skip it for a while, or remove it. Removing the last one destroys your organisation's key, and every token with it, for good. |
1. Verify the domain under Single sign-on
The From address must be on a domain your organisation proved it owns, the same proof single sign-on uses. You do not need to set up an identity provider for this; the domain is enough.
- Open the organisation in the portal and choose the Single sign-on tab.
- Under Email domains, add the domain you will send from, such as
acme.com. - Publish the TXT record Plotwork shows at your DNS host, then press Verify. DNS can take a few minutes, so press it again if the record is not found yet.
Single sign-on has the details of the record. A domain shows on the Connectors tab once it is verified.
2. Verify the domain at your provider
Your provider must also be allowed to send for the domain, or it refuses the email. Each provider gives DNS records to publish, usually DKIM and SPF, sometimes a return path or a tracking record. Add the same domain there and publish its records.
A DMARC record for the domain is a good idea whichever provider you use. It tells receiving servers what to do with mail that fails DKIM and SPF.
3. Make an API token that can only send
Make a token for Plotwork alone, with the least access your provider offers: permission to send email, and nothing else where the provider allows it. A token used only by Plotwork can be revoked at your provider without touching anything else. The provider pages above say where to make one and what each provider can restrict.
4. Save the connector
- Open the organisation and choose the Connectors tab.
- Add a provider and choose which one.
- Paste the API token. Plotwork seals it as soon as it arrives and never shows it again, only its last four characters.
- Enter the From address, on the domain you verified. A From address on any other domain is refused.
- Optionally, enter a From name, such as
Acme IT, of up to 80 characters, and a reply-to address, such as your help desk. - For Mailgun, choose the region your domain is in: US or EU.
- When you already have a connector, tick Make this the default if this one should be tried first.
- Save.
| Field | Rule |
|---|---|
| Provider | One of Resend, SendGrid, Postmark, Mailgun and Brevo. One connector a provider. |
| API token | Required the first time. Left empty later, the saved token is kept. |
| From address | On a domain the organisation verified |
| From name | Optional, up to 80 characters. Line breaks, quotes and angle brackets are replaced by spaces. |
| Reply-to | Optional, any address |
| Region | Mailgun only: US or EU. US when not chosen. |
| On | On by default. Off, the connector is skipped and stays saved. |
| Default | The first connector is the default. Tick it on another to make that one the default. |
5. Send a test
Press the button to send a test email. It goes through your provider to your own address, with no fallback to Plotwork's sender, and the tab says at once whether your provider took it or why not:
| Answer | What to check |
|---|---|
| The provider did not accept the token | The token is wrong, revoked, or lacks permission to send. Make a new one. |
| The provider refused the email | The From address or its domain is not verified at the provider, or the account cannot send to your address yet. |
| The provider could not be reached | Your provider is down or slow. Try again in a few minutes. |
A test that works clears the last error the tab showed. Tests are rate limited, so a few in a row are fine, but not a loop.
After it is set up
| Task | How |
|---|---|
| See whether it works | The Connectors tab shows when the last test passed, and the last error with when it happened. |
| Change the From address, name or reply-to | Edit them and save. The token is kept. |
| Change the token | Paste the new one and save. Revoke the old one at your provider. |
| Add another provider | Add it, paste its token and save. The default stays as it is unless you tick the box. |
| Choose the default | Make another connector the default from its row. |
| Replace the organisation's key | Press the button to replace the key. See How your token is protected. |
| Stop for a while | Turn the connector off. The next one, or Plotwork's address, sends instead. |
| Stop for good | Remove the connector. When it was the last one, your organisation's key is destroyed, no token can be opened again, and the email goes from Plotwork's address. |
Through the API
Every step is also an endpoint, called with a signed-in session:
| Task | Endpoint |
|---|---|
| Read the connectors | GET /orgs/{org}/connectors |
| Set one up or change it | PUT /orgs/{org}/connectors/email/{provider} |
| Make one the default | POST /orgs/{org}/connectors/email/{provider}/default |
| Send a test | POST /orgs/{org}/connectors/email/{provider}/test |
| Replace the key | POST /orgs/{org}/connectors/rotate-key |
| Remove one | DELETE /orgs/{org}/connectors/email/{provider} |
See also
| Page | Why |
|---|---|
| Connectors | Which email goes through a connector, and what happens when it fails |
| How your token is protected | How the token is sealed, and what removing it does |
| Single sign-on | Proving the email domain |
| Audit log | Where each change is recorded |