SendGrid v3 API
Send email with Mail Send, build dynamic templates, manage contacts and lists, handle suppressions and read delivery stats.
CommunicationGuided#email#transactional-email#templates#contacts#suppressions
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Twilio SendGrid is an email delivery platform. Its v3 Web API sends transactional email with one JSON request (Mail Send), stores reusable dynamic templates, manages Marketing Campaigns contacts and lists, keeps suppression lists (bounces, blocks, spam reports, unsubscribes) and reports delivery statistics. This guided collection walks through those five areas in the order you set them up.
Get credentials
- Create an account at https://signup.sendgrid.com and finish the onboarding questions.
- Verify a sender identity: for a quick test use Single Sender Verification (Settings > Sender Authentication > Verify a Single Sender) and confirm the email it sends you; for production authenticate your whole domain with DNS records (Settings > Sender Authentication > Authenticate Your Domain). The
fromaddress of every send must match a verified sender or authenticated domain. - Create an API key: Settings > API Keys > Create API Key, give it a name, choose Full Access or Custom Access (for this collection: Mail Send, Template Engine, Marketing, Suppressions and Stats), then Create & View. The key is shown only once; paste it into
apiKey.
Docs: https://www.twilio.com/docs/sendgrid/ui/account-and-settings/api-keys and https://www.twilio.com/docs/sendgrid/for-developers/sending-email/sender-identity
Authentication
Every request sends Authorization: Bearer <API key> (the collection sets it for you). Bodies are JSON. A parent account can act for a subuser by adding the on-behalf-of header with the subuser's username.
Base URLs
| Region | Base URL |
|---|---|
| Global (default) | https://api.sendgrid.com/v3 |
| EU regional subusers | https://api.eu.sendgrid.com/v3 |
There is no separate sandbox host. To test a Mail Send body without delivering anything, set mail_settings.sandbox_mode.enable to true (see folder 2). The EU host needs a plan with an EU IP and an EU subuser.
Variables and run order
Fill apiKey, fromEmail (your verified sender) and toEmail (an inbox you own). Then run: 1. Start here (check the key's scopes), 2. Mail Send, 3. Dynamic templates (saves templateId; then re-run the template send in folder 2), 4. Contacts and lists (saves listId and jobId), 5. Suppressions (saves groupId) and 6. Stats.
Limits and pricing
Mail Send accepts up to 1,000 personalizations per request and scheduled sends up to 72 hours ahead. Contact upserts take up to 30,000 contacts or 6 MB per call and are processed asynchronously. Other endpoints are rate limited per endpoint; every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a 429 means wait until the reset time. Daily sending volume depends on your plan: https://sendgrid.com/en-us/pricing and https://www.twilio.com/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/rate-limits
Common errors
| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid body; errors[].field names the problem | Fix the field (for example a missing from or empty content). |
| 401 | Missing or wrong API key | Check apiKey; it must be the full key, sent as Bearer. |
| 403 | Key lacks the scope, or the from address is not a verified sender | Add the scope to the key, or verify the sender/domain. |
| 404 | Unknown ID (template, list, group) | Re-run the create request that saves the ID. |
| 413 | Body too large | Shrink attachments or split the send. |
| 429 | Rate limit for this endpoint | Wait for X-RateLimit-Reset, then retry. |
Links
- API reference: https://www.twilio.com/docs/sendgrid/api-reference
- Mail Send: https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send
- Dynamic templates: https://www.twilio.com/docs/sendgrid/ui/sending-email/how-to-send-an-email-with-dynamic-templates
- Contacts: https://www.twilio.com/docs/sendgrid/api-reference/contacts
- Suppressions: https://www.twilio.com/docs/sendgrid/api-reference/suppressions-suppressions
- Stats: https://www.twilio.com/docs/sendgrid/api-reference/stats
- Official OpenAPI files: https://github.com/twilio/sendgrid-oai
Endpoints 30
1. Start here
- GETList the key's scopes
/scopesReturns the permission scopes of the API key in use, for example mail.send or templates.read. Run it first: a 200 proves the key is valid, and a missing scope… - GETGet account information
/user/accountReads the account type (free or paid) and the sender reputation score of the account that owns the key. Handy to confirm you are talking to the account you… - GETList verified senders
/verified_sendersLists the Single Sender identities on the account with their from_email and whether each is verified. The from.email of a Mail Send must be one of these (or…
2. Mail Send
- POSTSend an email
/mail/sendSends one email. The body has three required parts: personalizations (who gets it: one object per envelope, each with its own to, cc, bcc, subject or template… - POSTValidate a send in sandbox mode
/mail/sendSame body as a normal send but with mail_settings.sandbox_mode.enable set to true: SendGrid checks the request and returns a response without delivering any… - POSTSend with a dynamic template
/mail/sendSends using a dynamic template (ID starts with d-, created in folder 3 and saved in templateId). Put the values for the template's Handlebars placeholders in… - POSTSend to several recipients separately
/mail/sendUses two personalizations objects so each person gets an individual copy with their own subject and does not see the other address. Recipients inside one to… - POSTSend with an attachment
/mail/sendAttaches a file by putting its Base64-encoded bytes in attachments[].content along with filename and MIME type. The sample attaches a tiny text file whose… - POSTCreate a batch ID
/mail/batchCreates a batch ID that you can attach to scheduled sends so they can later be paused or cancelled together through the scheduled-sends API. The new batch_id… - POSTSchedule a send
/mail/sendSchedules delivery with send_at, a Unix timestamp in seconds no more than 72 hours ahead, and tags it with batchId. A pre-request script sets sendAt to one…
3. Dynamic templates
- POSTCreate a dynamic template
/templatesCreates an empty transactional template. Set generation to dynamic to get Handlebars support (IDs start with d-); legacy is the older substitution style. The… - POSTAdd a template version
/templates/{{templateId}}/versionsAdds the content of the template: subject and html_content with Handlebars placeholders such as {{first_name}}, filled from dynamic_template_data at send… - GETList dynamic templates
/templatesLists templates, paged. page_size is required (1 to 200); generations filters to dynamic, legacy or both. Follow _metadata.next (it carries a page_token) to… - GETGet a template
/templates/{{templateId}}Reads one template with all of its versions, including the HTML and subject of each and the active flag. Uses templateId. Use it to check which version will…
4. Contacts and lists (Marketing Campaigns)
- POSTCreate a list
/marketing/listsCreates a Marketing Campaigns contact list by name. The id is saved to listId and used by the upsert request below, which adds the contacts to this list. - PUTAdd or update contacts
/marketing/contactsUpserts contacts, matched by email (or another identifier). Optional list_ids adds them to lists. The work is asynchronous: you get 202 with a job_id (saved… - GETCheck the import job
/marketing/contacts/imports/{{jobId}}Shows the status of the upsert job saved in jobId: pending, completed, errored or failed, with counts of created, updated and errored contacts and an… - POSTGet contacts by email
/marketing/contacts/search/emailsLooks up contacts by exact email address. The result is keyed by each email you asked for, with the full contact (including its id and list_ids); addresses… - POSTSearch contacts with SGQL
/marketing/contacts/searchSearches contacts with an SGQL query string (a SQL-like filter language). Emails are stored lower-case, so compare lower-case values. Only the first 50… - GETCount contacts
/marketing/contacts/countReturns the total number of contacts and the billable count on the account. A quick sanity check after imports and deletes, and the number your Marketing… - DELETEDelete contacts
/marketing/contactsDeletes contacts by ID (ids, comma-separated; here the contactId saved above). Like upserts, deletes run as an asynchronous job and return 202 with a job_id.…
5. Suppressions
- POSTCreate an unsubscribe group
/asm/groupsCreates an unsubscribe (suppression) group such as 'Order updates' or 'Newsletter', so people can opt out of one kind of mail but keep others. name and… - POSTAdd addresses to a group
/asm/groups/{{groupId}}/suppressionsSuppresses addresses for one unsubscribe group, as if they had clicked its unsubscribe link. Sends that carry this asm.group_id skip them; other mail still… - POSTAdd a global unsubscribe
/asm/suppressions/globalAdds addresses to the global unsubscribe list, which blocks all mail to them from the account (except sends that explicitly bypass unsubscribe management).… - GETList bounces
/suppression/bouncesLists addresses that hard-bounced, with the SMTP reason and a Unix created time. SendGrid drops later mail to them until you delete the bounce. Filter by time… - GETList blocks
/suppression/blocksLists addresses whose receiving server refused a message for a temporary or policy reason (for example content filtering or IP reputation). Unlike bounces,… - GETList spam reports
/suppression/spam_reportsLists recipients who marked your mail as spam. SendGrid stops sending to them; keep them off your lists to protect your sender reputation. Supports the same… - DELETERemove a bounce
/suppression/bounces/old.address@example.comDeletes one address from the bounce list so SendGrid will try delivering to it again, for example after the recipient fixed their mailbox. Change the address…
6. Stats
- GETGlobal email stats
/statsReturns counts such as requests, delivered, opens, unique_opens, clicks, bounces and spam_reports per period. start_date (YYYY-MM-DD) is required; end_date… - GETStats for a category
/categories/statsSame metrics split by the categories you set on sends (up to 10 per request, repeat the parameter). Here it reports the order-shipped category used in folder…
API details
- Base URL
https://api.sendgrid.com/v3https://api.eu.sendgrid.com/v3- Authentication
- A bearer token in the Authorization header
- Operations
- 30 operations on 30 pathsPOST 15GET 12DELETE 2PUT 1
- Main resources
- 1. Start here 32. Mail Send 73. Dynamic templates 44. Contacts and lists (Marketing Campaigns) 75. Suppressions 76. Stats 2
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-18 - Links
- Documentation
How to test the SendGrid v3 API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the SendGrid v3 API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “List the key's scopes” (GET /scopes), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the SendGrid v3 API?
Send email with Mail Send, build dynamic templates, manage contacts and lists, handle suppressions and read delivery stats. It is listed under Communication and has 30 endpoints.
Who publishes the SendGrid v3 API?
It is listed from SendGrid's public API description (an OpenAPI document), not published by SendGrid on Swastik Codes. Anyone who controls sendgrid.com can claim the profile by adding a DNS TXT record.
What is the base URL of the SendGrid v3 API?
Its description lists 2 base URLs: https://api.sendgrid.com/v3, https://api.eu.sendgrid.com/v3. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the SendGrid v3 API?
With A bearer token in the Authorization header.
How many endpoints does the SendGrid v3 API have?
30 operations on 30 paths (15 POST, 12 GET, 2 DELETE, 1 PUT). The largest groups are 1. Start here, 2. Mail Send, 3. Dynamic templates, 4. Contacts and lists (Marketing Campaigns).
Is forking the SendGrid v3 API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.