# v2 Mail Send
> \[!WARNING]
>
> To access all the latest features and upcoming developments, please see our [v3 API](/docs/sendgrid/api-reference). For assistance with transitioning, refer to our [migration guide](/docs/sendgrid/for-developers/migration-guides/v2-to-v3-api).
This endpoint allows you to send email over SendGrid's Web API v2. For information about the latest mail send endpoint, please visit our [Web API v3 Mail Send documentation](/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/authentication). We encourage our current v2 API customers to [migrate](/docs/sendgrid/for-developers/sending-email/migrating-from-v2-to-v3-mail-send/) to the new endpoint, so they can take advantage of our latest features.
There are a number of [official SendGrid libraries](/docs/sendgrid/for-developers/sending-email/libraries) that will help you send email through the Web API v2. We recommend using these if possible. Check our [API Libraries page](/docs/sendgrid/for-developers/sending-email/libraries) to view a list of supported libraries.
## Parameters
| URI Parameter | Required | Requirements | Description |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| to | Yes | Must be a valid email address | Specify a recipient email as a single email with this parameter. To send to multiple emails, use an array to specify each email, for example: `to[]=a@mail.com&to[]=b@mail.com`. You can also use the `To` parameter in the x-smtpapi header to add additional recipients. If you use the API `to` parameter to specify a single recipient, that recipient is visible in the `For` field of the received header—so if you specify a single address, it should be an address that you are comfortable with your customer seeing. For example, use a generic email address in the `to` field that your customer is already going to see, like your `from` address. To completely omit the email showing up in the `from` header: either specify multiple addresses in the `to` field as an array, for example, `to[]=a@mail.com&to[]=b@mail.com`, or use the V3 mail send endpoint. |
| toname | No | Must be a string. If the `to` parameter is an array, `toname` must be an array with the exact number of array elements as the `to` field | Give a name to the recipient. This can also be passed as an array if the `to` parameter above is an array. Example: `toname[]=Alpha[]=Beta`. |
| x-smtpapi | No | Must be in valid JSON format | Please review the [SMTP API](/docs/sendgrid/for-developers/sending-email/building-an-x-smtpapi-header/) to view documentation on what you can do with the JSON headers |
| subject | Yes | Must be a valid string | The subject of your email |
| text | No | API call must include at least one of the `text` or `html` parameters. | The plain text content of your email message. |
| html | No | API call must include at least one of the `text` or `html` parameters. | The HTML content of your email message. |
| from | Yes | Must be a valid email address from your domain | This is where the email will appear to originate from for your recipient |
| cc | No | Must be a valid email address | This can also be passed in as an array of email addresses for multiple recipients. Example: `cc[]=a@mail.com&cc[]=b@mail.com`. |
| ccname | No | Must be a valid email address | This is the name be appended to the `cc` field. |
| bcc | No | Must be a valid email address | This can also be passed in as an array of email addresses for multiple recipients. Example: `bcc[]=a@mail.com&bcc[]=b@mail.com`. |
| bccname | No | Must be a valid email address | This is the name appended to the `bcc` field. |
| fromname | No | Must a valid string | This is the name appended to the `from` email field (i.e. your name or company name) |
| replyto | No | Must be a valid email address | Append a `reply-to` field to your email message |
| date | No | Must be a valid date | Specify the `date` header of your email. One example: "Thu, 21 Dec 2000 16:01:07 +0200". PHP developers can use: `date('r');` |
| files | No | Must be less than 7MB | Files to be attached. The file contents must be part of the multipart HTTP `POST`. Ex: `files[file1.jpg]=file1.jpg&files[file2.pdf]=file2.pdf` |
| content | No | Required for sending inline images | Content IDs of the files to be used as inline images. Content IDs should match the cids used in the HTML markup. Ex: `content[file1.jpg]=ii_139db99fdb5c3704` would correspond with the HTML `
` and `files[file1.jpg]` would contain the contents. |
| headers | No | Must be in valid JSON format without integers | A collection of key/value pairs in JSON format. This is specifically for non-SendGrid custom [extension headers](https://datatracker.ietf.org/doc/html/rfc5322#section-2.2). Each key represents a header name and the value the header value. Ex: `{"X-Accept-Language": "en", "X-Mailer": "MyApp"}` |
## Sending email
> \[!NOTE]
>
> SendGrid's [API keys](/docs/sendgrid/ui/account-and-settings/api-keys/) should be used when sending email over the API. API keys are preferred because you can revoke an API key at any time without changing your username and password. You can also limit the permissions of an API key, which reduces the potential for harm in the event that your API key is compromised.
>
> When using an API key, pass it in an Authorization header and omit the `api_user` and `api_key` parameters from your request. Pass the API key as a Bearer Token: `"Authorization: Bearer "`
>
> For more information, see [Upgrading your authentication method to API Keys](/docs/sendgrid/for-developers/sending-email/upgrade-your-authentication-method-to-api-keys/).
### Send to a single recipient
## JSON
#### Call
| `POST` | `https://api.sendgrid.com/api/mail.send.json` |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `POST` Data | `to=destination@example.com&toname=Destination&subject=Example_Subject&text=testingtextbody&from=info@domain.com` |
#### Response
```javascript
{
"message": "success"
}
```
## XML
#### Call \[#call-2]
| `POST` | `https://api.sendgrid.com/api/mail.send.xml` |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `POST` Data | `to=destination@example.com&toname=Destination&subject=Example_Subject&text=testingtextbody&from=info@domain.com` |
#### Response \[#response-2]
```xml
success
```
> \[!NOTE]
>
> You can have up to 1,000 recipients per Web API v2 request.
### Send to multiple recipients
## JSON
#### Call \[#call-3]
| `POST` | `https://api.sendgrid.com/api/mail.send.json` |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` Data | `to[]=destination@example.com&to[]=destination2@example.com&toname[]=Destination&to[]=example@example.com&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=info@domain.com` |
#### Response \[#response-3]
```javascript
{
"message": "success"
}
```
## XML
#### Call \[#call-4]
| `POST` | `https://api.sendgrid.com/api/mail.send.xml` |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` Data | `to[]=destination@example.com&to[]=destination2@example.com&toname[]=Destination&to[]=example@example.com&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=info@domain.com` |
#### Response \[#response-4]
```xml
success
```
### Sending with a CC and CCname
## JSON
#### Call \[#call-5]
| `POST` | `https://api.sendgrid.com/api/mail.send.json` |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` Data | `to[]=destination@example.com&toname[]=Destination&cc=ccdestination@mail.com&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com` |
#### Response \[#response-5]
```javascript
{
"message": "success"
}
```
## XML
#### Call \[#call-6]
| `POST` | `https://api.sendgrid.com/api/mail.send.xml` |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` Data | `to[]=destination@example.com&toname[]=Destination&cc=ccdestination@mail.com&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com` |
#### Response \[#response-6]
```xml
success
```
### Sending with a BCC and BCCname
## JSON
#### Call \[#call-7]
| `POST` | `https://api.sendgrid.com/api/mail.send.json` |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST` Data | `to[]=destination@example.com&toname[]=Destination&bcc=bccdestination@mail.com&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com` |
#### Response \[#response-7]
```javascript
{
"message": "success"
}
```
## XML
#### Call \[#call-8]
| `POST` | `https://api.sendgrid.com/api/mail.send.xml` |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST` Data | `to[]=destination@example.com&toname[]=Destination&bcc=bccdestination@mail.com&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com` |
#### Response \[#response-8]
```xml
success
```
### cURL Examples
#### Send to one email recipient
```bash
curl -X "POST" "https://api.sendgrid.com/api/mail.send.json" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode "to=destination@example.com" \
--data-urlencode "toname=Destination" \
--data-urlencode "subject=Example Subject" \
--data-urlencode "text=testingtextbody" \
--data-urlencode "from=info@domain.com"
```
#### Send to multiple email recipients
```bash
curl -X "POST" "https://api.sendgrid.com/api/mail.send.json" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode "to[]=destination@example.com,example@example.com" \
--data-urlencode "toname[]=Destination,Destination2" \
--data-urlencode "subject=Example Subject" \
--data-urlencode "text=testingtextbody" \
--data-urlencode "from=info@domain.com"
```
> \[!NOTE]
>
> To ensure that an attachment uploads from a local file, use `\<@filename>`.
```bash
curl https://api.sendgrid.com/api/mail.send.json \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F to=recipient@domain.com -F toname=test -F subject="Example Subject" \
-F text="testing text body" --form-string html="testing html body" \
-F from=test@example.com -F api_user=your_sendgrid_username -F api_key=your_sendgrid_password \
-F files[attachment.pdf\]=@attachment.pdf;type=application/pdf
```
#### Send a test with an attachment
```bash
curl https://api.sendgrid.com/api/mail.send.json \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F to=recipient@domain.com -F toname=test -F subject="Example Subject" \
-F text="testing text body" --form-string html="testing html body" \
-F from=test@example.com \
-F files[attachment.gz\]=@f.php.gz
```
#### Send a test specifying the file content type by appending ';type=' to the file name
```bash
curl https://api.sendgrid.com/api/mail.send.json \
-F to=recipient@domain.com -F toname=test -F subject="Example Subject" \
-F text="testing text body" --form-string html="testing html body" \
-F from=test@example.com -F api_user=your_sendgrid_username -F api_key=your_sendgrid_password \
-F files[attachment.pdf\]=@attachment.pdf;type=application/pdf
```
### Raw HTTP Dump
The following is a dump of the HTTP data sent to our server to generate an email via our Web API v2.
```bash
POST /api/mail.send.json HTTP/1.1
```
```bash
Host: sendgrid.com
Accept: */*
Content-Length: 999
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----------------------------400f182a9360
Authorization: Bearer YOUR_API_KEY
HTTP/1.1 100 Continue
------------------------------400f182a9360
Content-Disposition: form-data; name="to"
someone@somewhere.com
------------------------------400f182a9360
Content-Disposition: form-data; name="subject"
test of file sends
------------------------------400f182a9360
Content-Disposition: form-data; name="html"
the HTML
------------------------------400f182a9360
Content-Disposition: form-data; name="text"
the plain text
------------------------------400f182a9360
Content-Disposition: form-data; name="from"
example@sendgrid.com
------------------------------400f182a9360
Content-Disposition: form-data; name="files[myfile]"; filename="myfile"
Content-Type: application/octet-stream
file with stuff in it
------------------------------400f182a9360--
HTTP/1.1 200 OK
Server: nginx/0.7.65
Date: Fri, 03 Jun 2011 22:30:58 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
```
```bash
{"message":"success"}
```