Skip to main content

​
Connect to Paubox Email API via SMTP

To send email through Paubox SMTP API, follow these steps:
1
Generate a Paubox Email API key from the Paubox Email API > API Keys page.
2
Configure the SMTP server host to smtp.paubox.com.
This is often labeled as the SMTP relay or outgoing mail server in most email clients.
3
Set your username to the literal string apikey.
Note:this should be the exact word "apikey", not the API key you generated.
4
Use your API key as the SMTP password.
5
Choose the appropriate port, typically 587, unless your network requires another.
Tip:If you’re pasting a base64-encoded API key, double-check for any extra spaces or line breaks.
These can inadvertently appear when copying from certain terminals or editors, and they will prevent authentication.
Since SMTP is a line-based protocol, even a stray newline can result in failure.

​
Available SMTP Ports

Choose the correct port based on your desired level of security:
  • For TLS connections, use:
    25 or 587
  • For SSL/TLS connections, use:
    465
Tip:If you’re not sure which one to use, 587 with STARTTLS is the most widely supported and recommended option.

​
Sending Mail via SMTP

Once your SMTP connection is set up, you’re ready to construct and send email messages using your preferred client, service, or library.
  • The MAIL FROM address must be on the domain your API key belongs to. Any other domain is rejected with 550 5.1.7 Unauthorized sender domain.
  • To send a message as a Paubox Secure Message (the recipient gets a pickup notification with a link), add an X-Force-Secure-Msg header to the message. The header name is case-sensitive.

​
Rate Limits

To avoid delivery interruptions, be aware of Paubox SMTP usage thresholds:
  • By default, a single IP address may open up to 500 SMTP connections per minute. Connections beyond that are refused with 421 4.7.0 Too many connections or commands. Try again later.; wait and retry.

​
Avoid Direct IP Usage

Always reference the host as smtp.paubox.com; do not use direct IP addresses.
Paubox’s infrastructure may change without warning, and relying on hardcoded IPs could cause unexpected delivery issues in the future.