LogoSimply SendDOCS
    GuideSMTP Relay

    SMTP Relay Configuration

    Learn how to obtain your SMTP credentials and configure your existing applications or servers to send transactional email through Simply Send.

    SMTP Message Fields and Accepted Attributes

    Provide standard message fields as MIME headers and content. The SMTP relay also recognizes the Simply Send headers listed below.

    Parameters

    FromRequired
    MIME header
    Verified sender address. A display name is supported, for example "Service Team" <sender@example.com>.
    To, Cc, BccRequired
    MIME headers or SMTP envelope recipients
    At least one SMTP envelope recipient (RCPT TO) is required. To, Cc, and Bcc can be combined. Bcc recipients receive the message without appearing in its headers. For a BCC-only send, provide Bcc without To or Cc.
    SubjectRequired
    MIME header
    Subject line for the email.
    HTML or plain-text bodyRequired
    MIME body
    The relay converts a plain-text-only message to HTML. Include the required compliance template variables.
    Reply-To
    MIME header
    Address where replies should be sent.
    Attachments
    MIME attachments
    Up to 10 files. Attachment bytes, Base64 encoding, and MIME overhead count toward the total email size limit listed below.
    SMTP email size
    Message limit (not a header)

    The standard limit is 2 MB per email. With an approved workspace limit, the final email can be up to 40 MB (40,000,000 bytes), including the body, headers, MIME overhead, and Base64-encoded attachments. The body and other non-attachment data must stay within 2 MB. Attachment contents alone cannot total 40 MB.

    For larger emails, go to Account → Approvals, select Transactional Email Size Increase, and describe the total email size and expected sending volume. Wait for approval and the workspace limit update before sending. Use the same SMTP host and ports for standard and approved larger emails.

    Idempotency-Key
    MIME header

    Optional unique UUID to prevent duplicate sends when your client retries. Use a new UUID for each distinct email and reuse the same key only when retrying the same send. The header is stripped before delivery and is not forwarded to recipients.

    A retry with the same key within 24 hours returns the original result without sending a second email. If the original send is still in progress, the SMTP server returns a 450 temporary failure; retry later with the same key.

    X-Simply-Send-Tag
    MIME header
    Caller-defined identifier shown on each email event in analytics. Use 1–128 ASCII letters or digits only. Do not include personal, confidential, or sensitive information. The header is not forwarded to recipients.
    Other custom headers
    MIME headers
    Additional MIME headers are accepted and included with the message, subject to validation and headers managed by Simply Send.

    Need another attribute supported? Let us know which message or event detail would help your integration.

    Character Encoding and Charset

    Use UTF-8 and a MIME-aware email library whenever possible. A charset tells the relay how to decode incoming bytes into text. Base64 and quoted-printable are transfer encodings; they do not identify the charset by themselves. The relay decodes the incoming message, and the delivery composer generates the outgoing MIME message. The credential fallback does not force every field into one encoding.

    1. Subject and display names: MIME encoded-words carry their own charset, for example =?UTF-8?B?...?=. Unlabelled headers containing valid UTF-8 are preserved. For supported human-readable headers whose raw bytes are not valid UTF-8, the relay uses the credential's selected fallback.
    2. Body: each plain-text or HTML MIME part uses its own declared charset. If a text body part has no charset, the selected fallback is used directly, even if its bytes could be valid UTF-8. Declare UTF-8 explicitly on UTF-8 body parts when using a legacy fallback.
    3. No fallback: this is the default. Without a selected fallback, the relay keeps its existing MIME parsing behavior. It does not automatically detect a legacy charset or add a new requirement to select one.

    A body's charset does not apply to the Subject header or to other MIME parts. For example, an unlabelled Windows-1252 subject and a body declaring UTF-8 are decoded separately: the subject uses a Windows-1252 credential fallback, while the body uses UTF-8. Correct MIME declarations take precedence over the fallback.

    To configure a legacy application, open SMTP Credentials and select Fallback text encoding (charset) when creating or editing its credential. Choose the encoding the application actually sends, rather than choosing by language alone. The selector is disabled when the credential does not support this setting. Windows-1252 and CP1252 refer to the same encoding; an application's label “ANSI” is not enough to identify its code page.

    Supported fallbacks: Windows-1252 / CP1252, GB18030, Big5, Shift JIS, EUC-KR, Windows-1251, ISO-8859-2, Windows-1256, Windows-1255, and Windows-874. One fallback applies to all eligible unlabelled text on that credential. Applications sending different legacy encodings should declare them per message part or use separate credentials with the appropriate fallback.

    The fallback also covers supported human-readable header text, address display names, and unlabelled MIME filename metadata. It does not guess an encoding for email addresses or transcode attachment contents. Use MIME filename encoding for non-ASCII attachment names. Credential settings are cached: changes can take up to 65 minutes to reach new SMTP connections. Reconnect before testing the updated setting.

    Both examples represent Unicode text without needing a legacy fallback. The raw MIME example's Subject is an RFC 2047 UTF-8 encoded-word; its body separately declares UTF-8 and uses quoted-printable. Adding only a header declaration without converting the source bytes does not repair an incorrectly encoded message.

    1. Get Your SMTP Credentials

    To start sending via SMTP, you'll need your unique SMTP credentials.

    1. Log in to your Simply Send Dashboard.
    2. Navigate to the SMTP on the left menu.
    3. Create a new SMTP credentials. Keep this credentials secure.

    2. Connection Settings

    Use these settings in your email client, server configuration, or application code.

    SMTP Host

    smtp.simplysend.email

    Port (STARTTLS)

    587

    Port (SSL/TLS)

    465

    Authentication

    Required

    3. Implementation Examples

    Identify the sending application (optional)

    Add an X-Simply-Send-Tag MIME header to identify the application, service, device, or instance making the send. This is useful when multiple systems share SMTP credentials: the tag appears on each email event in analytics. Use 1–128 ASCII letters or digits only. Do not include personal, confidential, or sensitive information. The tag is not forwarded to recipients.

    Swaks (Bash)

    Standard Email Send (To recipient visible to all)

    BCC-only Send (Recipient hidden from other recipients)

    Swaks requires the --to flag for the envelope recipient. When you also specify --bcc, Simply Send will use BCC for delivery and ignore the To field.

    Tag example (Swaks)

    4. Troubleshooting

    Accents, non-Latin characters, or filenames appear corrupted

    Symptoms include question marks, replacement characters (�), or garbled text such as “Solicitação”. First check the original message generated by the sending application, before it reaches the relay.

    1. Prefer UTF-8 with a MIME-aware library. Encode non-ASCII subjects and display names as MIME encoded-words, and declare the actual charset on each text body part. A body charset does not set the subject's charset.
    2. If your ERP, printer, or other legacy application cannot generate correctly labelled MIME, confirm its outgoing code page with its administrator or vendor. Do not assume every language or application uses Windows-1252.
    3. Open SMTP Credentials, edit the credential used by the application, select the matching Fallback text encoding (charset), and save. If the selector is disabled, contact support about availability for that credential.
    4. Allow up to 65 minutes for cached settings to refresh, reconnect the SMTP client, and send a new test. Check the subject, display names, plain-text and HTML bodies, and attachment filenames. If a UTF-8 body becomes garbled after selecting a legacy fallback, ensure that body part explicitly declares charset=UTF-8.
    5. If the message declares the wrong charset, correct the sending application: the fallback does not override an explicit declaration. If the source has already replaced characters with literal question marks, the relay cannot recover the original text. An incompatible fallback can also cause rejection or incorrect text; return to No fallback if the application already sends correctly encoded MIME.

    Ports 465 and 587 use the same text parsing rules. Switching ports, enabling SMTPUTF8, or using 8BITMIME does not identify or convert a legacy charset. If the issue continues, share a synthetic reproducer with support, including MIME headers, the source encoding, and the selected fallback. Remove credentials and personal data. See Character Encoding and Charset for examples.

    TLS / Root certificate errors

    The SMTP endpoint smtp.simplysend.email uses a TLS certificate issued by Let's Encrypt. If your email client or platform reports that the root certificate cannot be found, it means the system does not yet trust the ISRG Root X1 certificate authority.

    1. Download the ISRG Root X1 certificate from https://letsencrypt.org/certs/isrgrootx1.pem.
    2. Install it into your system's trusted root certificate store (or ask your IT/security team to do so).
    3. If your environment uses a TLS-inspecting proxy or strict outbound firewall, whitelist smtp.simplysend.email and allow outbound traffic on ports 587 and 465.

    You can verify the certificate chain from a terminal:

    A successful verification shows Verify return code: 0 (ok).

    Authentication failures

    • Ensure you are using the account ID as the username and the SMTP password as the password from the Simply Send Dashboard.
    • Confirm that your sending domain is verified and that SMTP relay access has been enabled for your account.
    • Use PLAIN or LOGIN authentication. CRAM-MD5 is not supported.

    Connection timeouts

    • Verify outbound access to smtp.simplysend.email on ports 587 and 465.
    • Ensure TLS 1.2 or higher is enabled. Older TLS versions are not supported.

    Security

    We support both STARTTLS on port 587 and Implicit TLS on port 465. TLS 1.2 or higher is required for all connections.

    Compliance