# Get Newsletter

Reads an email newsletter’s identity and lifecycle, with optional metadata, audience, delivery, reach and conversion-pixel projections. The body is in get-email-editor-content. For split tests, deliveryConfiguration needs a variant editorUrl; there is no single email ID. Hand conversion-pixel snippets to the user verbatim for installation.

## Input schema:

```json
{
  "type": "object",
  "properties": {
    "newsletterId": {
      "type": "integer",
      "description": "ID of the newsletter, as shown in the KlickTipp app URL",
      "minimum": 1
    },
    "include": {
      "type": "array",
      "description": "Projections to add: \"metadata\", \"audience\", \"deliveryConfiguration\", \"deliveryStatus\", \"audienceReach\", \"conversionPixel\"; omit for identity and lifecycle only. The body is get-email-editor-content",
      "default": null,
      "items": {
        "type": "string",
        "enum": [
          "metadata",
          "audience",
          "deliveryConfiguration",
          "deliveryStatus",
          "audienceReach",
          "conversionPixel"
        ]
      },
      "maxItems": 6,
      "uniqueItems": true
    },
    "editorUrl": {
      "type": [
        "null",
        "string"
      ],
      "description": "Editor URL naming one variant of a split test, from splitTestVariants; omit for a newsletter with a single email",
      "default": null,
      "minLength": 12,
      "maxLength": 500
    },
    "accountId": {
      "type": [
        "null",
        "integer"
      ],
      "description": "User ID of the account; omit for the account the access token works in",
      "default": null,
      "minimum": 1
    }
  },
  "required": [
    "newsletterId"
  ],
  "additionalProperties": false
}
```

## Output schema:

```json
{
  "type": "object",
  "oneOf": [
    {
      "type": "object",
      "required": [
        "accountId",
        "newsletterId",
        "emailId",
        "createdAt",
        "newsletterStatus",
        "usageType",
        "emailEditor",
        "isSplitTest",
        "editUrl",
        "contentUrl",
        "scheduleUrl",
        "statisticsUrl"
      ],
      "properties": {
        "accountId": {
          "type": "integer"
        },
        "newsletterId": {
          "type": "integer"
        },
        "emailId": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Null for a split test: each variant has its own email."
        },
        "createdAt": {
          "type": "string"
        },
        "newsletterStatus": {
          "type": "string",
          "enum": [
            "draft",
            "scheduled",
            "outgoing",
            "sent"
          ]
        },
        "usageType": {
          "type": "string",
          "enum": [
            "newsletter",
            "newsletter-split-test"
          ]
        },
        "emailEditor": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "drag-and-drop",
            "rich-text",
            null
          ]
        },
        "isSplitTest": {
          "type": "boolean"
        },
        "splitTestVariants": {
          "type": [
            "array",
            "null"
          ],
          "description": "The variants of a split test, each with the editorUrl that reads it; null for a standard newsletter.",
          "items": {
            "type": "object",
            "required": [
              "emailId",
              "label",
              "name",
              "subject",
              "editorUrl"
            ],
            "properties": {
              "emailId": {
                "type": "integer"
              },
              "label": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "subject": {
                "type": "string"
              },
              "editorUrl": {
                "type": "string"
              }
            }
          }
        },
        "editUrl": {
          "type": "string"
        },
        "contentUrl": {
          "type": [
            "string",
            "null"
          ]
        },
        "scheduleUrl": {
          "type": "string"
        },
        "statisticsUrl": {
          "type": "string"
        },
        "metadata": {
          "type": "object"
        },
        "audience": {
          "type": "object"
        },
        "deliveryConfiguration": {
          "type": "object",
          "properties": {
            "senderIdentity": {
              "type": "object",
              "required": [
                "effectiveSenderEmail",
                "customerDomain",
                "normalizedSenderDomain",
                "status",
                "isUsable",
                "senderEmailOptions",
                "senderDomainOptions"
              ],
              "properties": {
                "effectiveSenderEmail": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "customerDomain": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "normalizedSenderDomain": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "status": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "enum": [
                    "ready",
                    "address-not-configured",
                    "address-not-confirmed",
                    "address-not-usable",
                    "address-blocked",
                    "domain-not-configured",
                    "domain-not-verified",
                    "domain-not-yet-usable",
                    "domain-mismatch",
                    null
                  ]
                },
                "isUsable": {
                  "type": [
                    "boolean",
                    "null"
                  ]
                },
                "senderEmailOptions": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "senderDomainOptions": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "deliveryStatus": {
          "type": "object",
          "required": [
            "accountId",
            "observedAt",
            "newsletterId",
            "name",
            "newsletterStatus",
            "dispatchConfigured",
            "mode",
            "sendDate",
            "sendProcessFinishedAt",
            "estimatedRecipients",
            "sentCount",
            "failedCount",
            "totalOpenCount",
            "uniqueOpenCount",
            "totalClickCount",
            "uniqueClickCount",
            "hardBounceCount",
            "softBounceCount",
            "spamBounceCount",
            "spamComplaintCount",
            "unsubscriptionCount",
            "canBeCancelled",
            "missingRequirements",
            "readyToSend",
            "scheduleUrl",
            "statisticsUrl"
          ],
          "properties": {
            "accountId": {
              "type": "integer"
            },
            "observedAt": {
              "type": "string",
              "description": "When these counters were read; bounces and complaints arrive later."
            },
            "newsletterId": {
              "type": "integer"
            },
            "name": {
              "type": "string"
            },
            "newsletterStatus": {
              "type": "string",
              "enum": [
                "draft",
                "scheduled",
                "outgoing",
                "sent"
              ]
            },
            "dispatchConfigured": {
              "type": "boolean"
            },
            "mode": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "immediate",
                "scheduled",
                null
              ],
              "description": "Null while no dispatch is set up; never an empty string."
            },
            "sendDate": {
              "type": [
                "string",
                "null"
              ],
              "description": "Null for a draft, even one whose schedule was set and called off."
            },
            "sendProcessFinishedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "estimatedRecipients": {
              "type": "integer",
              "minimum": 0
            },
            "sentCount": {
              "type": "integer",
              "minimum": 0
            },
            "failedCount": {
              "type": "integer",
              "minimum": 0
            },
            "totalOpenCount": {
              "type": "integer",
              "minimum": 0,
              "description": "Opens as events: one person opening twice counts twice."
            },
            "uniqueOpenCount": {
              "type": "integer",
              "minimum": 0,
              "description": "Opens counted once per contact."
            },
            "totalClickCount": {
              "type": "integer",
              "minimum": 0
            },
            "uniqueClickCount": {
              "type": "integer",
              "minimum": 0
            },
            "hardBounceCount": {
              "type": "integer",
              "minimum": 0
            },
            "softBounceCount": {
              "type": "integer",
              "minimum": 0
            },
            "spamBounceCount": {
              "type": "integer",
              "minimum": 0
            },
            "spamComplaintCount": {
              "type": "integer",
              "minimum": 0,
              "description": "Also counted in unsubscriptionCount, because a complaint unsubscribes; not summable."
            },
            "unsubscriptionCount": {
              "type": "integer",
              "minimum": 0
            },
            "canBeCancelled": {
              "type": "boolean"
            },
            "missingRequirements": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "readyToSend": {
              "type": "boolean"
            },
            "scheduleUrl": {
              "type": "string"
            },
            "statisticsUrl": {
              "type": "string"
            }
          }
        },
        "audienceReach": {
          "type": "object",
          "required": [
            "accountId",
            "newsletterId",
            "minRecipients",
            "maxRecipients",
            "observedAt"
          ],
          "properties": {
            "accountId": {
              "type": "integer"
            },
            "newsletterId": {
              "type": "integer"
            },
            "minRecipients": {
              "type": "integer",
              "description": "How many contacts the dispatch would certainly reach."
            },
            "maxRecipients": {
              "type": "integer",
              "description": "How many it would reach at most."
            },
            "observedAt": {
              "type": "string",
              "description": "When the audience was measured, ISO 8601 with offset; a snapshot."
            }
          }
        }
      }
    },
    {
      "type": "object",
      "required": [
        "error"
      ],
      "properties": {
        "error": {
          "type": "object",
          "required": [
            "code",
            "message",
            "remediation",
            "details"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "The machine-readable KlickTipp error code."
            },
            "message": {
              "type": "string"
            },
            "remediation": {
              "type": "string",
              "description": "Who has to act: for example get_again, use_klicktipp_editor, change_document, change_html, retry_later or ask_user_before_retry."
            },
            "details": {
              "type": "object"
            }
          }
        }
      }
    },
    {
      "type": "object",
      "required": [
        "code",
        "isSplitTest",
        "appUrl"
      ],
      "properties": {
        "code": {
          "type": "string",
          "const": "split_test_not_supported"
        },
        "isSplitTest": {
          "type": "boolean"
        },
        "appUrl": {
          "type": "string",
          "description": "Where the variants of this split test can be worked on in KlickTipp."
        },
        "newsletterId": {
          "type": "integer"
        },
        "message": {
          "type": "string"
        }
      }
    }
  ]
}
```