--- title: SendGrid API Implementation Guide for Product Teams | SendHQ description: Implement SendGrid with authenticated domains, scoped API keys, durable send records, verified event webhooks, and suppression-aware workflows. canonical: https://sendhq.cc/guides/sendgrid-api last-updated: 2026-08-24 --- # How should a product team implement the SendGrid API safely? Implement the SendGrid API behind a server-side mail service, using an authenticated sending domain and an API key limited to the Mail Send permission. Validate every message before calling \`POST /v3/mail/send\`, persist your own send record, and capture the response's \`X-Message-ID\`. Process signed Event Webhook payloads from their raw bytes, deduplicate events, and respect bounces, spam reports, and unsubscribes. Treat \`202 Accepted\`, receiving-server delivery, and inbox placement as separate states, with bounded retries for transient failures only. ## Define a narrow, legitimate sending job SendGrid's v3 Mail Send API is a provider endpoint for outbound email, not a general-purpose user mailbox. Put it behind a trusted application service or queue worker and define which product events may create messages, such as an account verification, receipt, security notice, or requested notification. Do not expose the provider key to browsers, mobile clients, templates, prompts, or logs. Separate transactional messages from consent-dependent campaigns at the data-model level so recipient expectations, preference handling, and reputation can be operated independently. Before implementation, decide who owns the sender domain, who approves templates, which environments can send externally, and which recipients are permitted in development. This scope becomes the boundary for API-key permissions, domain setup, audit records, alerts, and incident response. It also makes a provider migration possible because product code asks for an approved email operation instead of constructing arbitrary SendGrid requests throughout the application. ## Authenticate a dedicated sending domain Configure SendGrid Domain Authentication for a domain or purpose-specific subdomain you control, then publish exactly the DNS records generated for that identity and verify them in SendGrid. The provider documentation notes that subdomains do not inherit an authenticated parent identity, so verify the actual domain used in From addresses. Review existing SPF and DMARC records before changing DNS; do not create a second SPF policy for the same hostname or replace an organization's existing DMARC policy without its owner. Keep transactional and promotional traffic on deliberately chosen identities when their audiences and risk differ. Confirm the visible From address, return path, DKIM signing domain, reply path, and link branding behavior in a received test message. Authentication establishes authorized identity and alignment signals, but it does not determine the receiving system's final folder. Continue monitoring bounces, complaints, recipient expectations, and content after DNS verification succeeds. ## Issue least-privilege API keys per environment Create a Custom Access API key with only the permissions the workload needs, normally Mail Send access for a sending worker. Do not give a routine sender Full Access to templates, suppressions, teammates, statistics, IP configuration, or account administration. Use separate keys for development, staging, and production, with names that identify the owning service and rotation purpose. SendGrid displays a new key once, so place it directly into the environment's secret manager and never copy it into source control or a shared document. At runtime, read it from secret-backed configuration and pass it only in the \`Authorization: Bearer\` header over HTTPS. Test key rotation as an operational sequence: create a replacement with equivalent narrow permissions, deploy the replacement, verify successful controlled traffic, then revoke the old key. Alert on unexpected 401 or 403 responses because they can indicate a missing key, a revoked credential, a permission mismatch, or an unsafe configuration change. ## Build and record each Mail Send request Create one internal outbound record before contacting SendGrid. Give it a stable application event key, tenant, sender identity, approved recipients, message class, template version, and state. Construct the provider payload from that record using \`personalizations\`, \`from\`, \`subject\`, and at least one supported content part or an approved dynamic template. Validate address syntax, recipient count, attachment size, template data, and custom headers before the network call. SendGrid's current Mail Send overview limits total request size including attachments to less than 30 MB and total recipients across To, Cc, and Bcc to no more than 1,000. Smaller, purpose-specific requests are easier to audit and recover. On a \`202 Accepted\` response, capture the \`X-Message-ID\` header and attach it to the outbound record. Do not put personal data in categories or unique arguments; SendGrid warns that those values can be retained and viewed outside the protections expected for message content. ## Verify and process the Event Webhook Configure the SendGrid Event Webhook on an HTTPS endpoint that can retain the raw request body. Enable cryptographic signing, OAuth 2.0, or both. For signed delivery, verify the timestamp and \`X-Twilio-Email-Event-Webhook-Signature\` against the exact raw bytes before parsing JSON; Twilio warns that re-serializing the payload can change bytes and invalidate verification. Reject unauthenticated input, apply a reasonable request-size limit, and prevent replay according to the timestamp policy chosen by the team. After verification, enqueue or durably store the event batch before returning success. Deduplicate with \`sg_event_id\`, then correlate \`sg_message_id\`, the stored \`X-Message-ID\`, and a non-sensitive internal correlation value. Make state transitions monotonic so a delayed processed event cannot overwrite a later delivered or bounce result. Keep the original provider event in restricted storage for troubleshooting, but minimize retention of addresses, response text, and engagement data to what the product and policy actually require. ## Model acceptance, delivery, and placement precisely SendGrid's HTTP \`202 Accepted\` means the request was accepted and queued for processing. It does not say that the destination accepted the message. A \`processed\` webhook event means SendGrid accepted the message and can attempt delivery. A \`delivered\` event means SendGrid reports that the receiving mail server accepted it, often with an SMTP response. That still does not establish inbox placement, because the receiving system can categorize accepted mail into an inbox tab, quarantine, junk folder, or another location. Keep these states separate in storage and user interfaces: requested, provider accepted, processed, deferred, receiving server accepted, bounced, dropped, complained, or suppressed. Avoid translating every non-error HTTP response into “delivered.” Engagement signals such as opens are also not delivery proof and can be affected by privacy features. Precise state names make support investigations, retries, and deliverability decisions safer. ## Classify failures before retrying Handle provider errors by class rather than retrying every non-202 response. A 400 usually requires correcting the payload, sender, template data, or reserved headers. A 401 points to authentication; a 403 can indicate insufficient permission or account policy; a 413 requires reducing message size. SendGrid documents per-endpoint rate-limit headers and returns 429 when the refresh-period allowance is exhausted, so delay until the reset time and add jitter instead of creating synchronized retries. Retry 5xx and transport failures with exponential backoff, a finite attempt count, and an operational alert. Ambiguous timeouts need special care: the provider may have accepted the request even though the client missed the response. Hold the outbound record in an unknown state, look for correlated events, and require a deliberate reconciliation rule before resending. Provider APIs do not remove the need for product-level duplicate prevention. Never retry a known permanent bounce, invalid recipient, unsubscribe, or spam-report destination as a transient infrastructure error. ## Respect suppressions and recipient choices Ingest bounce, dropped, spam-report, unsubscribe, and group-unsubscribe events into a recipient-safety model. SendGrid supports global suppressions and unsubscribe groups for different message classes. Associate each promotional or optional message with the correct group, provide an understandable preference path, and stop sends when the relevant suppression applies. Do not use suppression-bypass options as a routine delivery technique. A product-critical message may need a separately documented legal and operational policy, but that policy should not silently override a person's promotional choice or a provider reputation safeguard. Protect support tools that remove a suppression with strong authorization, a visible reason, and an audit trail. Track permanent and temporary delivery failures separately, and review any manual reactivation before the next send. These controls protect recipients and reduce repeated attempts to destinations that have already rejected or declined the traffic. They also keep transactional sending from inheriting unsafe campaign behavior. ## Test the full lifecycle before production traffic Start with a non-production SendGrid key and a controlled authenticated subdomain. Verify DNS, then send plain-text and HTML variants to inboxes the team owns. Confirm the \`202\` response and \`X-Message-ID\`, and verify that signed webhook events correlate to the local outbound record. Exercise invalid payload, revoked key, missing permission, oversized attachment, rate-limit, deferred, bounce, dropped, and duplicate-event paths without using real customer addresses. Confirm that webhook verification rejects a modified body and that the handler acknowledges only after durable capture. Test key rotation, template rollback, suppression enforcement, and an ambiguous client timeout. Add dashboards for request failures, event lag, deferrals, bounces, spam reports, and webhook signature failures, with tenant and message identifiers but no credentials or full content. Finally, review current SendGrid documentation and account limits at launch because plan entitlements, regional features, quotas, and provider policies can change independently of application code. ## Compare provider-specific dependencies A direct SendGrid integration is appropriate when a team deliberately depends on SendGrid-specific request fields, templates, account controls, webhook formats, suppressions, and operational ownership. SendHQ's public documentation describes a workspace-scoped email API with verified-domain sending, inbound email, hosted templates, delivery events, suppressions, and a web dashboard. Before migrating, review the two providers' payloads, events, identity controls, suppressions, regional requirements, and stored provider identifiers. ## Frequently asked questions **Does SendGrid 202 Accepted mean the email was delivered?** No. It means SendGrid accepted the API request for processing. Use Event Webhook delivery events to learn whether the receiving server accepted the message, and keep inbox placement as a separate outcome that the API response does not establish. **What permission should a SendGrid sending key have?** Use a Custom Access key limited to the Mail Send capability required by the worker. Avoid Full Access for routine sending, and use separate secret-managed keys for development, staging, production, administration, and any other workload with materially different authority. **How should a SendGrid Event Webhook signature be verified?** Retain the exact raw HTTP body, read the Twilio signature and timestamp headers, and verify them before JSON parsing or re-serialization. Apply replay protection, reject failed verification, then durably store or enqueue the event batch before acknowledging delivery. **Should a product retry every failed Mail Send request?** No. Fix payload, authentication, authorization, size, and permanent-recipient errors instead of retrying them. Delay 429 responses until the documented reset, retry transient network and 5xx failures with bounded backoff, and reconcile ambiguous timeouts before resending. **Can SendGrid suppressions be bypassed for transactional email?** SendGrid exposes bypass controls, but a product should not use them routinely. Separate message classes, honor the applicable unsubscribe or suppression, and require documented authorization and audit history for any exceptional reactivation or policy-specific send decision. **What should a team assess before comparing SendGrid and SendHQ?** Compare the providers' payloads, events, identity controls, suppressions, regional requirements, and stored provider identifiers before planning a migration. ## Sources - [Mail Send API Overview](https://www.twilio.com/docs/sendgrid/api-reference/mail-send) — Twilio SendGrid - [Mail Send endpoint](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send) — Twilio SendGrid - [SendGrid API Keys](https://www.twilio.com/docs/sendgrid/ui/account-and-settings/api-keys) — Twilio SendGrid - [Configure domain authentication](https://www.twilio.com/docs/sendgrid/ui/account-and-settings/how-to-set-up-domain-authentication) — Twilio SendGrid - [Twilio SendGrid Event Webhook Overview](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/twilio-sendgrid-event-webhook-overview) — Twilio SendGrid - [Event Webhook Reference](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/event) — Twilio SendGrid - [Event Webhook security features](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features) — Twilio SendGrid - [SendGrid API rate limits](https://www.twilio.com/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/rate-limits) — Twilio SendGrid - [SendGrid suppressions](https://www.twilio.com/docs/sendgrid/ui/sending-email/index-suppressions) — Twilio SendGrid - [SendGrid API returns 202 Accepted but does not send email](https://help.twilio.com/articles/47587887489563) — Twilio Help Center - [X-Message-ID](https://www.twilio.com/docs/sendgrid/glossary/x-message-id) — Twilio SendGrid - [SendHQ OpenAPI Contract](https://sendhq.cc/openapi.json) — SendHQ ## Continue learning - [Email API Implementation Guide for Product Teams](https://sendhq.cc/guides/email-api.md): Design a safe email API integration with verified domains, queued sends, stable identifiers, controlled retries, delivery events, suppression, and tenant isolation.