Skip to content

Mail in your organisation's name

The mail OS sends about your organisation, such as an invitation or a notice to your administrators, can carry your organisation's own name, a reply address of your own and, once you set one up, an address at your own domain. This page shows how to set the sender name and the reply address, how to send from a domain of your own, and what an organisation takes over from the organisation above it. You set it up in two screens under Organization management; other applications use the same routes, named below.

The screens

  • Mail settings. Fill in the sender name and the reply address and choose Save mail settings. An empty field is taken from the organization above. Below the form is what a mail carries now: the sender name as a recipient sees it, the address it leaves from and the reply address, each with whether it is your organization's own or which organization above it comes from. Remove own mail settings makes everything come from above again. If someone else saved in the meantime, the screen loads the newest version and says so; check your changes and save again.
  • Sending domain. Choose a proved domain; the screen proposes mail. followed by that domain. Choose Add sending domain, copy the records from the table to your DNS provider and choose Check now. The screen says in plain words what state the domain is in and what to do: waiting for the records, verified, stopped (with the reason) or removed. Try again appears only for a domain that stopped because of the mail itself. You change the address before the @ and whether organizations below may send from it on the same page; removing asks for confirmation first.
  • Not on the screen yet. The state of each record on its own, and a reason for a domain held by another Scaleway account, are not there yet: the screen shows the state of the domain as a whole.

Who may do what

Every member of the organisation can see the mail settings and what a mail carries. An org-admin of the organisation can change the sender name and the reply address. The sending domain is set up by whoever may manage the organisation's domains, as for a web address (Manage roles).

Sender name and reply address

  • Sender name. The name a recipient sees before the address, for example Noordwind. At most 60 characters, without @, <, >, " or a backslash. It is one name for every language.
  • Reply address. Where a reply goes, for example support@noordwind.nl. It must be at a domain your organisation proved, or under one, so nobody can point replies at someone else's domain.

Either may be left empty; an empty one is taken from the organisation above. Without any sender name, OS uses the name of your brand identity in the recipient's language, else your organisation's name.

GET and PUT /api/v1/organisations/{id}/mail-settings read and replace the settings; DELETE removes them, so everything is taken from above again. A change names the revision you read in If-Match, exactly as for the brand identity: if someone else saved in the meantime, OS refuses yours and answers the current revision.

Sending from your own domain

Without a domain of your own, a mail in your name leaves from the nearest organisation above you that has one and offers it, or from OS's own address. The recipient then sees whose domain sends it, for example Noordwind via Reseller BV or Noordwind via Artific. Once your own domain is verified, your name stands alone.

  1. Prove a domain first, for example noordwind.nl: claim it with POST /api/v1/organisations/{id}/domains, publish the TXT record it names and verify it with POST …/domains/{domain}/verify.
  2. Ask for a sending domain with PUT /api/v1/organisations/{id}/sending-domain, naming the domain and the part before the @: {"domain": "mail.noordwind.nl", "local_part": "noreply"}. We recommend a subdomain such as mail.noordwind.nl: the records you publish then touch nothing your own mail already uses.
  3. Publish the records. Within seconds GET …/sending-domain lists the records Scaleway asks for: SPF and DKIM are required, MX and DMARC are recommended. Publish them at your DNS provider.
  4. Check. OS checks the domain every few minutes on its first day and hourly after that; POST …/sending-domain/check asks for a check now, at most once a minute. Once Scaleway has checked the records, the domain is verified, your administrators are told, and mail leaves from it.

An organisation has one sending domain. To move to another, remove the current one with DELETE …/sending-domain and ask for the new one; meanwhile mail leaves from the next address up. By default organisations below yours without a domain of their own send from yours, under their own names; set "offer_below": false to stop that.

When a domain stops sending

OS stops sending from a domain when its records are changed or removed, when Scaleway locks it, when its reputation is bad, or when too many of its mails fail. Its mail then leaves from the next address up the tree, and your administrators are told. A domain stopped for its records sends again by itself once Scaleway checks them again. A domain stopped for its mail sends again only after an administrator asks with POST …/sending-domain/retry, at most once a day, and the next check passes. If your organisation gives up the proof of the domain, the sending domain goes with it.

Every change is written to the audit trail.