Connectors
Connectors
Connectors let an Enterprise organisation run part of Plotwork through services it already owns. The first is email: your organisation's invitations, reminders and notices go out from an address on your own domain, through your own email provider, with your provider's API token guarded by a key that belongs to your organisation alone.
TL;DR
| Question | Answer |
|---|---|
| What is a connector? | A link between your organisation and a service you run, set up once by an owner or admin. Email is the first connector. |
| Which plan? | Enterprise. On another plan the Connectors tab says so and a connector cannot be set up or tested. A connector saved earlier can still be removed. |
| Who sets it up? | The owner and the admins, signed in, on the organisation's Connectors tab in the portal. A key or a connected agent cannot read or change it. |
| Which providers? | Resend, SendGrid, Postmark, Mailgun (US or EU region) and Brevo. |
| From which address? | One on a domain your organisation verified under Single sign-on, and that your provider verified too. Nobody can send as a domain that is not theirs. |
| Which email goes through it? | Invitations to the organisation, reminders to turn on two-step sign-in, the outcome of a publish approval, and the notice that the key policy revoked a member's personal keys. |
| Which email never does? | Sign-in codes and email about a person's own account. Key expiry warnings and daily limit alerts also still come from Plotwork's address. |
| Can I use more than one provider? | Yes, one connector a provider. You choose which is the default; it is tried first, and the others take over in turn when it fails. |
| What if my provider fails? | The email goes through your next connector, or from Plotwork's address when none is left, and the Connectors tab shows why your provider refused it. |
| How is the token kept? | Sealed with a key made for your organisation alone, kept apart from the database. It is never shown again, only its last four characters. See How your token is protected. |
| Is it recorded? | Yes. Setting up, changing, testing, removing, choosing the default and replacing the key are recorded in the organisation's audit log, never with the token. |
Why send from your own domain
| Reason | What it changes |
|---|---|
| Your people trust your domain | An invitation from plotwork@acme.com reads as an internal message, not a third party's, so it is less likely to be ignored or reported. |
| Your mail rules apply | Your provider signs the email with your domain's DKIM key and sends it under your SPF and DMARC records, so your mail gateway can treat it like the rest of your outgoing mail. |
| Your provider keeps the records | Delivery, bounces and logs are in the account you already run, under the terms you already agreed with that provider. |
| Your reply address | Set a reply-to, such as your IT help desk, so a member's question goes to your own people. |
Which email goes through it
| Through your connector? | |
|---|---|
| An invitation to join the organisation | Yes |
| A reminder to turn on two-step sign-in | Yes. See Reminders to turn on two-step sign-in. |
| The outcome of a publish approval, to the person who asked | Yes |
| The notice that the organisation's key policy revoked a member's personal keys | Yes |
| A sign-in code | No. It always comes from Plotwork, so a broken or changed connector can never stop anyone signing in. |
| Email about a person's own account, such as a change of address | No. The account belongs to the person, not to the organisation. |
| A warning that an organisation key is about to expire | No. The scheduled run sends it from Plotwork's address. |
| An alert that a member, an agent or a key reached its daily limit | No. The scheduled run sends it from Plotwork's address. |
When the provider fails
| What happens | What you see |
|---|---|
| Your provider does not accept the token | The next connector sends the email, or Plotwork's address when none is left. The Connectors tab says the provider did not accept the token. |
| Your provider refuses the email, for example because the From address is not verified there | The next connector sends it, or Plotwork's address. The tab says the provider refused it and to check the From address there. |
| Your provider cannot be reached in time | The next connector sends it, or Plotwork's address. The tab says the provider could not be reached. |
| A connector is turned off | It is skipped. It stays saved until it is removed. |
| The organisation leaves Enterprise | The email goes from Plotwork's address. The connectors stay saved until they are removed. |
A failure is shown in Plotwork's own words, with when it happened, and never with what the provider sent back. It is cleared by the next successful test or by saving the connector again. A test email has no fallback: it tells you whether your provider took it, so you know before your members do.
More than one provider
An organisation can set up a connector for each provider it uses, and choose one as the default. Every email is tried through the default first. When it fails, the other connectors that are on take over in the order they were added, and Plotwork's own address is the last resort. A second provider is a standby that needs no action from you on the day the first one has an outage.
| Task | How |
|---|---|
| Add a provider | On the Connectors tab, add a provider and save its token and From address. The first one you add is the default. |
| Choose the default | Make another connector the default from its row, or tick the box when you save it. |
| Remove the default | The next connector added becomes the default. |
Set it up
- Verify your email domain on the organisation's Single sign-on tab.
- Verify the same domain at your provider and make an API token that can only send.
- Open the organisation's Connectors tab, choose the provider, paste the token and enter the From address.
- Send a test email to yourself.
Email through your own domain walks through each step.
See also
| Page | Why |
|---|---|
| Email through your own domain | The steps, from the domain to the first test email |
| How your token is protected | The two layers of keys, what an attacker would need, and crypto-shredding |
| Reminders to turn on two-step sign-in | Ask the members without it to turn it on, through your connector |
| Single sign-on | Where the email domain is verified |
| Audit log | Where every change to a connector is recorded |
| Plans and billing | What Enterprise includes |