Send over SMTP with credentials

An SMTP credential is a username and password that an application uses to sign in to SMTP Relay. Create one for each application, so that you can rotate or revoke one without touching the others. The send API also sends through a credential, so a relay needs at least one even if you only send over HTTPS.

• An SMTP Relay service with the status active. While the service is being set up, Create credential… is greyed out.
• A domain on the relay whose ownership check has passed. See Add a sending domain to SMTP Relay.
• Room for another credential. A relay holds up to 200. When its plan sets a lower limit, the SMTP credentials card shows it, such as 2 of 5 on this plan.

1. In the dashboard, go to Email, open the SMTP Relay service, then the Credentials tab.
2. Select Create credential….
3. In Domain, choose the domain the application sends from. A domain that is not verified yet shows (pending) after its name.
4. In Label, name the application, such as billing app. Leave it empty and the label is default.
5. Select Create credential.
6. Copy the Username and Password from the dialog, or select Copy all, and store them where the application keeps its secrets. We show the password only this once.
7. Select I have saved them.

The username is built from the label and the domain: the label in lower case with anything other than letters and digits turned into hyphens, cut to 24 characters, then a hyphen and six random characters. A credential labelled billing app on example.com gets a username such as billing-app-3f9a1c@example.com. The password has 32 characters.

Give the application these settings. The SMTP endpoint card on the Credentials tab shows the host for your relay.

The From address does not have to be on the credential's own domain: one credential can send for every domain on the relay. To send a message as marketing mail, add the header X-Mail-Category: marketing; see Transactional and marketing mail.

To test the credential from a terminal, write a message to a file:

From: Receipts <receipts@example.com>
To: alex@example.com
Subject: Test from SMTP Relay

This message came through SMTP Relay.

Then send it with curl, which upgrades the connection with STARTTLS:

curl --url "smtp://smtp.mail-fra.coritan.com:587" --ssl-reqd \
  --user "billing-app-3f9a1c@example.com:$SMTP_PASSWORD" \
  --mail-from "receipts@example.com" \
  --mail-rcpt "alex@example.com" \
  --upload-file message.txt

In application code, use your language's SMTP library. With Python's standard library:

import os
import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Receipts <receipts@example.com>"
msg["To"] = "alex@example.com"
msg["Subject"] = "Your receipt"
msg.set_content("Thanks for your order.")

with smtplib.SMTP("smtp.mail-fra.coritan.com", 587) as smtp:
    smtp.starttls()
    smtp.login("billing-app-3f9a1c@example.com", os.environ["SMTP_PASSWORD"])
    smtp.send_message(msg)

• The credential is listed on the Credentials tab with its label, its username, when its password was set and its Enabled switch on.
• The application's messages go out signed for your domain, and each one appears on the Events tab.

Rotate a credential's password when it may have leaked, or on a schedule.

1. On the Credentials tab, open the menu at the end of the credential's row and select Rotate password….
2. Select Rotate password to confirm. The old password stops working at once.
3. Copy the new Password from the dialog, then select I have saved them.
4. Put the new password in the application straight away.

The new password has 24 characters. The Password set column shows when it changed. To give a credential a password you choose, use the API: see With the API.

Turning a credential off stops it signing in but keeps its username and password, so you can turn it back on later.

1. On the Credentials tab, find the credential.
2. Use the switch in its Enabled column. A toast confirms the change, such as billing-app-3f9a1c@example.com disabled.

1. On the Credentials tab, open the menu at the end of the credential's row and select Revoke credential….
2. Type the credential's username to confirm, then select Revoke credential.

The send API needs an active credential. It uses one on the From address's domain when there is one, and otherwise any active credential on the relay, so revoke the last one only when nothing sends through the relay.

On an internal mail tenant, the credential the platform sends its own mail with can be rotated but not turned off or revoked: Revoke credential… shows Staff only.

Prove you own example.com first: publish the ownership record shown under Domains, then check the domain

The domain's ownership check has not passed yet. Publish the ownership record and select Verify now on the domain's page. See Add a sending domain to SMTP Relay.

A relay may hold at most 200 SMTP credentials; remove one you no longer use or This plan allows 5 SMTP credentials

The relay holds as many credentials as it can. Revoke one you no longer use. Several applications can share a credential, but you then rotate them together.

The domain is not registered in the mail engine yet; check the domain again in a minute

The domain's ownership check passed moments ago and we are still setting it up. Select Verify now on the domain's page, then create the credential again.

Service is not active

The service is suspended or not set up yet. Its status is on the Overview tab.

The application says the username or password is wrong

Use the whole username, including the six random characters before the @, and the password from when you created or last rotated the credential. A credential that is turned off cannot sign in, and while sending is paused for the relay, no credential can: the panel then shows Sending is paused. After 30 failed sign-ins in an hour from one IP address, the relay refuses that address for 24 hours, so fix the password before the application retries many times.

The application cannot sign in when its settings are a URL

Some frameworks take the settings as one URL, such as smtp://user:password@host:587. The username contains an @, and passwords can contain @, #, %, ?, + and =, so percent-encode both, or pass the username and password as separate settings.

550 5.7.1 Sender domain example.org is not verified on this account

The envelope sender, the address the application gives in MAIL FROM, is not on a domain of this relay whose ownership has been proved. Send from an address on one of the relay's domains.

550 5.7.1 From address must use a verified domain, not example.org

The From header is on a domain the relay has not proved. Change the From address, or add the domain.

550 5.7.1 Sending is not available for this account

The credential is turned off, or the relay is not active. Turn the credential on, or check the relay's status on the Overview tab.

550 5.7.1 Sending is paused for this account; contact support

Sending is paused for the relay: its bounce or complaint rate passed our limit, or our staff paused it. See Sending reputation and deliverability.

550 5.7.1 Monthly allowance and its 12% buffer are used up; upgrade the plan to continue

The relay has sent everything its plan allows this month. A free plan says Monthly sending allowance reached; upgrade the plan to continue. See How SMTP Relay sending limits work.

550 5.1.1 Recipient alex@example.com is suppressed after a bounce or complaint

The address is on the relay's suppression list. See Manage the suppression list.

550 5.7.1 This login is not a mail account we know

The credential belongs to a relay that no longer exists. Create a credential on an active relay.

The application cannot connect

Check the host and the port. Port 587 needs STARTTLS and port 465 needs TLS from the start, so an application that uses the wrong security for the port cannot connect. Use port 587 or 465: many networks block port 25.

A large message is refused

SMTP accepts messages up to 50 MB, including the encoded attachments, which are about a third larger than the files. The send API takes up to 25 MB.

• Add a sending domain to SMTP Relay
• Send email over HTTPS
• Transactional and marketing mail
• How SMTP Relay sending limits work

Create a credential:

curl -X POST https://api.coritan.com/api/v1/client/smtp-relay/4812/credentials \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain_id": 311, "label": "billing app"}'

The body takes these fields:

domain_id

The domain the username goes on, from GET /client/smtp-relay/{service_id}/domains. Its ownership check must have passed.

label

Optional, 1–100 characters, default when left out. It names the credential in lists and starts its username.

The answer is 201 with the credential, its password, shown this once, and smtp, the host names to connect to:

{
  "id": 7731,
  "tenant_id": 903,
  "domain_id": 311,
  "kind": "relay_credential",
  "address": "billing-app-3f9a1c@example.com",
  "local_part": "billing-app-3f9a1c",
  "display_name": "billing app",
  "quota_bytes": 0,
  "targets": [],
  "status": "active",
  "password_set_at": "2026-09-16T10:52:03.418207+00:00",
  "created_at": "2026-09-16T10:52:03.418207+00:00",
  "totp_enabled": false,
  "app_passwords": 0,
  "frozen_reason": null,
  "user_id": null,
  "password": "Vq8#nT2mLw!4Rz=Kp7Xc9@Hd3Fs+Gy6J",
  "smtp": {
    "smtp_host": "smtp.mail-fra.coritan.com",
    "imap_host": "imap.mail-fra.coritan.com",
    "jmap_host": "jmap.mail-fra.coritan.com",
    "mx_hostname_base": "mail-fra.coritan.com",
    "webmail_url": "https://jmap.mail-fra.coritan.com",
    "display_name": null,
    "support_url": null,
    "postmaster_address": null,
    "user_mailbox_domain": null
  }
}

The username is address, and the label is display_name. Connect to smtp.smtp_host.

The other operations:

locked is null on your own services. On an internal mail tenant it holds The platform sends its own mail with this credential. You can rotate it, but only staff can disable or delete it., and turning that credential off or revoking it answers 409 with the same message.

To give a credential a password you choose, 12–128 characters, post it to the credential's id under mailboxes:

curl -X POST https://api.coritan.com/api/v1/client/smtp-relay/4812/mailboxes/7731/password \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "a-long-passphrase-you-chose"}'

The answer is {"id", "address", "password"} with the password you sent. The send API goes on working after a rotation or a new password, because it always uses the current one.

A refused request answers 400 with one of the messages in Troubleshooting, or Domain not found on this service for a domain_id that is not on the relay. An id that is not a credential of the relay answers 404 Not found, a value outside a field's range answers 422, and a failure on our side answers 502 with a message that starts Mail engine error:.

The same paths exist under /client/mail/{service_id}/credentials, where they do this:

• GET answers {"items": [], "smtp": {...}}: no credentials, and the service's host names.
• POST answers 404 Not an SMTP Relay service.
• .../{account_id}/rotate and .../{account_id}/enabled accept a mailbox's id and act on the mailbox. rotate works as POST .../mailboxes/{account_id}/password with {}: it sets a generated password and turns off two-factor sign-in. See Mailboxes.
• DELETE .../{account_id} answers 404 Not found.