Merge pull request #1438 from sendgrid/kb_docs_move

Knowledge Base -> Docs Move

Author: eschallock

source/API_Reference/Web_API_v3/Marketing_Campaigns/campaigns.apiblueprint

@@ -253,7 +253,7 @@ Returns an empty array if no campaigns exist
             "list_ids": "You must select at least 1 segment or 1 list to send to."
             "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign."
             "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign."
-            "": "You do not have enough credits to send this campaign. <a href='https://app.sendgrid.com/settings/billing'>Upgrade your plan to send more.</a>"
+            "": " credits to send this campaign. <a href='https://app.sendgrid.com/settings/billing'>Upgrade your plan to send more.</a>"
 
 + Response 403
 

source/Classroom/Basics/API/Icon

@@ -0,0 +1,16 @@
+---
+seo:
+  title: Does Sendgrid offer a sandbox or test environment?
+  description: Does Sendgrid offer a sandbox or test environment?
+  keywords: box, throughput, development, dev, staging, sand, speed, developers, test, sandbox, environment, trial
+title: Does Sendgrid offer a sandbox or test environment?
+weight: 0
+layout: page
+zendesk_id: 203891358
+navigation:
+  show: true
+---
+
+We do not offer a true "sandbox" environment, however we do have a [Free plan](https://sendgrid.com/transactional-email/pricing) which allows you to send 400 emails per day, and also gives you access to almost all of the features offered with our higher package levels. The Free plan does not include access to a dedicated IP or IP whitelabeling.
+
+We also have a [sink email address](http://support.sendgrid.com/hc/en-us/articles/201995663-Safely-Test-Your-Sending-Speed) that can help you test message throughput for your integration.

source/Classroom/Basics/API/does_sendgrid_offer_a_sandbox_or_test_environment.md

@@ -0,0 +1,30 @@
+---
+seo:
+  title: How do I Integrate with SendGrid?
+  description: How do I Integrate with SendGrid?
+  keywords: marketing, webhook, newsletter, getting, started, whitelabel, getting_started, email, api, integration, smtp, what, warm
+title: How do I Integrate with SendGrid?
+weight: 0
+layout: page
+zendesk_id: 200182018
+navigation:
+  show: true
+---
+
+There are many different ways to use SendGrid’s email services so it all comes down to what _you_ need. We have numerous examples for how to configure mail clients such as Outlook and Apple Mail to send through our system as well as integration examples for a multitude of programming languages and libraries on our  [SendGrid Integration Page](http://sendgrid.com/docs/Integrate/index.html).
+
+**The main ways you can integrate with Sendgrid: **
+
+- [SMTP](http://support.sendgrid.com/hc/en-us/articles/202821898-What-is-SMTP-) - Send using a desktop mail client, or existing program/service with [your smtp credentials](http://support.sendgrid.com/hc/en-us/articles/200328026-What-are-my-settings-for-SMTP-integration-). 
+- [Web API](https://sendgrid.com/docs/API_Reference/Web_API/index.html) - Send from your app using  [your api key](http://support.sendgrid.com/hc/en-us/articles/200181818-What-is-my-API-key-). Check out our [API Guide](http://go.sendgrid.com/rs/sendgrid/images/SendGrid_API_Guide-101.pdf) for more info.
+- [Email Marketing App and API](https://sendgrid.com/docs/Marketing_Emails/index.html) - Send from our content creation UI and manage your lists via the website. 
+
+ 
+
+**Things to consider before you start sending:**
+
+- We recommend that all Silver and higher customers complete [Whitelabeling](http://support.sendgrid.com/entries/21195838-whitelabel-why-do-i-need-to-make-dns-changes-silver) for their accounts. This process helps your emails look as legitimate as possible!
+- Also consider implementing the  [Event API](http://sendgrid.com/docs/API_Reference/Webhooks/event.html) to track and log your email data more thoroughly. For more info on the benefits of Event API, check out our  [_Why Event API_](http://support.sendgrid.com/entries/21233621-why-event-api) article. The Event API is available to all account levels except for Lite.
+- We _ **highly** _ recommend that if you are a Silver or higher customer, you [warm up your IP](https://sendgrid.com/docs/User_Guide/warming_up.html) as part of your getting started checklist. Warming up is one of the best ways to prevent delivery issues down the road!
+
+ 

source/Classroom/Basics/API/how_do_i_integrate_with_sendgrid.md

@@ -0,0 +1,113 @@
+---
+seo:
+  title: How to Create a Subuser with the API
+  description: How to Create a Subuser with the API
+  keywords: subuser, api, IP, account, new, create, /customer.
+title: How to Create a Subuser with the API
+weight: 0
+layout: page
+zendesk_id: 201750787
+navigation:
+  show: true
+---
+
+<center>Creating a new subuser through SendGrid's API is a multi-step process. This guide will walk you through the necessary steps in order to create a new subuser account using only API calls.</center>
+
+**1. Establish the New Subuser&nbsp;** (required)
+
+With the [subuser creation API call](http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/subusers.html)&nbsp;you will be able to establish the new subuser's account and profile settings. This call will create the new subuser account, however it does not apply the sending IP for the account, nor does it establish a whitelabel entry or enable website/SMTP access for the subuser.   
+
+**Call Example:** https://api.sendgrid.com/apiv2/customer.add.json?api\[email protected]&api\_key=xxxxxx&username=newsubuser\_username&website=yourdomain.com&password=newsubuser\_password&confirm\_password=newsubuser\_password&first\_name=Ryan&last\_name=Burrer&address=555\_anystreet&city=any\_city&state=CO&zip=80203&[email protected]&country=US&phone=555-5555
+
+<center>
+<strong>Success Message<br></strong><img src="http://content.screencast.com/users/Ryan.Burrer/folders/Jing/media/5e355c42-487e-442a-bd2b-89c9d80dd7d0/00000094.png" alt=""><center><strong> <br>Failure Message<br></strong></center>
+<img src="http://content.screencast.com/users/Ryan.Burrer/folders/Jing/media/d8482205-976f-4f82-ad3a-77503e867c2f/00000095.png" alt=""> <strong><span class="wysiwyg-font-size-medium"><br><br></span></strong>
+</center>
+
+**2. Assign an IP to be Used by the New Subuser** &nbsp;(required)   
+
+Now that you have created the new subuser account, you will need to [add an IP](http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/ip_management.html#-Subuser-IP-Assignment)&nbsp;so that it can send emails. We advise that you first find an available IP for this subuser. You can do so by using the following call:
+
+**Call Example:** https://api.sendgrid.com/apiv2/customer.ip.xml?api\[email protected]&api\_key=xxxxxx&list=all
+
+When defining the parameter 'list' there are a few options you can choose:
+
+- **All&nbsp;** = Will list all of the IPs on your account, taken or available.
+- **Free&nbsp;** = Will list all the free IPs on your account. &nbsp;For instance, if an IP is in use by a subuser or parent account then that IP will not be listed.
+- **Taken&nbsp;** = Will list all of the IP addresses that are assigned to your parent and/or subuser accounts.
+- **Available&nbsp;** = Will list all of the unassigned IP addresses for the account. If a subuser is deactivated&nbsp;_and it&nbsp;_is assigned an IP, that IP will show up on this list since that IP address is not technically in use.
+<center>
+<strong>Response Example<br></strong><img src="http://content.screencast.com/users/Ryan.Burrer/folders/Jing/media/0dc1923b-fff9-4446-aff1-5dcab41929a4/00000096.png" alt="" align="middle">
+</center>
+
+After you have selected the IP that you wish to assign to your subuser account, simply make the API call to [append the IP address](http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/ip_management.html#-Subuser-IP-Assignment).
+
+**Call Example:** https://api.sendgrid.com/apiv2/customer.sendip.json?api\[email protected]&api\_key=xxxxxx&task=append&set=specify&user=newsubuser\_username&ip[]=255.255.255.250&ip[]=255.255.255.255
+
+When defining this call's 'set' parameter, you have a few options for appending the subuser's IP:
+
+- **None&nbsp;** = removes all of the IPs on the associated account.
+- **All&nbsp;** = applies all of the possible IPs to the account.
+- **Specify** =&nbsp;Specify the IPs to the subuser
+<center>
+<strong>Success Message</strong>
+<p class="wysiwyg-text-align-left"><img src="http://content.screencast.com/users/Ryan.Burrer/folders/Jing/media/5e355c42-487e-442a-bd2b-89c9d80dd7d0/00000094.png" alt="" align="middle"></p>
+<strong>Failure Message</strong>
+<p class="wysiwyg-text-align-left"><img src="http://content.screencast.com/users/Ryan.Burrer/folders/Jing/media/d8482205-976f-4f82-ad3a-77503e867c2f/00000095.png" alt="" align="middle"></p>
+</center>
+
+&nbsp;
+
+**3. Assign a Whitelabel for the Subuser Account&nbsp;** (optional)
+
+After you have created the subuser account and have appended an IP address, you are now ready to assign an _existing_&nbsp; [whitelabel](https://sendgrid.zendesk.com/hc/en-us/articles/200548228-All-You-Need-to-Know-About-Whitelabeling) to the account. If you have not yet created the required records for whitelabeling for your chosen domain then this step should be skipped. Unfortunately, new whitelabel records cannot be established through API calls.
+
+First, you should find out what whitelabel entries you have associated with your account. This call will [list your available whitelabel domains](http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/whitelabel.html#-List):
+
+**Call Example:&nbsp;** https://api.sendgrid.com/apiv2/customer.whitelabel.json?api\[email protected]&api\_key=xxxxxx&task=list
+
+<center>
+<strong>Response Example</strong>
+<p class="wysiwyg-text-align-left"><img src="http://content.screencast.com/users/Ryan.Burrer/folders/Jing/media/9d491f57-d3c8-4376-a31d-a04b49590747/00000097.png" alt=""></p>
+</center>
+
+The&nbsp;API response above shows that email.sendgrid.com and email.example.com are both already established whitelabel entries, and can be used by this subuser. &nbsp;If none are displayed then the next step in this process should be skipped.
+
+If you have a whitelabel entry that you wish to apply to your subuser then you will need to [append the whitelabel entry](http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/whitelabel.html#-Append) to your subuser:
+
+**Call Example:** &nbsp;https://api.sendgrid.com/apiv2/customer.whitelabel.json?api\[email protected]&api\_key=xxxxxx&task=append&user=newsubuser\_username&mail\_domain=YOUR.ALREADY.EXISTING.WHITELABEL
+
+<center>
+<strong>Success Message</strong>
+<p class="wysiwyg-text-align-left"><img src="http://content.screencast.com/users/Ryan.Burrer/folders/Jing/media/5e355c42-487e-442a-bd2b-89c9d80dd7d0/00000094.png" alt="" align="middle"></p>
+<strong>Failure Message</strong>
+<p><img src="http://content.screencast.com/users/Ryan.Burrer/folders/Jing/media/d8482205-976f-4f82-ad3a-77503e867c2f/00000095.png" alt=""></p>
+</center>
+
+**4. Authenticating the Subuser to Have Website/SMTP Access&nbsp;** (required)
+
+The final step in creating your new subuser requires you to simply [activate the subuser](http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/authenticate_a_subuser.html) account so that they have website and SMTP access.
+
+**Call Example:** &nbsp;https://api.sendgrid.com/apiv2/customer.auth.json?api\[email protected]&api\_key=xxxxxx&user=newsubuser\_username&password=newsubuser\_password
+
+<center>
+<strong>Success Message</strong>
+<p><img src="http://content.screencast.com/users/Ryan.Burrer/folders/Jing/media/5e355c42-487e-442a-bd2b-89c9d80dd7d0/00000094.png" alt="" align="middle"></p>
+<strong>Failure Message</strong>
+<p><img src="http://content.screencast.com/users/Ryan.Burrer/folders/Jing/media/d8482205-976f-4f82-ad3a-77503e867c2f/00000095.png" alt=""></p>
+</center>
+<center>
+<br><strong>That's All, Folks!</strong>
+</center>
+
+If you have followed all of these steps then you have just created a new subuser using the Subuser API. Give yourself a high five! &nbsp;
+
+But wait, there's more... &nbsp;
+
+Now that you have created a new subuser you can change the [Event Notification URL](http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/event_notification_url.html), the subuser's enabled [apps](http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/apps.html), and even set [account limits](http://sendgrid.com/docs/API_Reference/Customer_Subuser_API/account_limits.html) for the subuser. &nbsp;&nbsp;
+
+<center>
+<p> </p>
+</center>
+
+&nbsp;

source/Classroom/Basics/API/how_to_create_a_subuser_with_the_api.md

@@ -0,0 +1,46 @@
+---
+seo:
+  title: HTTP POSTing The Right Way
+  description: HTTP POSTing The Right Way
+  keywords: event, webhook, http, https, post, parse, header, body
+title: HTTP POSTing The Right Way
+weight: 0
+layout: page
+zendesk_id: 200181828
+navigation:
+  show: true
+---
+
+ **Issue** : You're getting an error when using WebAPI and a very long URI string consisting of all of the parameter data in the URI string. Error returned may be “414 request-URI Too Large.”
+
+**Cause** : Instead of putting the appropriate parameters (i.e. to, from, body, html (etc)) in the body of the HTTP POST request, the user is putting them in the URI string as such:
+
+    http://sendgrid.net/api/mail.send?to=email@address&[email protected]
+
+If the content is too long (in the case of many TO/CC/BCC addresses and lengthy TEXT and HTML content), the error will be generated.
+
+An example using Curl which is not correct (when used on the command line):
+
+    $ curl https://sendgrid.com/api/mail.send.json?api_user=MyName&api_key=MyPassword&[email protected]&[email protected]&text=some+really+long+text+also+notice+how+this+is+all+part+of+the+mail.send.json+URI
+
+The above Curl request is putting all of the parameters as part of the URL (https://sendgrid.com/api/mail.send.json) instead as seperate fields.
+
+Resolution/Best Practices:   
+When performing the HTTP POST, ensure that the parameters are being posted as part of the body instead of with the URI.
+
+Example using Curl which is correct (when used on the command line):
+
+    $ curl -F [email protected] -F [email protected] -F text=some+really+long+text+that+is+now+going+to+work+correctly -F api_user=MyUserName -F api_key=MyPassword https://sendgrid.com/api/mail.send.json
+
+The above Curl request is now submitting the parameters as fields (“-F”) which will put the parameters in the HTTP POST body instead of as part of the URI string. This will allow the customer to not run into the above error under normal circumstances.
+
+For more information, please see the following links:
+
+- Doing HTTP POST the right way: [http://www.jmarshall.com/easy/http/#postmethod](http://www.jmarshall.com/easy/http/#postmethod)
+- SendGrid WebAPI (see Examples): [http://docs.sendgrid.com/documentation/api/web-api/mail/](http://docs.sendgrid.com/documentation/api/web-api/mail/)
+- Curl POST via PHP: [http://davidwalsh.name/execute-http-post-php-curl](http://davidwalsh.name/execute-http-post-php-curl)   
+(notice how the data is put into the CURL\_POSTFIELDS variable instead of the CURL\_URL variable)
+
+ 
+
+_last updated: Jayson Sperling - 09 Apr 2013_

source/Classroom/Basics/API/http_posting_the_right_way.md

@@ -0,0 +1,28 @@
+---
+seo:
+  title: What is my API key?
+  description: What is my API key?
+  keywords: password, credentials, api, key, api_key, credential
+title: What is my API key?
+weight: 0
+layout: page
+zendesk_id: 200181818
+navigation:
+  show: true
+---
+
+SendGrid offers customers the ability to manage the security of their accounts and their sending with [API keys](https://app.sendgrid.com/settings/api_keys).
+
+API Keys allow you to generate an authentication credential that is separate from your username and password. They are independent from one another and are easily disposable. You should create unique API keys for each of your applications or servers so that you can easily revoke them without disrupting other systems if needed.
+
+ 
+
+Example:
+
+> Authorization: Bearer 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
+
+\*For sending via SMTP, provide the string `apikey` as the SMTP username, and use your API Key as the password.
+
+ 
+
+For more information please feel free to review our [documentation](https://sendgrid.com/docs/Classroom/Send/api_keys.html) page.

source/Classroom/Basics/API/what_is_my_api_key.md

@@ -0,0 +1,32 @@
+---
+seo:
+  title: Why Event API?
+  description: Why Event API?
+  keywords: event, webhook, notification, api
+title: Why Event API?
+weight: 0
+layout: page
+zendesk_id: 200182028
+navigation:
+  show: true
+---
+
+Wouldn't it be nice if you could get information about every email you've ever sent, every message that's ever been opened, and any link that's ever been clicked? If you ever talk to SendGrid Support Agents, we'll almost always recommend implementing our Event API if you haven't done so. This article highlights the major benefits of the Event API and why we always recommend it.
+
+ 
+
+Due to the sheer volume of email we send (more than 3 _billion_ in March of 2012), we can only store so much information regarding the emails passing through our system. Our Email Activity page holds records for 2 days with a max 500 entries and our internal database records only go back about 30 days. After that, unfortunately, specific email data is gone (stats are permanent). Fortunately, you can receive and store all of this information on your end though by implementing our Event API.
+
+ 
+
+The Event API, available with all Essentials level and higher accounts, gives you HTTP POSTs for any and all requested account activity as it takes place to a provided URL. The Event API can tell you who opened what email and clicked which link as far back as the records go.  [Events](http://docs.sendgrid.com/documentation/delivery-metrics/) we can POST include Processed, Delivered, Opens, Clicks, Unsubscribes, Spam Reports, Deferred, Bounces, and Drops with all relevant Category and Unique Argument information. This potentially gives you the entire sending activity of your account and is not restricted by our own internal storage limitations. Additionally, as Events are posted realtime you can have automated systems on your end to take action, such as removing an Unsubscribed address from your master mailing list.
+
+ 
+
+You can take things a step further by processing or analyzing the data to present it in intuitive charts and graphs and get much more usable information than we provide on our Statistics page. This also makes it possible to get segmented lists, such as all recipients that Opened last week, that our system does not currently provide.
+
+ 
+
+Although it does require a fair amount of setup, the benefits of the Event API are paramount. More information about setup can be found in our [SendGrid Event API Documentation](https://sendgrid.com/docs/API_Reference/Webhooks/index.html). If you have any specific questions about the Event API please do not hesitate to contact our Support team via email, chat, or phone call.
+
+Need additional functionality with your Event API integration? Check out the open-source [Event Kit App](https://github.com/sendgrid/eventkit), as well as out friends over at [Keen.io](https://keen.io/).

source/Classroom/Basics/API/why_event_api.md

@@ -0,0 +1,18 @@
+---
+seo:
+  title: Adding an additional dedicated IP to your account
+  description: Adding an additional dedicated IP to your account
+  keywords: address, purchase, silver, dedicated, IP, account, add, additional
+title: Adding an additional dedicated IP to your account
+weight: 0
+layout: page
+zendesk_id: 200181948
+navigation:
+  show: true
+---
+
+In order to add additional IPs to your account please contact either SendGrid Support or the SendGrid Sales team. Please feel free to use the options below to contact Support. 
+
+Make sure you know and inform us if the IP will be for the Parent account, both Primary and [Subuser](http://support.sendgrid.com/forums/20690237-subusers "Link: http://support.sendgrid.com/forums/20690237-subusers") account, or Subuser account use only. 
+
+Additional IPs cost an extra $20 per IP per month.