Skip to content
This repository was archived by the owner on Aug 27, 2021. It is now read-only.

Commit b1a4309

Browse files
eschallockeschallock
authored
Merge pull request #1968 from sendgrid/develop
6/27/2016 Docs Updates
2 parents b07dc03 + 720d697 commit b1a4309

File tree

22 files changed

+440
-119
lines changed

22 files changed

+440
-119
lines changed

‎source/API_Reference/Web_API_v3/Mail/errors.md‎

Lines changed: 77 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -11,22 +11,83 @@ navigation:
1111

1212
Failed requests will always return an error response, including a response code, a message explaining the reason for the error, and a link to any relevant documentation that may help you troubleshoot the problem.
1313

14-
| Response Code | Reason | Description |
15-
|---|---|---|
16-
| 2xx | 2xx responses indicate a successful request | The request that you made is valid and successful. |
17-
| 200 | OK | Your message is valid, but it is not queued to be delivered. |
18-
| 202 | ACCEPTED | Your message is both valid, and queued to be delivered. |
19-
| 4xx | 4xx responses indicate an error with the request | There was a problem with your request. |
20-
| 400 | BAD REQUEST | |
21-
| 401 | UNAUTHORIZED | You do not have authorization to make the request. |
22-
| 403 | FORBIDDEN | |
23-
| 404 | NOT FOUND | The resource you tried to locate could not be found or does not exist. |
24-
| 405 | METHOD NOT ALLOWED | |
25-
| 413 | PAYLOAD TOO LARGE | The JSON payload you have included in your request is too large. |
26-
| 429 | TOO MANY REQUESTS | The number of requests you have made exceeds SendGrid's [rate limitations]({{root_url}}/API_Reference/Web_API_v3/How_To_Use_The_Web_API_v3/rate_limits.html) |
27-
| 5xx | 5xx respones indicate an error made by SendGrid | An error occurred when SendGrid attempted to processes it. |
28-
| 500 | SERVER UNAVAILABLE | An error occurred on a SendGrid server. |
29-
| 503 | SERVICE NOT AVAILABLE | The SendGrid v3 Web API is not available. |
14+
<table class="table">
15+
<tr>
16+
<th>Response Code</th>
17+
<th>Reason</th>
18+
<th>Description</th>
19+
</tr>
20+
<tr>
21+
<td>2xx</td>
22+
<td>2xx responses indicate a successful request</td>
23+
<td>The request that you made is valid and successful.</td>
24+
</tr>
25+
<tr>
26+
<td>200</td>
27+
<td>OK</td>
28+
<td>Your message is valid, but it is not queued to be delivered.</td>
29+
</tr>
30+
<tr>
31+
<td>202</td>
32+
<td>ACCEPTED</td>
33+
<td>Your message is both valid, and queued to be delivered.</td>
34+
</tr>
35+
<tr>
36+
<td>4xx</td>
37+
<td>4xx responses indicate an error with the request</td>
38+
<td>There was a problem with your request.</td>
39+
</tr>
40+
<tr>
41+
<td>400</td>
42+
<td>BAD REQUEST</td>
43+
<td></td>
44+
</tr>
45+
<tr>
46+
<td>401</td>
47+
<td>UNAUTHORIZED</td>
48+
<td>You do not have authorization to make the request.</td>
49+
</tr>
50+
<tr>
51+
<td>403</td>
52+
<td>FORBIDDEN</td>
53+
<td></td>
54+
</tr>
55+
<tr>
56+
<td>404</td>
57+
<td>NOT FOUND</td>
58+
<td>The resource you tried to locate could not be found or does not exist.</td>
59+
</tr>
60+
<tr>
61+
<td>405</td>
62+
<td>METHOD NOT ALLOWED</td>
63+
<td></td>
64+
</tr>
65+
<tr>
66+
<td>413</td>
67+
<td>PAYLOAD TOO LARGE</td>
68+
<td>The JSON payload you have included in your request is too large.</td>
69+
</tr>
70+
<tr>
71+
<td>429</td>
72+
<td>TOO MANY REQUESTS</td>
73+
<td>The number of requests you have made exceeds SendGrid's [rate limitations]({{root_url}}/API_Reference/Web_API_v3/How_To_Use_The_Web_API_v3/rate_limits.html)</td>
74+
</tr>
75+
<tr>
76+
<td>5xx</td>
77+
<td>5xx respones indicate an error made by SendGrid</td>
78+
<td>An error occurred when SendGrid attempted to processes it.</td>
79+
</tr>
80+
<tr>
81+
<td>500</td>
82+
<td>SERVER UNAVAILABLE</td>
83+
<td>An error occurred on a SendGrid server.</td>
84+
</tr>
85+
<tr>
86+
<td>503</td>
87+
<td>SERVICE NOT AVAILABLE</td>
88+
<td>The SendGrid v3 Web API is not available.</td>
89+
</tr>
90+
</table>
3091

3192
Following is a complete list of the possible parameter level errors that you may receive when making a request to the v3 Mail Send endpoint. Each error will include the field that caused the error (e.g. "personalizations" or "personalizations.to"), a brief message explaining the cause of the error, and a link to the error in the table below. Here you will find links to relevant documentation for each error.
3293

‎source/API_Reference/Web_API_v3/Mail/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@
6060
{% endanchor %}
6161

6262
{% codeblock lang:bash %}
63-
curl =X "POST" "https://api.sendgrid.com/v3/mail/send" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "[YOUR DATA HERE]"
63+
curl -X "POST" "https://api.sendgrid.com/v3/mail/send" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "[YOUR DATA HERE]"
6464
{% endcodeblock %}
6565

6666
You must authenticate every API request to send mail by including an <code>Authorization</code> header. This header should include the authorization type of <code>Bearer</code>, followed by your API Key that has already been assigned the necessary permissions. Click <a href="{{root_url}}/API_Reference/Web_API_v3/How_To_Use_The_Web_API_v3/authentication.html">here</a> for more information.

‎source/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.apiblueprint‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,8 @@ Lists
4040

4141
Recipients
4242
<ul>
43-
<li><a href="{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#Add-Recipients-POST">Add Recipients - POST</a></li>
43+
<li><a href="{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#Add-Single-Recipient-POST">Add a Single Recipient - POST</a></li>
44+
<li><a href="{{root_url}}{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#Add-Multiple-Recipients-POST">Add Multiple Recipients - POST</a></li>
4445
<li><a href="{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#Update-Recipient-PATCH">Update a Recipient - PATCH</a></li>
4546
<li><a href="{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#Delete-Recipient-DELETE">Delete one or more Recipients - DELETE</a></li>
4647
<li><a href="{{root_url}}/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html#List-Recipients-GET">List Recipients - GET</a></li>
@@ -412,25 +413,51 @@ The rate at which recipients may be added to a list is limited to 1 request per
412413

413414
## Recipients [/contactdb/recipients]
414415

415-
### Add Recipients [POST]
416+
{% info %}
417+
If you make a request to upload a duplicate recipient and your request would make no change to the original recipient, the original recipient will remain unchanged and its index will be added to the unmodified_indices list.
418+
{% endinfo %}
419+
420+
### Add Single Recipient [POST]
416421

417422
The rate at which recipients may be uploaded is limited to 3 requests every 2 seconds. Recipients may be uploaded in batches of 1000 per request. This results in a maximum upload rate of 1500 recipients per second.
418423

424+
+ Request (application/json)
425+
426+
+ Body
427+
428+
[{"email": "[email protected]", "last_name": "Jones", "pet": "Fluffy", "age": 25}]
429+
430+
+ Response 201
431+
432+
+ Body
433+
434+
{"error_count":0,"error_indices":[],"unmodified_indices":[],"new_count":1,"persisted_recipients":["am9uZXNAZXhhbXBsZS5jb20="],"updated_count":0}
435+
436+
+ Response 400
437+
438+
+ Body
439+
440+
"" : "Returned if request body is not valid json"
441+
442+
443+
### Add Multiple Recipients [POST]
444+
419445
+ Request (application/json)
420446

421447
+ Body
422448

423449
[
424-
{"email": "[email protected]", "last_name": "Jones", "pet": "Indiana", "age": 25},
450+
{"email": "[email protected]", "last_name": "Jones", "pet": "Fluffy", "age": 25},
425451
{"email": "[email protected]", "last_name": "Miller", "pet": "FrouFrou", "age": 32},
426-
{"email": "invalid_email", "last_name": "Smith", "pet": "Spot", "age": 17}
452+
{"email": "invalid_email", "last_name": "Smith", "pet": "Spot", "age": 17},
453+
{"email": "[email protected]"}
427454
]
428455

429456
+ Response 201
430457

431458
+ Body
432459

433-
{"error_count":1,"error_indices":[2],"new_count":2,"persisted_recipients":["YUBh", "bWlsbGVyQG1pbGxlci50ZXN0"],"updated_count":0, "errors":[{"message":"Invalid email.", "error_indices":[2]}]}
460+
{"error_count":1,"error_indices":[2],"unmodified_indices":[3],"new_count":2,"persisted_recipients":["YUBh", "bWlsbGVyQG1pbGxlci50ZXN0"],"updated_count":0, "errors":[{"message":"Invalid email.", "error_indices":[2]}]}
434461

435462
+ Response 400
436463

@@ -447,14 +474,15 @@ Updates one or more recipients. The body is a list of recipient objects.
447474
+ Body
448475

449476
[
450-
{"email": "[email protected]", "last_name": "Jones"}
477+
{"email": "[email protected]", "last_name": "Jones"},
478+
{"email": "[email protected]"}
451479
]
452480

453481
+ Response 201
454482

455483
+ Body
456484

457-
{"error_count":0,"error_indices":[],"new_count":0,"persisted_recipients":["am9uZXNAZXhhbXBsZS5jb20="],"updated_count":1}
485+
{"error_count":0,"error_indices":[],"unmodified_indices":[1],"new_count":0,"persisted_recipients":["am9uZXNAZXhhbXBsZS5jb20="],"updated_count":1}
458486

459487
+ Response 400
460488

@@ -485,7 +513,6 @@ Returned if at least one recipient was deleted
485513
"" : "Returned if all of the provided recipient ids are invalid"
486514
"" : "Returned if request body is not valid json"
487515

488-
489516
## Recipients [/contactdb/recipients?page_size=100&page=1]
490517

491518
{% info %}

‎source/API_Reference/Web_API_v3/Settings/tracking.apiblueprint‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,15 @@ FORMAT: 1A
128128

129129
### Update Open Tracking Settings [PATCH]
130130

131+
<p>
132+
By default, the open tracking image used to determine when an email is opened is inserted at the end of your email. It is possible to specify an alternative location by using a replacement tag and the open tracking <a href="{{root_url}}/API_Reference/SMTP_API/apps.html#opentrack">SMTP API header</a>.
133+
</p>
134+
135+
<p>
136+
If you are sending through the <a href="{{root_url}}/API_Reference/Web_API_v3/Mail/index.html">v3 Mail Send endpoint</a> then you can specify the substitution tag you want to use by setting the <code>enable</code> parameter to <code>true</code> within the <code>open_tracking</code> object and specifying the text you would like to use in the <code>substitution_tag</code> parameter. SendGrid will replace your <code>substitution_tag</code> text with the open tracking pixel wherever you insert it in your email.
137+
</p>
138+
139+
131140
+ Request (application/json)
132141

133142
+ Body

‎source/API_Reference/Web_API_v3/Webhooks/parse.apiblueprint‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
layout: page
3+
title: Parse API
4+
weight: 80
5+
navigation:
6+
show: true
7+
---
8+
FORMAT: 1A
9+
10+
The following Parse API settings allow you to manage the [Inbound Parse Webhook]({{root_url}}/API_Reference/Webhooks/parse.html).
11+
12+
## Parse Settings Collection [/user/webhooks/parse/settings?limit={limit}&offset={offset}]
13+
14+
### Get Parse Settings [GET]
15+
16+
Retrieves all of your current inbound parse settings.
17+
18+
+ Parameters
19+
+ limit (optional, number, `20`) ... Number of settings to return.
20+
+ offset (optional, number, `1`) ... Paging offset.
21+
22+
+ Response 200 (application/json)
23+
24+
+ Body
25+
26+
{
27+
"result":
28+
[
29+
{
30+
"url": "http://mydomain.com/parse",
31+
"hostname": "mail.mydomain.com",
32+
"spam_check": true,
33+
"send_raw": true
34+
}
35+
]
36+
}
37+
38+
## Parse Settings Create Resource [/user/webhooks/parse/settings]
39+
40+
### Create Parse Setting [POST]
41+
42+
Creates a new inbound parse setting.
43+
44+
+ Request (application/json)
45+
46+
+ Body
47+
48+
{
49+
"hostname": "myhostname.com",
50+
"url": "http://email.myhosthame.com",
51+
"spam_check": true,
52+
"send_raw": false
53+
}
54+
55+
+ Response 201 (application/json)
56+
57+
+ Body
58+
59+
{
60+
"url": "http://email.myhostname.com",
61+
"hostname": "myhostname.com",
62+
"spam_check": false,
63+
"send_raw": true
64+
}
65+
66+
## Parse Settings Resource [/user/webhooks/parse/settings/{hostname}]
67+
68+
### Get Parse Setting [GET]
69+
70+
Retrieves a specific inbound parse setting.
71+
72+
+ Response 200 (application/json)
73+
74+
+ Body
75+
76+
{
77+
"url": "http://mydomain.com/parse",
78+
"hostname": "mail.mydomain.com",
79+
"spam_check": true,
80+
"send_raw": true
81+
}
82+
83+
### Update Parse Setting [PATCH]
84+
85+
Updates one of your current inbound parse settings.
86+
87+
+ Request (application/json)
88+
89+
+ Body
90+
91+
{
92+
"url": "http://newdomain.com/parse",
93+
"spam_check": false,
94+
"send_raw": true
95+
}
96+
97+
+ Response 200 (application/json)
98+
99+
+ Body
100+
101+
{
102+
"url": "http://mydomain.com/parse",
103+
"hostname": "mail.mydomain.com",
104+
"spam_check": true,
105+
"send_raw": true
106+
}
107+
108+
### Delete Parse Setting [DELETE]
109+
110+
Deletes one of your current inbound parse settings.
111+
112+
+ Response 204 (application/json)

‎source/API_Reference/Web_API_v3/Webhooks/parse.md‎

Lines changed: 0 additions & 25 deletions
This file was deleted.

‎source/API_Reference/Web_API_v3/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Hello, World!
1414

1515
{% codeblock lang:bash %}
1616
curl --request POST \
17-
--url https://api.sendgrid.com/v3/mail/send/beta \
17+
--url https://api.sendgrid.com/v3/mail/send \
1818
--header 'Authorization: Bearer YOUR_API_KEY' \
1919
--header 'Content-Type: application/json' \
2020
--data '{"personalizations": [{"to": [{"email": "[email protected]"}]}],"from": {"email": "[email protected]"},"subject": "Hello, World!","content": [{"type": "text/plain", "value": "Heya!"}]}'

0 commit comments

Comments
 (0)