SendGrid

SendGrid rides a single API key for both transports, and its Event Webhook reports what happened after the handoff — confirmed deliveries, bounces, deferrals, and spam reports — which powers the delivered state, webhooks like mail.delivered and mail.bounced, and automatic suppressions. The delivery-events setup is one form on SendGrid’s side.

Before you start

• A SendGrid account with your sender domain authenticated under Settings → Sender Authentication — see Deliverability for what each record proves.
• An API key with Mail Send access (Settings → API Keys → Create API Key, restricted access is enough).

Add the account in Mailway

1. Add the provider.

   In the console, open Providers → New provider, pick SendGrid and paste the key — secrets are encrypted at rest. The one key gives the account both transports: mail that reaches Mailway’s SMTP relay goes on over SendGrid’s SMTP server (smtp.sendgrid.net:465, as the literal user apikey), byte-for-byte, and HTTP API and console mail go over SendGrid’s API.

   Tip

   Leave Send via on Auto. Set to API only, relayed mail can’t keep its bytes — SendGrid’s API is structured-only — so it skips the account unless a project admin enables re-encoding on the attachment, and a re-encoded copy may not be 100% identical to the original.

2. Attach it to a project.

   Open the project, attach the provider, and position it in the failover order. Send something — the provider health panel starts filling in.

Delivery events

Without delivery events, SendGrid only reports that it accepted the mail. With them, SendGrid tells Mailway what happened afterwards.

1. Open delivery tracking. In the console, open the provider → Delivery tracking (beside Configure). Mailway creates the provider’s webhook URL and shows it ready to copy. The URL contains a per-provider secret — treat it like a password (regenerating it at the bottom of the dialog revokes the old one instantly).

2. Create the Event Webhook in SendGrid. Settings → Mail Settings → Event Webhooks → create a new webhook:

   • Post URL: the URL you copied.
   • Actions to be posted: tick Delivered, Deferred, Bounced, Dropped, and Spam Reports. Processed and the engagement events (opens, clicks, unsubscribes) can stay off — Mailway doesn’t track engagement, so those events are ignored.

3. Store the verification key (required). Under the webhook’s security features, enable Signed Event Webhook and copy the Verification Key. Paste it into the dialog’s Paste the signing secret step (SendGrid verification key) and save. Mailway accepts only events that carry SendGrid’s valid signature with a timestamp within five minutes: until the key is stored, every event sent to the URL is refused.

What each event does in Mailway

SendGrid event	Mailway outcome
Delivered	The mail turns delivered (confirmed by the provider’s event).
Bounce	The mail turns bounced; the address is auto-suppressed for the project.
Bounce (blocked)	Recorded as soft_bounced (temporary; a later delivery outranks it). A block is not a verdict.
Deferred	Recorded as soft_bounced (temporary; a later delivery outranks it). SendGrid is still retrying.
Spam Report	The mail turns complained; the address is auto-suppressed.
Dropped	Recorded as dropped: SendGrid refused the message before sending. The mail keeps its state.

Note

Events correlate to mails through the id SendGrid returned when the mail was handed off — the API’s X-Message-Id, or the SMTP relay’s queued as reply — which is the first part of every event’s sg_message_id. Both transports correlate; an uncorrelated event is still recorded and visible, just not pinned to a specific mail.

Check the connection

• Connection check. The provider page’s connection check logs in over SMTP and reads the key’s permissions over the API, without sending anything.
• Delivery events. Save the webhook and use SendGrid’s test button on it: the sample events are acknowledged, and the Delivery tracking dialog’s last step ticks when they arrive. After a real send, the mail’s timeline shows the delivered or bounced step with SendGrid’s own response details attached.

What SendGrid changes

Not tested yet. What SendGrid changes before delivery will appear in What providers change once it is.

Limits

Your SendGrid plan’s own sending limits apply. Mailway adds none for SendGrid beyond your Mailway plan’s quotas.