Delivery options
What happens when an email cannot be delivered right away, and how to change it per email: how long we keep retrying, and whether to send to an address that hard bounced before.
All options are optional. Without them every email follows the defaults below. They go in the body of Send Email, or as headers when you send through SMTP.
How retries work
A permanent rejection, like an address that does not exist, is final and is not retried. These are retried for you:
Greylisting
The receiving server answers "try again later" to a sender it has not seen before.
We try again from the same IP after 5, 10, 20, 40, 60 and 60 minutes (about 3 hours in total).
Temporary errors
A 4xx reply, too many connections, or a connection that drops mid-send.
We try again a few times with a pause between attempts. How many times and how long to wait depends on the error, unless you set it.
retryUnavailable · retryUnavailableSecondsReceiving server down
The recipient's mail server does not accept connections at all.
We wait for it to come back without using up your retries. If it is still down after 24 hours, the email is marked as bounced.
Rate limited
The mailbox provider (Outlook, Yahoo, AOL…) asks us to slow down.
The email waits and is tried again every 30 minutes, possibly from another IP. By default we keep trying for 25 cycles (about 12 hours).
retryRateLimitedRetry options
You set the limit, we set the ceiling. A value outside the range is adjusted to the nearest allowed value, and the response tells you in warnings. Field names are not case-sensitive: retryRateLimited and retry_rate_limited are the same.
retryRateLimitedintegeroptionalHow many 30-minute rate-limit cycles to wait before giving up. 0 gives up on the first rate limit. Use a low value for time-sensitive emails, like login codes.
Range0 – 24Default 25 cyclesSMTPX-Sendcorex-Retry-Rate-LimitedretryUnavailableintegeroptionalHow many times to try again after a temporary error. 0 fails on the first one.
Range0 – 30Default Depends on the error (up to 10)SMTPX-Sendcorex-Retry-UnavailableretryUnavailableSecondsintegeroptionalHow many seconds to wait between those attempts.
Range10 – 3600Default Depends on the errorSMTPX-Sendcorex-Retry-Unavailable-SecondsignoreHardBouncebooleanoptionalSend even if the address hard bounced in the last 90 days. One try per address, and it is turned off for 7 days after 3 misses in 24 hours. See Known hard bounces below.
Rangetrue · falseDefault falseSMTPX-Sendcorex-Ignore-Hard-Bounce
Known hard bounces
When an address hard bounces (the mailbox does not exist), we remember it for 90 days. Sending to it again would only hurt your sender reputation, so we don't connect to the receiving server again:
Without the Hard Bounce Shield
Marked as bounced
The email is not sent and is logged as a bounce. It counts in your bounce rate.
With the Hard Bounce Shield
Suppressed
The email is not sent and is logged as Suppressed. It uses a credit, but it does not count as a bounce. You still get the bounced webhook, with suppressed: true, so every email ends with a final event.
Mailbox full
A full mailbox is a temporary error, so the address is not remembered the first time. If the same address comes back as full on 3 emails in a row, with no delivery in between and less than 30 days between them, we treat it as a hard bounce from then on. One successful delivery resets the count.
Send anyway
If you know the mailbox exists now (the recipient fixed it, or it was a temporary problem on their side), set ignoreHardBounce: true. The email is sent normally. If it is delivered, the address is removed from the list and you don't need the option for it anymore.
Limits
The option means "this mailbox exists now". When that turns out not to be true, it stops working:
One try per address
If the email hard bounces again, it counts as a bounce, the address is remembered for another 90 days, and the option is ignored for that address until then.
3 misses in 24 hours
If 3 emails sent with the option hard bounce again, each less than 24 hours after the previous one, the option is turned off for your account for 7 days. Your emails keep going out; known hard bounces are just skipped as usual.
When the option was ignored, the reason starts with ignore_hard_bounce revoked: and says why.
Use it per email, not by default. Mailbox providers watch how often you send to addresses that don't exist. Turning it on for every send removes the protection.
Choose the sending IP
With dedicated IPs, we pick which of your IPs sends each email using the settings on your IP page. To decide yourself, set sendingIp to one of your dedicated IPs. The email goes out from that IP only, from the first attempt to the last retry.
sendingIpstringoptionalAn IPv4 or IPv6 address that is one of your dedicated IPs and is active. Any other value rejects the email.
Default Chosen by your IP settingsSMTPX-Sendcorex-Sending-IPMCPsending_ip
{
"to": "customer@example.com",
"from": "billing@yourdomain.com",
"senderName": "My App",
"subject": "Your invoice",
"body": "<p>Your invoice is ready.</p>",
"sendingIp": "203.0.113.10"
}What it overrides
These settings from your IP page don't apply to an email sent with sendingIp. Emails without it keep following them.
Which IP sends
We normally take turns between your dedicated IPs. The email goes out from the one you chose instead.
IPv4 and IPv6 routing
The IPv4/IPv6 split from your routing settings is skipped. An IPv6 address sends over IPv6, an IPv4 address over IPv4.
Failover when rate limited
We normally retry from another of your dedicated IPs. The email waits on the IP you chose.
Blacklist Guard
If the IP gets listed, the email is not moved to a shared IP. It waits on the IP you chose.
Scheduled emails
The IP is saved with the email and used when it goes out, even if your IP settings change in between.
Errors
API
400 INVALID_SENDING_IPThe value is not an IP address, or it is not one of your active dedicated IPs. The email is not queued.SMTP
550 5.7.1Same check on the X-Sendcorex-Sending-IP header. The message is rejected at the end of DATA.MCP
INVALID_SENDING_IPSame check on the sending_ip argument of email_send.
A fixed IP waits instead of switching.If the provider slows that IP down or it gets listed, the email waits on the same IP until it goes out or the retries run out. For emails that can't wait, leave sendingIp out and let us pick.
Example
A login code is useless after a few minutes, so don't keep it waiting for hours.
import axios from 'axios';
const response = await axios.post(
'https://mail.sendcorex.com/v3.0/send',
{
to: 'user@example.com',
from: 'noreply@yourdomain.com',
senderName: 'My App',
subject: 'Your login code',
body: '<p>Your code is <b>482913</b></p>',
retryRateLimited: 4, // give up after 4 rate-limit cycles (~2 h)
retryUnavailable: 5, // up to 5 retries on temporary errors
retryUnavailableSeconds: 30, // 30 s between them
ignoreHardBounce: true, // send even if this address hard bounced before
},
{
headers: { Authorization: process.env.SENDCOREX_API_KEY },
}
);
console.log(response.data.id, response.data.warnings);Response with an adjusted value
Here retryRateLimited was sent as 40. The email is still queued, with 24.
Email queued, with a warning
{
"success": true,
"message": "Email queued successfully",
"code": "EMAIL_QUEUED_SUCCESS",
"id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
"ids": [
{ "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f", "recipient": "user@example.com" }
],
"recipients": 1,
"scheduledAt": null,
"warnings": ["retry_rate_limited 40 → 24"]
}SMTP headers
Sending through SMTP? Add the same options as headers. We read them and remove them before the email is delivered, so the recipient never sees them.
X-Sendcorex-Retry-Rate-Limited: 4 X-Sendcorex-Retry-Unavailable: 5 X-Sendcorex-Retry-Unavailable-Seconds: 30 X-Sendcorex-Ignore-Hard-Bounce: true X-Sendcorex-Sending-IP: 203.0.113.10
Webhook events
Follow retries as they happen with these webhook events:
- retrying
A temporary error happened and the email will be tried again. The reason says which attempt it is.
- failed
We gave up after the retries or the rate-limit cycles ran out.
- bounced
The receiving server rejected the email for good, or stayed down for 24 hours. Also sent when we skip a known hard bounce, with suppressed: true if you have the Hard Bounce Shield.