Viesti Sign in

SMTP relay settings: host, ports, auth, reply codes

Any SMTP client can send through Viesti: your application's mail library, a framework mailer, or a command-line tool. Log in with an API key over TLS and send from an address at a verified domain.

Connection settings

Host smtp.viesti.email
Port and TLS 587 with STARTTLS, or 465 with implicit TLS (often labeled SSL or SMTPS). TLS 1.2 or later.
Authentication AUTH PLAIN, the only mechanism offered, and only once the connection is encrypted
Username apikey, literally
Password An API key from the Credentials page: mr_ followed by 64 hexadecimal characters
Message size Up to 10 MB (10 × 1,048,576 bytes), headers and encoded attachments included
Recipients Up to 50 per message, counting To, Cc and Bcc

On port 587 the client connects in plain text and upgrades with STARTTLS before logging in. On port 465 the connection is encrypted from the first byte. Mail libraries name these modes differently, often calling implicit TLS "SSL" or "secure"; the framework guides show the exact settings. Viesti accepts submission only on these two ports.

After TLS, EHLO advertises AUTH PLAIN, SIZE, PIPELINING, 8BITMIME, ENHANCEDSTATUSCODES, CHUNKING and LIMITS RCPTMAX=50.

Test the connection

swaks

swaks runs a complete SMTP transaction and prints it. With your key in VIESTI_API_KEY and an address at your verified domain as the sender:

swaks --server smtp.viesti.email:587 --tls \
  --auth-user apikey --auth-password "$VIESTI_API_KEY" \
  --from [email protected] --to [email protected] \
  --header "Subject: Your receipt" --body "Thanks for your order."

For port 465, use --server smtp.viesti.email:465 --tlsc instead of --tls. A successful run includes these replies:

<~  235 2.0.0 Authentication succeeded
<~  250 2.0.0 Roger, accepting mail from <[email protected]>
<~  250 2.0.0 I'll make sure <[email protected]> gets this
<~  354 Go ahead. End your data with <CR><LF>.<CR><LF>
<~  250 2.0.0 OK: queued

openssl s_client

To check TLS and the key without sending anything, build the AUTH PLAIN token: a NUL byte, the username, a NUL byte and the key, base64 encoded on one line.

printf '\0apikey\0%s' "$VIESTI_API_KEY" | openssl base64 -A

Then open a session and type the commands after the greeting:

openssl s_client -starttls smtp -connect smtp.viesti.email:587 -crlf -quiet
EHLO test.example
AUTH PLAIN <token>
QUIT

Viesti answers 235 2.0.0 Authentication succeeded for a valid key, 525 5.7.13 Workspace suspended; contact support (or Workspace pending review) for a valid key whose workspace is out of service, and 535 5.7.8 Authentication failed otherwise. For port 465, connect with openssl s_client -connect smtp.viesti.email:465 -crlf -quiet. Only a 535 counts toward the authentication limit.

What the server enforces

  • Sender. The MAIL FROM address must be at a domain verified in your workspace, and the From header must use the same domain. A Sender header, if present, must too. The match is exact: a subdomain needs its own verification. Viesti checks this once the message is complete, so the refusal arrives after DATA.
  • Recipients. At most 50 RCPT TO commands per message; duplicates that differ only in case are sent once. Each recipient is checked against your suppression list as it is given.
  • Size. At most 10 MB, measured after Viesti adds any missing headers. A client that declares a larger SIZE= is refused at MAIL FROM.
  • Line length. At most 2,000 bytes per line. Encode long HTML with quoted-printable or base64.
  • Headers. Exactly one From; at most one each of Sender, Subject, Message-ID, Date, Reply-To, To, Cc and Bcc; no Resent-* headers; no control characters.
  • Date. A Date header must parse and be within 24 hours of Viesti's clock. If it is missing or blank, Viesti adds one.
  • Message-ID. Kept if present. If it is missing or blank, Viesti adds <[email protected]>.
  • Signing and envelope. Viesti adds a DKIM-Signature for your domain (d=yourdomain.com, s=v1, rsa-sha256, relaxed/relaxed) and relays with its own signed Return-Path, so bounces come back to Viesti rather than to your MAIL FROM address. See DKIM, SPF and DMARC setup.
  • Content screening. Messages are screened before relay. A flagged message is still accepted with 250 and held for staff review; Activity shows it as quarantined.
  • Revocation. The key is checked again for every message, so revoking it stops an open session at its next message.

SMTP reply codes

Codes starting with 4 are temporary: the same message can succeed later, and a mail server or queue retries it for you. Codes starting with 5 are permanent: change something before you retry (RFC 5321, section 4.2.1; checked 26 September 2026).

Reply Meaning What to do
250 2.0.0 OK: queued Accepted after DATA. It counts as one email and appears in Activity. Nothing.
523 5.7.10 TLS is required AUTH was sent before STARTTLS. Enable STARTTLS on port 587, or use port 465.
502 5.7.0 Please authenticate first MAIL FROM was sent without logging in. Configure the username and password.
535 5.7.8 Authentication failed The key is wrong or revoked. Use an active key from Credentials as the password.
525 5.7.13 Workspace suspended; contact support The key is valid, but the workspace is suspended, or under review (Workspace pending review). No mail is accepted until it is reactivated. Write to [email protected]; a new key does not help.
454 4.0.0 Too many failed authentications; retry later Your address failed to log in 10 times within 10 minutes and is blocked for 10 minutes. Fix the credentials, then wait out the block.
454 4.7.0 Temporary authentication failure; retry later Viesti could not check the key. Retry.
452 4.5.3 Maximum limit of 50 recipients reached One RCPT TO too many. Split the recipients across messages.
550 5.0.0 recipient suppressed That recipient is on your suppression list. Other recipients of the message are still accepted. Stop mailing the address, or remove the suppression if it works again; see bounces.
550 5.0.0 recipient domain cannot receive mail DNS says the recipient's domain does not exist, has no mail server, or refuses all mail (null MX), usually a typo such as icloud.con. Other recipients of the message are still accepted. Fix the address.
550 5.0.0 sending not permitted The sender's domain is not verified in this workspace, the From or Sender header uses a different domain than MAIL FROM, or the workspace is not active. Send from a verified domain and keep the envelope and header domains the same.
550 5.0.0 invalid message An address or the header block breaks the rules above. Fix the address or headers.
550 5.0.0 Date header is unparseable or too far from the current time The Date header is malformed or more than 24 hours off. Fix the client's clock or date format, or leave Date out.
552 5.0.0 message too large Over 10 MB. Base64 makes attachments about a third larger than the files. Send smaller attachments, or a link instead.
500 5.4.0 Too long line A line exceeded 2,000 bytes. The connection is closed. Encode the body with quoted-printable or base64.
554 5.0.0 rejected by content audit The content screen refused the message. It is recorded in Activity but not counted. Do not retry unchanged.
451 4.0.0 submission quota exceeded The plan's allowance is used up. Retry after the window resets, or upgrade; see limits.
451 4.0.0 temporarily unavailable Viesti could not accept the message right now. Retry with backoff.
421 4.3.2 Service shutting down The server is restarting. Reconnect and resend.

A mail server that relays through Viesti queues a message after a 4xx reply and retries it. If your application talks to Viesti directly and its mail library reports a 4xx reply as an error, retry the send later from your own job queue.

Framework guides

Step-by-step SMTP setup for common stacks:

To send without SMTP, use the HTTP API.