Skip to content
Pidgely Docs

Guides

SMTP relay

Send through smtp.pidgely.com on ports 587 or 465 with user pidgely and your API key as password. Examples for Nodemailer, Django, Rails, Laravel and Spring.

View as Markdown

If your framework or tool only speaks SMTP, send through Pidgely's submission server. Messages go through the same pipeline as the API: verified From domain, suppression list, quotas, DKIM signing and webhooks.

Setting Value
Host smtp.pidgely.com
Port 587 or 2587 with STARTTLS · 465 or 2465 with implicit TLS
Username pidgely
Password Your API key, pdg_…
Authentication PLAIN or LOGIN, TLS 1.2 or newer

Any valid API key works, including sending_access keys; a domain-restricted key can only send from its domain. Use ports 2587/2465 if your network blocks the standard ones.

Framework examples

Nodemailer
import nodemailer from 'nodemailer';

const transporter = nodemailer.createTransport({
  host: 'smtp.pidgely.com',
  port: 465,
  secure: true,
  auth: { user: 'pidgely', pass: process.env.PIDGELY_API_KEY },
});

await transporter.sendMail({
  from: 'Acme <hello@acme.com>',
  to: 'steve@example.com',
  subject: 'Hello over SMTP',
  html: '<p>It works!</p>',
  headers: { 'Pidgely-Idempotency-Key': 'welcome-42', 'X-Pidgely-Tags': 'category=welcome' },
});
Django
# settings.py
import os

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.pidgely.com"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "pidgely"
EMAIL_HOST_PASSWORD = os.environ["PIDGELY_API_KEY"]
DEFAULT_FROM_EMAIL = "Acme <hello@acme.com>"
Rails
# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: "smtp.pidgely.com",
  port: 587,
  user_name: "pidgely",
  password: ENV.fetch("PIDGELY_API_KEY"),
  authentication: :plain,
  enable_starttls_auto: true
}
Laravel
# .env (STARTTLS is negotiated automatically on port 587)
MAIL_MAILER=smtp
MAIL_HOST=smtp.pidgely.com
MAIL_PORT=587
MAIL_USERNAME=pidgely
MAIL_PASSWORD=pdg_your_key_here
MAIL_FROM_ADDRESS=hello@acme.com
MAIL_FROM_NAME="Acme"
Spring
# application.properties
spring.mail.host=smtp.pidgely.com
spring.mail.port=587
spring.mail.username=pidgely
spring.mail.password=${PIDGELY_API_KEY}
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true

Special headers

Header Effect
Pidgely-Idempotency-Key Deduplicates retries for 24 hours; a repeat returns the original message id. See Idempotency.
X-Pidgely-Tags: name=value,name2=value2 Sets tags ([A-Za-z0-9_-]{1,256} each).

Pidgely removes Bcc, Return-Path, DKIM-Signature, Received, Delivered-To, Authentication-Results, ARC-*, Feedback-ID, List-Unsubscribe-Post and the two headers above before sending, and adds Message-ID and Date when missing. Bcc recipients are taken from the SMTP envelope. Other headers (for example X-Entity-Ref-ID) pass through. SMTP mail uses the transactional stream.

Limits

  • Messages up to 40 MB.
  • Up to 50 recipients per message (after de-duplication).
  • Sending quotas apply as for the API.

Error replies

Reply Meaning
530 5.7.0 Authenticate first
535 5.7.8 Wrong username or API key
454 4.7.0 Temporary authentication failure; retry
550 5.6.0 Invalid message, including a From domain that is not verified
550 5.7.1 Not allowed: key restricted to another domain, account paused or suspended
452 4.5.3 Sending quota reached
451 4.7.0 Rate limited; retry later
451 4.3.0 Temporary failure; retry