[GG-1960] Document sending addresses and setting a Single-Email Campaign's sender

source/includes/rest/_accounts.md

@@ -84,6 +84,14 @@
       <td><code>href</code></td>
       <td>The url designated for retrieving the account record via the REST API.</td>
     </tr>
+    <tr>
+      <td><code>default_email_address_id</code></td>
+      <td>A read-only id of the account's default From address in <code>sending_addresses</code>. Returns <code>null</code> if the account has no default From address or its default address has been deleted; <code>default_from_email</code> still shows the address emails are sent from when they have no From address of their own. Only returned when <a href="#fetch-an-account">fetching an account</a>.</td>
+    </tr>
+    <tr>
+      <td><code>sending_addresses</code></td>
+      <td>A read-only list of the account's email addresses, including unverified ones. Only returned when <a href="#fetch-an-account">fetching an account</a>. Refer to <a href="#sending-addresses">Sending addresses</a> for an overview of the properties returned here.</td>
+    </tr>
     <tr>
       <td><code>links</code></td>
       <td>An object containing URLs for campaign and conversion resources. Note, conversions are represented as "Goals".</td>
@@ -191,13 +199,79 @@ client.fetchAccount(accountId)
 > The response looks like this:
 
 ```json
-# The accounts property is an array of one account object.
+# The accounts property is an array of one account object,
+# which also includes the account's sending addresses.
 {
   "links": { ... },
-  "accounts": [{ ... }]
+  "accounts": [{
+    "id": "9999999",
+    "name": "Acme, Inc.",
+    ...
+    "default_email_address_id": "1234567",
+    "sending_addresses": [
+      {
+        "id": "1234569",
+        "email": "support@acme.com",
+        "is_default": false,
+        "verified": true,
+        "auto_generated": false
+      },
+      {
+        "id": "1234568",
+        "email": "news@acme.com",
+        "is_default": false,
+        "verified": true,
+        "auto_generated": false
+      },
+      {
+        "id": "1234567",
+        "email": "john@acme.com",
+        "is_default": true,
+        "verified": true,
+        "auto_generated": false
+      }
+    ]
+  }]
 }
 ```
 
+### Sending addresses
+
+Fetching a single account also returns the account's email addresses, newest first. Only those
+with `verified: true` can be used as a From address. Deleted addresses are not included. Listing
+accounts does not return them.
+
+<table>
+  <thead>
+    <tr>
+      <th>Property</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>id</code></td>
+      <td>A read-only Drip generated id used to identify the address.</td>
+    </tr>
+    <tr>
+      <td><code>email</code></td>
+      <td>The email address.</td>
+    </tr>
+    <tr>
+      <td><code>is_default</code></td>
+      <td>Returns true for the account's default From address, which emails without their own From address are sent from.</td>
+    </tr>
+    <tr>
+      <td><code>verified</code></td>
+      <td>Returns true if Drip can send from this address: it is on a sending domain you have authenticated in Drip, or it is an address Drip generated for the account. Unverified addresses are listed, but cannot be used as a From address until their domain is authenticated.</td>
+    </tr>
+    <tr>
+      <td><code>auto_generated</code></td>
+      <td>Returns true for the no-reply address Drip creates for new accounts.</td>
+    </tr>
+  </tbody>
+</table>
+
 ### HTTP Endpoint
 
 `GET /v2/accounts/:account_id`

source/includes/rest/_broadcasts.md

@@ -56,7 +56,10 @@ with [Set the audience](#set-the-audience).
   "status": "sent",
   "name": "4 Marketing Automation Trends for 2015",
   "from_name": "John Doe",
-  "from_email": "john@example.com",
+  "from_email": "john@acme.com",
+  "from_email_address_id": "1234567",
+  "reply_to": "support@acme.com",
+  "reply_to_email_address_id": "1234569",
   "postal_address": "123 Anywhere St\nFresno, CA 99999",
   "localize_sending_time": true,
   "send_at": "2015-07-01T10:00:00Z",
@@ -111,7 +114,19 @@ with [Set the audience](#set-the-audience).
     </tr>
     <tr>
       <td><code>from_email</code></td>
-      <td>A "from email" that appears in your sent emails and can be changed on a per email basis. This setting overrides the account's default from email.</td>
+      <td>The address the Single-Email Campaign is sent from: its own From address, or the account's default From address if it has none. Read-only; set it with <code>from_email_address_id</code>.</td>
+    </tr>
+    <tr>
+      <td><code>from_email_address_id</code></td>
+      <td>The id of the address in <code>from_email</code>, matching an <code>id</code> in the account's <a href="#sending-addresses">sending addresses</a>. Returns <code>null</code> if neither the campaign nor the account has a From address, or if the address has been deleted; <code>from_email</code> still shows it. See <a href="#sender">Sender</a>.</td>
+    </tr>
+    <tr>
+      <td><code>reply_to</code></td>
+      <td>The Reply-To address, or <code>null</code> when replies go to the From address. Read-only; set it with <code>reply_to_email_address_id</code>.</td>
+    </tr>
+    <tr>
+      <td><code>reply_to_email_address_id</code></td>
+      <td>The id of the address in <code>reply_to</code>, matching an <code>id</code> in the account's <a href="#sending-addresses">sending addresses</a>, or <code>null</code>. It is also <code>null</code> if the Reply-To address has been deleted; <code>reply_to</code> still shows it. See <a href="#sender">Sender</a>.</td>
     </tr>
     <tr>
       <td><code>postal_address</code></td>
@@ -127,7 +142,7 @@ with [Set the audience](#set-the-audience).
     </tr>
     <tr>
       <td><code>bcc</code></td>
-      <td>A list of emails designated to receive a blind copy of the Single-Email Campaign.</td>
+      <td>A list of emails designated to receive a blind copy of the Single-Email Campaign. Read-only.</td>
     </tr>
     <tr>
       <td><code>created_at</code></td>
@@ -227,6 +242,109 @@ with a `422 Unprocessable Entity`:
 }
 ```
 
+## Sender
+
+> To change who a draft Single-Email Campaign is from and where replies go:
+
+```shell
+curl -X PATCH "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/broadcasts/BROADCAST_ID" \
+  -H "Content-Type: application/json" \
+  -H 'User-Agent: Your App Name (www.yourapp.com)' \
+  -u YOUR_API_KEY: \
+  -d @- << EOF
+  {
+    "broadcasts": [{
+      "from_name": "Acme Support",
+      "from_email_address_id": "1234568",
+      "reply_to_email_address_id": "1234569"
+    }]
+  }
+EOF
+```
+
+```ruby
+require "net/http"
+require "json"
+
+uri = URI("https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/broadcasts/BROADCAST_ID")
+
+request = Net::HTTP::Patch.new(uri)
+request.basic_auth("YOUR_API_KEY", "")
+request["User-Agent"] = "Your App Name (www.yourapp.com)"
+request["Content-Type"] = "application/json"
+request.body = {
+  broadcasts: [{
+    from_name: "Acme Support",
+    from_email_address_id: "1234568",
+    reply_to_email_address_id: "1234569"
+  }]
+}.to_json
+
+response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+  http.request(request)
+end
+
+puts response.body
+```
+
+```javascript
+const response = await fetch(
+  "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/broadcasts/BROADCAST_ID",
+  {
+    method: "PATCH",
+    headers: {
+      "Content-Type": "application/json",
+      "User-Agent": "Your App Name (www.yourapp.com)",
+      "Authorization": "Basic " + Buffer.from("YOUR_API_KEY:").toString("base64")
+    },
+    body: JSON.stringify({
+      broadcasts: [{
+        from_name: "Acme Support",
+        from_email_address_id: "1234568",
+        reply_to_email_address_id: "1234569"
+      }]
+    })
+  }
+);
+
+const body = await response.json();
+```
+
+> If an address id cannot be used, responds with a <code>422 Unprocessable Entity</code> and changes nothing:
+
+```json
+{
+  "errors": [{
+    "code": "validation_error",
+    "attribute": "from_email_address_id",
+    "message": "sales@acme.com is not verified: use the id of an address in the account's sending_addresses that has verified: true."
+  }]
+}
+```
+
+A Single-Email Campaign's From name, From address and Reply-To address can be set when you
+[create](#create-a-single-email-campaign) it, and changed while it is a `draft` with
+[Update a Single-Email Campaign](#update-a-single-email-campaign).
+
+* `from_name` is free text, up to 255 characters. It cannot be blank, and supports Liquid
+  templating.
+* The From and Reply-To addresses are chosen by id, never typed in. Use an `id` from the
+  account's [sending addresses](#sending-addresses), returned by
+  [Fetch an account](#fetch-an-account).
+* `from_email_address_id` must be an address with `verified: true`.
+* `reply_to_email_address_id` must be an address with `verified: true` and
+  `auto_generated: false`.
+* On update, send `null` or `""` to clear either one. A cleared From address sends from the
+  account's default From address, and a cleared Reply-To sends replies to the From address.
+
+Any other id, such as an unverified or deleted address, or one that belongs to another account,
+responds with a `422 Unprocessable Entity` and changes nothing.
+
+`from_email`, `reply_to` and `bcc` are read-only: they are returned in responses. Set the sender
+with the address ids above.
+
+A sender set here appears in the Drip app, the same as one chosen there.
+
 ## List all Single-Email Campaigns
 
 > To list Single-Email Campaigns in an account:
@@ -485,6 +603,18 @@ everyone eligible to receive them. [Set the audience](#set-the-audience) to narr
       <td><code>postal_address</code></td>
       <td>Optional. A physical mailing address for CAN-SPAM compliance. Defaults to the account's postal address.</td>
     </tr>
+    <tr>
+      <td><code>from_name</code></td>
+      <td>Optional. The name the email is sent from (255 characters maximum). Supports Liquid templating. Defaults to the account's default From name.</td>
+    </tr>
+    <tr>
+      <td><code>from_email_address_id</code></td>
+      <td>Optional. The id of a verified address in the account's <a href="#sending-addresses">sending addresses</a> to send from. Defaults to the account's default From address. See <a href="#sender">Sender</a>.</td>
+    </tr>
+    <tr>
+      <td><code>reply_to_email_address_id</code></td>
+      <td>Optional. The id of a verified, non-auto-generated address in the account's <a href="#sending-addresses">sending addresses</a> to receive replies. If omitted, replies go to the From address. See <a href="#sender">Sender</a>.</td>
+    </tr>
   </tbody>
 </table>
 
@@ -652,7 +782,8 @@ const body = await response.json();
 ```
 
 Only Single-Email Campaigns in the `draft` status can be updated via the API; all other
-statuses are read-only. Updates are partial: only the fields you include are changed.
+statuses are read-only. Updates are partial: only the fields you include are changed. To change
+the From name, From address or Reply-To address, see [Sender](#sender).
 
 Status, scheduling, and the audience are not updated here. Each has its own endpoint:
 [Set the audience](#set-the-audience), [Schedule](#schedule-a-single-email-campaign), and
@@ -692,6 +823,18 @@ Status, scheduling, and the audience are not updated here. Each has its own endp
       <td><code>postal_address</code></td>
       <td>Optional. A physical mailing address for CAN-SPAM compliance.</td>
     </tr>
+    <tr>
+      <td><code>from_name</code></td>
+      <td>Optional. The name the email is sent from (255 characters maximum). Supports Liquid templating.</td>
+    </tr>
+    <tr>
+      <td><code>from_email_address_id</code></td>
+      <td>Optional. The id of a verified address in the account's <a href="#sending-addresses">sending addresses</a> to send from. Send <code>null</code> or <code>""</code> to use the account's default From address. See <a href="#sender">Sender</a>.</td>
+    </tr>
+    <tr>
+      <td><code>reply_to_email_address_id</code></td>
+      <td>Optional. The id of a verified, non-auto-generated address in the account's <a href="#sending-addresses">sending addresses</a> to receive replies. Send <code>null</code> or <code>""</code> to have replies go to the From address. See <a href="#sender">Sender</a>.</td>
+    </tr>
   </tbody>
 </table>
 

source/includes/rest/_campaigns.md

@@ -9,6 +9,7 @@
   "name": "SEO Email Course",
   "from_name": "John Doe",
   "from_email": "john@example.com",
+  "reply_to": "support@example.com",
   "postal_address": "123 Anywhere St\nFresno, CA 99999",
   "minutes_from_midnight": 440,
   "localize_sending_time": true,
@@ -75,6 +76,10 @@
       <td><code>from_email</code></td>
       <td>A "from email" that appears in your sent emails. This setting overrides the account's default from email.</td>
     </tr>
+    <tr>
+      <td><code>reply_to</code></td>
+      <td>The Reply-To address set on the Email Series Campaign, or <code>null</code> if none is set. When it is <code>null</code>, replies go to the From address.</td>
+    </tr>
     <tr>
       <td><code>postal_address</code></td>
       <td>As required by the <a href="http://1.usa.gov/YgrzFP" target="_blank">CAN-SPAM Act</a>, this is a postal address used for all sent emails.</td>