SendGrid and CodeWords: deliverability is the whole problem

Sending email is easy. Having it arrive is not, and the difference is where every hour of work on an email integration actually goes.

An API call that returns success means SendGrid accepted the message for delivery. It says nothing about whether a mailbox provider accepted it, whether it landed in a spam folder, or whether it was silently discarded. Building anything on email without understanding that gap produces a system that reports perfect health while customers do not receive their receipts.

What we'll cover

• Accepted is not delivered
• Authentication, which is not optional
• What SendGrid reaches
• Connecting it to CodeWords
• Seven automations worth building
• Separating transactional from marketing
• Suppressions, which are protecting you
• Shared or dedicated IPs
• Building it so it survives
• Limits worth knowing about
• What to build first
• Frequently asked questions

Accepted is not delivered

The event webhook is where the truth is, and the distinctions matter.

Processed means SendGrid has the message.

Delivered means the receiving server accepted it. This is the first event that means anything.

Bounced splits into hard and soft. Hard bounces are permanent — the address does not exist — and continuing to send to them damages your reputation. Soft bounces are temporary.

Deferred means the receiving server asked for a retry, and a sudden rise in deferrals to one provider is an early warning of a reputation problem.

Dropped means SendGrid did not attempt delivery, usually because the address is suppressed. It counts as a send in your own logs and nothing left the building.

Spam report is the most consequential event and the one to act on immediately.

Opens and clicks are unreliable individually — privacy features prefetch images and rewrite clicks — and are useful only in aggregate and only as a trend.

Anything treating a successful API response as a delivered email is measuring its own optimism.

Authentication, which is not optional

Three mechanisms decide whether your mail is treated as legitimate, and all three need to be right.

SPF lists who may send for your domain.

DKIM signs messages so the receiver can verify they were not altered and came from you.

DMARC tells receivers what to do when the first two fail, and gives you reports on what is being sent in your name.

Use a subdomain for sending. Sending from a subdomain separates your application's reputation from your corporate mail, so a bad campaign does not affect whether your invoices arrive.

Check it stays right. DNS records are changed by people who do not know what depends on them, and the symptom — mail quietly going to spam — is invisible until somebody complains.

An automation that verifies your authentication records daily is five minutes of work and catches a failure that otherwise takes weeks to notice.

What SendGrid reaches

The Mail Send API for individual and batched messages, with dynamic templates and personalisations.

Dynamic templates hold the content, so changing an email does not require a deployment.

The event webhook posts delivery events to you, which is the primary source of truth about what happened.

Suppression management covers bounces, blocks, spam reports, and unsubscribes, all of which can be listed and, carefully, modified.

Statistics endpoints provide aggregate metrics by day, category, and mailbox provider.

Inbound parse turns received email into a webhook, which is how you handle replies.

Validation checks addresses before sending on plans that include it.

Subusers and API keys segment sending, which is central to the separation described below.

Connecting it to CodeWords

CodeWords connects to more than 3,000 integrations, and the connection is made once and reused.

1. Open CodeWords and start a new automation.
2. Describe what should happen in plain language to Cody, the automation builder: what triggers the message, which template, and what to do with the events that come back.
3. Authorize the connection with an API key restricted to mail send, rather than a full-access key.
4. Describe the exceptions: a suppressed address, a hard bounce, a spam report, a template variable with no value.
5. Send to your own addresses across several providers before anything reaches a customer.

You describe the outcome; Cody builds it, connects it, and deploys it. The free plan covers light use, with Pro at $39 per month and Business at $100 per month as usage grows; details are on the pricing page.

Seven automations worth building

Event ingestion into your own records. Take the event webhook and write delivery outcomes against the customer, so support can see whether the receipt was actually delivered instead of guessing.

Authentication monitoring. Daily verification that SPF, DKIM, and DMARC records are intact. Cheap, and it catches the failure that is otherwise invisible.

Bounce and complaint handling. Hard bounces marked on the account so nothing sends there again, and spam reports escalated rather than logged.

Deliverability reporting by provider. Rates broken down by mailbox provider, because a problem usually appears at one provider first and an aggregate number hides it.

Sending anomaly detection. Volume far outside the normal range, which catches both a loop in your own code and a compromised key.

Reply handling through inbound parse. Replies to transactional mail routed to support rather than landing in a mailbox nobody reads, which is where they go by default.

Template change reporting. Who changed which template and when, since templates are edited outside your deployment process and nothing records it.

Separating transactional from marketing

The structural decision that protects the mail you cannot afford to lose.

Use separate subusers or separate accounts. Reputation is largely per sending identity, and mixing the two means a marketing campaign that generates complaints can affect password resets.

Use separate subdomains, so the separation is visible to receiving servers rather than only to you.

Restrict API keys by function. A key that can only send mail cannot modify suppressions or read statistics, which limits what a leaked key can do.

Never send marketing content on the transactional path. It is the fastest way to generate complaints against the identity that carries your receipts, and it is often done accidentally by adding a promotion to a confirmation email.

Report on them separately. Combined metrics conceal exactly the problem you need to see.

Suppressions, which are protecting you

Suppression lists exist to stop you damaging your own reputation, and the instinct to override them is usually wrong.

Hard bounces are permanent. Removing an address to try again is how sustained damage happens.

Spam reports must never be re-sent to. In many jurisdictions it is also a legal problem, not only a reputational one.

Blocks are often temporary and provider-specific, and they can be reviewed.

Unsubscribes are a customer instruction, and honouring them across systems rather than only in SendGrid is the part people get wrong.

Report the list rather than clearing it. A growing suppression list usually indicates a data quality problem upstream — stale addresses in your database — and clearing it treats the symptom.

Shared or dedicated IPs

The question that comes up as volume grows, and the answer is not always the expensive one.

Shared IPs pool your reputation with other senders, which is usually fine and means your occasional bad day is absorbed by everyone else's good ones.

A dedicated IP is your reputation alone, which is an advantage only if your volume is high enough and consistent enough to establish one.

Low volume on a dedicated IP is worse than shared. Mailbox providers need regular traffic to form a view, and sporadic sending from a dedicated address looks unfamiliar every time.

A new dedicated IP needs warming — volume increased gradually over weeks — and sending full volume on day one is how a new IP gets filtered immediately.

Separate IPs for transactional and marketing follow the same logic as separate subdomains, if your volume supports two.

The honest default: stay on shared unless your volume is genuinely high and steady, and if you move, plan the warm-up before you move rather than after delivery drops.

Building it so it survives

Make sending idempotent. Key on the event that triggered the message so a retry does not send twice, which is visible to the customer in a way most errors are not.

Verify the event webhook signature, since the endpoint is public and will receive things you did not send.

Handle at-least-once delivery and out-of-order events. A delivered event can arrive after a bounce event for the same message.

Validate template data. A missing variable renders an email with a gap in it, which is worse than not sending.

Report the outcome. Sent, delivered, bounced, and suppressed, by category, so the picture is real rather than the count of API calls that succeeded.

Limits worth knowing about

Rate limits and plan limits differ, and exceeding a plan's volume behaves differently from exceeding a rate limit.

Personalisations per request are capped, so bulk sends need batching.

Event webhook delivery is at-least-once with retries, and events can be delayed.

Statistics are aggregated, so per-message detail comes from the event webhook rather than the statistics endpoints.

Attachment size is limited, and a large attachment is better sent as a link in most cases anyway.

What to build first

Authentication monitoring: a daily check that your SPF, DKIM, and DMARC records are present and correct, alerting if they change. It sends nothing, it takes very little building, and it catches the failure mode where deliverability degrades quietly after somebody edits DNS for an unrelated reason.

Two habits make the difference. Check the actual published records rather than your configuration, since the whole point is catching a change made elsewhere. And alert to a channel a person reads daily, because a week of mail going to spam is expensive and entirely preventable.

Frequently asked questions

Why do emails vanish after the API returns success?

Because acceptance by SendGrid is not delivery. The message may be deferred, bounced, dropped for suppression, or accepted and filed as spam. The event webhook is where the actual outcome is, and nothing else tells you.

Should transactional and marketing mail share a sending domain?

No. Use separate subdomains and separate subusers. Reputation is largely per sending identity, and mixing them means a campaign generating complaints can stop password resets arriving.

Can I remove an address from the suppression list?

You can, and for hard bounces and spam reports you should not. Those suppressions exist to protect your reputation, and overriding them causes sustained damage that takes far longer to repair than it took to cause.

Are open rates reliable?

Not individually. Privacy features prefetch tracking images, which registers opens nobody made. Treat them as a trend at aggregate level and never as evidence that a specific person read a specific message.

How do I know deliverability is degrading?

Watch delivery rates by mailbox provider rather than in aggregate, and watch deferrals. Problems usually start at one provider, and an overall number stays healthy-looking while a significant share of your customers stop receiving mail.

Where do replies to transactional email go?

Nowhere, by default, which is a poor experience. Inbound parse turns replies into a webhook so they can be routed to support. People reply to automated mail constantly, whatever the header says.

What should an API key be allowed to do?

Only what that automation needs — usually mail send alone. A restricted key cannot modify suppressions or read statistics, which meaningfully limits the damage if it leaks.

Should we get a dedicated IP?

Only with high, steady volume. Low or sporadic volume on a dedicated IP performs worse than shared, because mailbox providers never build a stable view of it. If you do move, plan the warm-up in advance rather than sending full volume on the first day.

What causes a sudden rise in deferrals?

A receiving provider asking you to slow down, usually the first visible sign of a reputation problem or a volume spike. Watch deferrals by provider — they move before delivery rates do, which makes them the better early warning.

Related reading

• Mailchimp and CodeWords
• Twilio and CodeWords
• CodeWords integrations and templates