SendGrid

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

  1. Create an account at https://signup.sendgrid.com and finish the onboarding questions.
  2. 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 from address of every send must match a verified sender or authenticated domain.
  3. 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

RegionBase URL
Global (default)https://api.sendgrid.com/v3
EU regional subusershttps://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

StatusMeaningWhat to do
400Invalid body; errors[].field names the problemFix the field (for example a missing from or empty content).
401Missing or wrong API keyCheck apiKey; it must be the full key, sent as Bearer.
403Key lacks the scope, or the from address is not a verified senderAdd the scope to the key, or verify the sender/domain.
404Unknown ID (template, list, group)Re-run the create request that saves the ID.
413Body too largeShrink attachments or split the send.
429Rate limit for this endpointWait 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/v3
https://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

How to test the SendGrid v3 API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the SendGrid v3 API collection, without the publisher's secrets.
  3. 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.
  4. 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.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.