How To Migrate From v2 to v3 Mail Send

If you are currently using the Web API v2 mail send endpoint, we recommend that you upgrade to the latest version.

To upgrade your authentication credentials from username and password to API keys, please see our authentication update guide.

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

  • Simple, intuitive, and 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 quickly.

What do you need to migrate?

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.

JSON Schema

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.

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:

subject=Hello, World!&
text=Hello, World!&

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

  "personalizations": [
      "to": [
          "email": ""
      "subject": "Hello, World!",
      "send_at": 1459728000
  "from": {
    "email": ""
  "content": {
    "type": "text/plain",
    "value": "Hello, World!"

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.

Requirements and Limitations

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 simply 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:

  "attachments": [
      "content": "[BASE64 encoded content block here]",
      "type": "jpg",
      "name": "example_file",
      "filename": "example_file.jpg",
      "disposition": "inline",
      "content_id": "[THE CONTENT ID OF YOUR FILE]"

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

You may also visit our Support page.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more