Relay Configuration Guide - Step-by-Step Setup for Ridgital Transactional Email

What to do

1. Create your Ridgital account.
2. Verify your email address.
3. Select and purchase a Relay package.
4. Confirm that the subscription is active.
5. Review your package limits before creating resources.

What your package controls

• Monthly and daily email volume.
• API and SMTP rate limits.
• Message and event retention.
• Applications, API Keys, SMTP credentials, and webhooks.
• Attachments and message-size limits.
• Tracking, suppressions, compliance features, and support level.

Create an Application

1. Open Relay → Applications.
2. Select Add Application.
3. Enter a recognizable name.
4. Add an optional description.
5. Create separate Applications for Production and Staging when their activity and credentials should remain independent.

Choose the correct scope

Where Relay provides a scope selector, associate the resource with a specific Application or select Account-wide when the resource must be shared across the organization.

Create an API Key

1. Open Account → API Keys.
2. Select Create API Key.
3. Enter a name that identifies its application and environment.
4. Optionally configure an expiration date.
5. Copy the generated key immediately.

Protect the generated key

• The complete API Key is displayed only once.
• Store it in a secrets manager or server-side environment variable.
• Never expose it in browser code, mobile applications, repositories, or logs.
• Revoking a key stops it immediately and cannot be reversed.

Validate API access

GET /relay/ping

Use this endpoint first to confirm API availability and validate the API Key.

Submit one message

POST /relay/send

A successful response means Relay accepted and queued the message. It does not mean delivery has completed.

Submit a batch

POST /relay/send/batch

Submit up to 100 messages in one request. Relay returns a separate result for each item.

Retrieve one message

GET /relay/messages/{message_id}

Retrieve the current canonical status and recorded lifecycle of a submitted message.

List submitted messages

GET /relay/emails

List and filter your submitted messages. Results are paginated.

Asynchronous processing

Delivery attempts, retries, bounce processing, suppressions, tracking events, and webhook notifications occur after the initial submission response.

Create the credential

1. Open Relay → SMTP Ingress.
2. Select Add Credential.
3. Enter a label identifying the application.
4. Create the credential.
5. Save the generated username and password immediately.

Configure the application

• Use the SMTP ingress host displayed in the portal.
• Use port 587.
• Use STARTTLS.
• Authenticate with the Relay-generated username and password.

Identification and status

• Name: identifies the connection in Relay.
• Active: determines whether Relay can use it.
• Default: identifies the intended primary connection.

Server connection

• Host: provider SMTP hostname.
• Port: provider SMTP port.
• Encryption: mode required by that port.

Authentication

• Username: SMTP username.
• Password: credential accepted by the SMTP server.
• When editing, leave the password blank to keep the current stored password.

Sender identity

• From Email: sender address associated with the configuration.
• From Name: sender display name.
• The provider must authorize the selected From Email.

Daily Limit

Maximum messages this Delivery SMTP configuration may send per day. Leave blank for no configuration-level daily limit.

Hourly Limit

Maximum messages this Delivery SMTP configuration may send per hour. Leave blank for no configuration-level hourly limit.

Required bounce fields

• Bounce Email Domain.
• IMAP Host.
• IMAP Port.
• IMAP Encryption.
• IMAP Username.
• IMAP Password.

Why this connection matters

A message can initially become delivered after SMTP handoff and later change to soft_bounced or hard_bounced after Relay processes a DSN from this mailbox.

Register a domain

1. Open Relay → Sender Domains.
2. Select Add Domain.
3. Enter the domain portion of the From address.
4. Review whether it is Verified or Unverified.
5. Contact Ridgital support when platform-side verification is required.

Domain enforcement

When sender-domain enforcement is enabled, messages using unregistered or removed domains may be rejected.

Registering a domain in Relay does not configure SPF, DKIM, or DMARC. Configure these records through your outbound email provider.

submitted and accepted

Relay received and accepted the message for asynchronous processing. Delivery has not yet been confirmed.

delivered

The configured Delivery SMTP server accepted the message for further routing. It does not guarantee inbox placement.

deferred and bounced

deferred represents a temporary delay. Later bounce processing can produce soft_bounced or hard_bounced.

suppressed and failed

A suppression prevented delivery, or message processing failed for another recorded reason.

trackOpens

Allows Relay to use a tracking-pixel request to record an open outcome.

trackClicks

Allows Relay to use tracked redirects to record supported link-click outcomes.

Automatic suppression sources

• Hard bounce.
• Supported complaint report.
• One-click unsubscribe.
• Compliance action.
• Another platform-defined deliverability condition.

Before removing a suppression

• Review the recipient address.
• Review the suppression reason.
• Review when and how it was created.
• Confirm the recipient may lawfully receive email again.

Verify payloads

Validate the HMAC-SHA256 signature supplied in X-Ridgital-Signature before trusting or processing an event.

Test delivery

Use Send Test, review recorded delivery attempts, and retry eligible failed deliveries from the portal.

Rotate the secret

Rotation invalidates the previous signing secret immediately. Coordinate the update with your receiving application.

Authoritative status

Webhook delivery is asynchronous. Use Email Logs or the Relay API as the authoritative source for recorded message state.

Recipient lookup and export

1. Open Relay → Compliance.
2. Enter one recipient email address.
3. Look up the associated Relay records.
4. Download JSON or submit an export request when available.
5. Review the request in Compliance history.

Recipient deletion

Deletion permanently removes applicable message content and event history. The request may require staff approval and cannot be reversed after completion.

Recipient deletion does not remove the recipient's suppression entry.

Account and access

• The subscription is active.
• User roles are correct.
• Sensitive accounts use 2FA.
• Production resources use the intended Application scope.

Submission

• The application uses the correct API or SMTP ingress credential.
• Secrets are stored securely.
• Unused credentials have been revoked.
• GET /relay/ping accepts the production API Key.

Delivery

• Delivery SMTP passes Test Connection.
• The correct configuration is Active and Default.
• The From Email is authorized.
• Daily and hourly limits are correct.
• The bounce mailbox is accessible.

Monitoring

• A real test message appears in Email Logs.
• The message reaches the expected SMTP handoff status.
• Sender Domains are registered.
• Webhook signatures are verified.
• Suppression behavior is understood.

TLS handshake error

The selected port expects a different encryption mode. Confirm whether the provider requires STARTTLS or implicit SSL/TLS.

535 authentication error

The SMTP or IMAP server rejected the credentials or authentication method. Verify the username, password type, and provider access policy.

Sender rejected

Confirm that the authenticated Delivery SMTP account may send using the configured From Email and sender domain.

Delivered but not in the inbox

Delivered confirms SMTP handoff, not inbox placement. Check your provider, recipient filtering, sender reputation, and later bounce updates.

Bounce not detected

Check the Bounce Email Domain, IMAP settings, credentials, mailbox routing, and feedback-loop destination.

Message suppressed

Review the suppression reason and source. Do not remove it merely to bypass a bounce, complaint, unsubscribe, or compliance action.