Migrate from Twilio SendGrid API v2 to v3

Before starting the migration, familiarize yourself with the v3 API documentation. The v3 API has different endpoints, request formats, and authentication methods compared to the v2 API. Understanding these differences is crucial for a successful migration.

The v3 API uses an API key for authentication. Ensure you have generated an API key from the SendGrid dashboard or via API and update your code to use this key in the HTTP Authorization header as a Bearer token.

Authorization: Basic <base64-encoded-credentials>

or

https://sendgrid.com/api/stats.get.json?api\_user=yourusername\&api\_key=yourpassword\&days=1

Identify all the v2 API endpoints you are currently using and find the corresponding v3 endpoints. For example, if you are using the /api/mail.send.json endpoint in v2, the equivalent in v3 would be /v3/mail/send. At the end of this migration guide, you will find a mapping of all of the v2 and v3 API endpoints.

For specific instructions on migrating the send email endpoint, refer to the How To Migrate From v2 to v3 Mail Send guide.

Change the base URL in your API requests from the v2 base URL to the v3 base URL. For example:

The v3 API typically uses JSON for both request payloads and responses. Ensure that your requests are sending JSON payloads and that your code is prepared to parse JSON responses. Below are examples demonstrating how to update your request formats:

v2 API cURL Request Example:

In the v2 API, you might send an email using a cURL command like this:

1
curl -X POST "https://api.sendgrid.com/api/mail.send.json" \
2
  -d "api_user=yourusername" \
3
  -d "api_key=yourpassword" \
4
  -d "to=example@example.com" \
5
  -d "from=you@yourdomain.com" \
6
  -d "subject=Hello" \
7
  -d "text=Testing SendGrid"

This command sends a form-encoded POST request to the SendGrid v2 API endpoint.

v3 API cURL Request Example:

In the v3 API, the equivalent request using JSON would look like this:

1
curl -X POST "https://api.sendgrid.com/v3/mail/send" \
2
  -H "Authorization: Bearer <your-api-key>" \
3
  -H "Content-Type: application/json" \
4
  -d '{
5
    "personalizations": [
6
      {
7
        "to": [
8
          {
9
            "email": "example@example.com"
10
          }
11
        ],
12
        "subject": "Hello"
13
      }
14
    ],
15
    "from": {
16
      "email": "you@yourdomain.com"
17
    },
18
    "content": [
19
      {
20
        "type": "text/plain",
21
        "value": "Testing SendGrid"
22
      }
23
    ]
24
  }'

This command sends a JSON payload to the SendGrid v3 API endpoint, using the Bearer token for authentication.

For handling responses, ensure your application is set up to parse JSON responses from the v3 API. The cURL command itself will not handle responses beyond displaying them in the terminal, but you can redirect the output to a file or another application component that processes JSON.

v3 Response Handling:

In practice, you might capture the response like this:

1
curl -X GET "https://api.sendgrid.com/v3/stats?start_date=2023-01-01&end_date=2023-01-02" \
2
  -H "Authorization: Bearer <YOUR_API_KEY>" \
3
  -o response.json

This command retrieves email statistics for the specified date range and saves the response to a file named response.json. The file is saved in the current working directory where the cURL command is executed. You can review or process this file using another script or application.

These examples show how to transition from v2 to v3 requests using cURL and how to adapt to the JSON-based format of the v3 API. Always ensure your authentication and API key management practices align with Twilio SendGrid's security recommendations.

The v3 API might use different query parameters compared to the v2 API. Update your requests to use the correct query parameters for filtering, pagination, and other functionalities as per the v3 API documentation.

Compare the v3 API rate limits with the v2 API rate limits. Make sure to handle rate limits appropriately in your code to avoid disruptions.

Before fully switching over to the v3 API, test your updated integration thoroughly. Ensure that all functionalities are working as expected and that the data you receive from the v3 API is correct.

After migrating to the v3 API, monitor your application closely for any issues. If you encounter any problems, use the error messages and status codes provided by the v3 API to debug and resolve issues.

Finally, update any internal documentation and training materials to reflect the changes made during the migration. This will help your team to understand and maintain the new integration.

Specific details may vary based on the particular features of the SendGrid v2 API you are using. Always refer to the official SendGrid v3 API documentation for the most accurate and detailed information.

In the v2 API, retrieving statistics for a subuser looks like this:

curl -X GET "https://api.sendgrid.com/v2-api/customer_subuser_api/stats?api_user=<YOUR_SENDGRID_USERNAME>&api_key=<YOUR_SENDGRID_APIKEY>&days=1&user=<MY_SUBUSER_NAME>"

This request retrieves statistics for the specified subuser over the past day. The request parameters, including authentication credentials, are passed as query parameters.

In the v3 API, retrieving global email statistics looks like this:

1
curl -X GET "https://api.sendgrid.com/v3/stats?start_date=2023-01-01&end_date=2023-01-02" \
2
-H "Authorization: Bearer <YOUR_API_KEY>"

This request retrieves global email statistics for the specified date range.