Email tools

Preview

Connected applications are currently available to selected accounts only.

Fifteen tools manage the addresses on your domains: mailboxes, forwards (the portal calls them aliases), vacation replies, the catch-all and the DNS records mail needs. They appear once your account holds a domain. For how email hosting itself works, see Mailboxes and aliases.

A forward can send your mail to anyone

mail:write lets an application forward an address to any address in the world, and from then on every message sent there goes along. No tool reads a mailbox, so this is how mail content could leave your account. Setting up such a forward sends you an email, see Forwards outside your domains.

The tools

Tool	What it does	Needs
mail_account_list	Lists mailboxes, forwards, mailing lists and shared mailboxes, optionally of one domain or kind	mail:read, domain:read
mail_account_get	Shows one address	mail:read
mailbox_create	Creates a mailbox and returns the link where you set its password	mail:write, domain:read
mailbox_password_link	Returns the link where you set or change a mailbox's password	mail:read
mail_forward_create	Forwards an address to 1 to 10 other addresses	mail:write, domain:read
mail_account_update	Switches a mailbox or forward off or on, or replaces a forward's targets	mail:write
mail_account_delete	Deletes a mailbox or forward	mail:read, mail:delete
mail_vacation_get	Shows a mailbox's vacation reply, its text only on request	mail:read
mail_vacation_set	Switches a vacation reply on or off and sets its days, subject and text	mail:write
mail_catchall_get	Shows which mailbox gets mail for addresses nobody has	mail:read, domain:read
mail_catchall_set	Points the catch-all at a mailbox, replacing any it had	mail:write, domain:read
mail_catchall_disable	Switches the catch-all off: mail to unknown addresses is then refused	mail:delete, mail:write, domain:read
mail_dns_status	Lists the DNS records mail needs and whether each is right	mail:read, domain:read
mail_dns_apply	Writes the missing mail records	mail:write, dns:write, domain:read
mail_dns_replace	Replaces another provider's mail records with ITSH's	mail:write, dns:write, domain:read

Creating something that already exists in the same form is not an error: the tool returns it with created false, so a retry is safe. A new mailbox takes over its address from the catch-all.

Passwords: a link, not a password

No tool sets, returns or accepts a mailbox password. mailbox_create and mailbox_password_link return a link to the mailbox's page in the portal, which opens the password dialog for you while you are signed in. The link holds only the mailbox's number, nothing secret.

A mailbox an application created cannot be used until you set its password through that link. That is expected, not a failed setup.

Forwards outside your domains

mail_forward_create and mail_account_update can forward to addresses outside your account's domains. For every forward that starts sending to such an address:

• once the forward is set up, you get an email naming the forwarded address and the new targets outside your domains
• the activity log lists the targets under Asked to forward mail outside your domains to:
• if that email cannot be prepared, the forward is not set up at all, and the application receives forward_notice_unavailable:

the account holder cannot be told about a forward outside the account's domains right now, so it was not set up; try again shortly

If you did not ask for it, remove the forward under Email in the portal and disconnect the application.

Deleting

Deleting a mailbox deletes every message in it, and nothing restores them. The tool therefore deletes a mailbox only when confirm_email repeats its address:

Mail account 42 is the mailbox info@example.com: deleting it needs confirm_email set to that address.

That guards against the application deleting the wrong id. It does not guard against an application that was told to delete the mailbox. A forward is deleted without confirmation, and the activity log keeps its targets.

Mail DNS records

Tool	Writes	Leaves alone
mail_dns_status	Nothing	Everything
mail_dns_apply	Missing records. An existing SPF record gains ITSH's server, an existing DMARC record its report address	Records that clash, such as another provider's MX
mail_dns_replace	ITSH's records, after deleting every record on the names mail needs, including another provider's MX, SPF and DMARC	Nothing on those names

mail_dns_replace stops mail from reaching any other provider. The tool tells the application to use it only when you explicitly ask to move the domain's mail to ITSH. Both writing tools work on domains that use ITSH's nameservers.

One run may make at most 10 record changes with mail_dns_apply and 20 with mail_dns_replace. A zone that needs more is refused before anything changes, with a link to the domain's page in the portal, where you set mail up yourself:

this zone needs more record changes than a connected application may make in one run; nothing was changed

DNS changes can take up to an hour to be seen everywhere.

Refusals with a link

Code	Cause	The reply
mail_not_entitled	Mail is not booked on the domain	Links to the domain's page, where you book it
address_taken	Another mailbox, forward or list holds the address	Tells the application to find it with mail_account_list
not_supported	The address is a mailing list or shared mailbox	"… which is changed in the ITSH control panel only."
mail_dns_too_many_changes	The zone needs more changes than one run may make	Links to the domain's page

Limits

Limit	Value
Address	Local part up to 64 letters, digits and . _ % + -; the whole address up to 254 characters
Forward targets	1 to 10 per forward
Vacation reply	Subject one line of up to 255 characters, text up to 4,000; days as YYYY-MM-DD, the end not before the start
Listing	50 addresses per call by default, at most 200
Changes	60 a minute per account, shared with your own changes in the portal
Mail DNS	20 checks and 5 writes a minute per account, shared with your own checks and writes in the portal. A check costs 2 registrar calls, a write uses the account's whole registrar budget for a minute
Time per call	10 seconds; 45 for the three mail DNS tools

What's next

• Managing connections for the emails you get
• Setting up a domain for the mail records themselves