How To Migrate From v2 to v3 Mail Send

With a few changes you will be able to take advantage of the improvements and added features provided by the v3 mail send endpoint, such as:

• Consistent request body format.
• Sandbox Mode allows you to test and validate your email.
• Improved error reporting and documentation.
• Extensive code examples in each of our libraries to help you integrate.

All you need to migrate from the v2 to v3 mail send endpoint is a SendGrid account.

If you are a new SendGrid user and haven't begun sending email yet, please go straight to our v3 Mail Send documentation to get started.

Some of the biggest improvements made to the mail send endpoint reside in the JSON schema used to format and submit the data payload for your email. While the v2 mail send endpoint relies on a combination of JSON and SendGrid's x-smtpapi headers, all content and metadata sent via the v3 mail send endpoint is defined using JSON within a single request body.

Below you will find a visual comparison of the v2 and v3 JSON schemas that highlights equivalent parameters between the 2 versions and any parameters that have been added or removed. Significant additions include the "personalizations", "sandbox_mode", and "bypass_list_management" parameters.

For a more detailed discussion of these new parameters, please visit the v3 Mail Send Overview.

Expand image

One of the more prominent changes you may notice, is that many of the settings that were previously handled by SendGrid's x-smtpapi are now defined explicitly within the JSON schema of the request body to the mail send endpoint.

Previously, the only way to specify custom handling instructions for your email was to include individual blocks of JSON for each "setting" or "app" that you wanted to use according to the SMTP API.

For example, if you wanted to schedule an email to be sent at a certain time using the v2 mail send endpoint, your request body would look like:

1
api_user=YOUR_USER_NAME&
2
api_key=YOUR_PASSWORD&
3
to=john.doeexampexample@example.com&
4
toname=John&
5
subject=Hello, World!&
6
text=Hello, World!&
7
from=from_address@example.com
8
x-smtpapi={"send_at":1459728000}

However, the equivalent API call for the v3 mail send endpoint would look like:

1
{
2
  "personalizations": [
3
    {
4
      "to": [
5
        {
6
          "email": "john.doeexampexample@example.com"
7
        }
8
      ],
9
      "subject": "Hello, World!",
10
      "send_at": 1459728000
11
    }
12
  ],
13
  "from": {
14
    "email": "from_address@example.com"
15
  },
16
  "content": {
17
    "type": "text/plain",
18
    "value": "Hello, World!"
19
  }
20
}

Notice that while the call to the v2 Mail Send endpoint does include JSON, it is only defined from within the x-smtpapi parameter, whereas the entire payload for the v3 Mail Send API Call is formatted in JSON.

There are few limitations and requirements differences between the v2 and v3 mail send endpoints, making it even easier to migrate your integration to the latest version.

Attachments are handled differently between the v2 and v3 Mail Send endpoints. When attaching files in an email sent over the v2 Mail Send endpoint, you needed to attach your file to the transport and specify the file names and content IDs of those files in your API call. Essentially, you specified which files you were attaching in the API call, but the files were actually sent differently.

When attaching files to an email sent over the v3 Mail Send endpoint, you must include the BASE64 encoded content of your file, file type, filename, disposition, and content_id for each file you are attaching. These are all defined as separate objects within the attachments array.

For example, when attaching a single file named "example_file.jpg", the attachments object would look like:

1
{
2
  "attachments": [
3
    {
4
      "content": "[BASE64 encoded content block here]",
5
      "type": "jpg",
6
      "name": "example_file",
7
      "filename": "example_file.jpg",
8
      "disposition": "inline",
9
      "content_id": "[THE CONTENT ID OF YOUR FILE]"
10
    }
11
  ]
12
}

More Resources For additional resources on the v3 Mail Send endpoint, please first visit our other documentation on the v3 Mail Send endpoint:

• V3 Mail Send Overview
• Upgrading your Authentication to API Keys
• SandBox Mode
• Errors
• Personalizations
• cURL Examples for Common Use Cases

You may also visit our Support page.