SMTP Authentication Methods

Motorical supports multiple SMTP AUTH (and HTTPS send) alternatives to match your security requirements. Each Motor Block uses one active method at a time (set under SMTP Configuration → Configure).

Method Comparison

Method	Best For	Transport	Setup Time	Technical Level
Password	Email clients, scripts, general use	SMTP mail.motorical.com:2587	~2 min	Beginner
API Key	Web apps, automation over HTTPS	POST https://api.motorical.com/v1/send	~2 min	Developer
OAuth 2.0	Apps that need short-lived SMTP credentials	SMTP with access token as password (or XOAUTH2)	~10 min	Advanced
mTLS	High-security / compliance clients	SMTP + client certificate	~15 min	Expert

Password (Basic Auth)

Use your Motor Block SMTP username and a generated password.

SMTP Server: mail.motorical.com
Port: 2587 (STARTTLS) or 2465 (implicit TLS)
Username: [motor-block smtp username]
Password: [generated password — shown once]

Passwords are not re-displayed after creation. Generate a new one from Configure if lost.

API Key (HTTPS Send API)

Motor-block API keys authenticate POST https://api.motorical.com/v1/send, not SMTP password auth.

curl -X POST https://api.motorical.com/v1/send \
  -H "Authorization: ApiKey mk_live_YOUR_PREFIX_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "sender@yourdomain.com",
    "to": ["recipient@example.com"],
    "subject": "Test Email",
    "text": "Hello from Motorical!",
    "html": "<p>Hello from <strong>Motorical</strong>!</p>",
    "dryRun": true
  }'

• Header may also be X-Api-Key: mk_live_…
• Key format: mk_live_<prefix>_<secret> (full token shown once)
• from must use the Motor Block’s assigned domain
• At least one of text or html is required; to may be a string or array

OAuth 2.0

Motorical acts as the OAuth 2.0 authorization server for the Motor Block. You do not need Google, Okta, or another IdP. Your app (or a browser + curl) completes the authorization-code flow; the resulting access token is used as the SMTP password (PLAIN/LOGIN) or via XOAUTH2.

Endpoints

Step	URL
Authorize	https://motorical.com/api/oauth2/authorize
Token	https://motorical.com/api/oauth2/token
Validate (optional)	GET https://motorical.com/api/oauth2/validate (Bearer access token)

Setup (dashboard)

1. Open the Motor Block → SMTP Configuration → Configure → choose OAuth 2.0.
2. Create OAuth App (registers client_id, shows client_secret once, sets redirect URI — default https://motorical.com/oauth/callback).
3. Configure Now so the block’s active method is OAuth 2.0.
4. Test OAuth Flow (opens consent → Approve → exchanges code for tokens automatically when opened from Configure).
5. Use the access token as the SMTP password until it expires (~1 hour); refresh with grant_type=refresh_token or re-run Test OAuth Flow.

redirect_uri must match the registered value exactly.

Token exchange (manual)

curl -sS -X POST 'https://motorical.com/api/oauth2/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "code": "PASTE_CODE_HERE",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://motorical.com/oauth/callback"
  }'

Response includes access_token, refresh_token, expires_in, and motor_block.smtp_username.

SMTP send with access token

swaks --server mail.motorical.com --port 2587 --tls \
  --auth LOGIN \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_ACCESS_TOKEN' \
  --from 'noreply@yourdomain.com' \
  --to 'recipient@example.com' \
  --header 'Subject: OAuth2 SMTP test' \
  --body 'Access token used as SMTP password'

Gateway also advertises XOAUTH2. Host: mail.motorical.com, ports 2587 (STARTTLS) or 2465 (implicit TLS).

Notes

• Access tokens are JWTs issued for Motorical SMTP (iss / aud checked on the gateway).
• Client secret is shown once at create/regenerate — store it securely.
• Do not send OAuth access tokens to POST /v1/send; that endpoint expects Authorization: ApiKey mk_live_….

Mutual TLS (mTLS)

Client certificate and SMTP username/password over STARTTLS.

1. Download the certificate bundle from the Motor Block drawer (Download Certificates).
2. Import the P12 into your mail client, or use the PEM cert/key with your SMTP library.
3. Connect to mail.motorical.com:2587 with STARTTLS + client cert, then AUTH with username/password.

Quiet handshake check

printf 'QUIT\r\n' | openssl s_client -connect mail.motorical.com:2587 -starttls smtp \
  -cert ./client.crt -key ./client.key -quiet

Look for Verify return code: 0 and an SMTP banner; the process should exit without Ctrl+C.

Send test (swaks)

swaks --server mail.motorical.com --port 2587 --tls \
  --tls-cert ./client.crt --tls-key ./client.key \
  --auth LOGIN --auth-user 'YOUR_SMTP_USERNAME' --auth-password 'YOUR_SMTP_PASSWORD' \
  --from 'noreply@yourdomain.com' \
  --to 'recipient@example.com' \
  --header 'Subject: mTLS test' \
  --body 'mTLS test from Motorical'