Email

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.

i

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).

Automatic

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.

Change it withretryUnavailable · retryUnavailableSeconds

Receiving 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.

Automatic

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).

Change it withretryRateLimited

Retry 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.

  • retryRateLimitedintegeroptional

    How 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.

    Range 0 – 24Default 25 cyclesSMTP X-Sendcorex-Retry-Rate-Limited
  • retryUnavailableintegeroptional

    How many times to try again after a temporary error. 0 fails on the first one.

    Range 0 – 30Default Depends on the error (up to 10)SMTP X-Sendcorex-Retry-Unavailable
  • retryUnavailableSecondsintegeroptional

    How many seconds to wait between those attempts.

    Range 10 – 3600Default Depends on the errorSMTP X-Sendcorex-Retry-Unavailable-Seconds
  • ignoreHardBouncebooleanoptional

    Send 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.

    Range true · falseDefault falseSMTP X-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.

  • sendingIpstringoptional

    An 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 settingsSMTP X-Sendcorex-Sending-IPMCP sending_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_IP The 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.1 Same check on the X-Sendcorex-Sending-IP header. The message is rejected at the end of DATA.

  • MCP

    INVALID_SENDING_IP Same 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.

200

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.