Merge pull request #73 from mailsac/api-calls-ops

Renames API calls to Operations (Ops)

LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2019 Forking Software LLC
+Copyright (c) 2019 - 2021 Forking Software LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -30,4 +30,10 @@ for testing purposes.
 
 8. Alternatively the reStructuredText Visual Studio Code extension can be used for live previews
 
-Copyright © 2019 by Forking Software LLC
+# License
+
+Copyright © 2019-2021 by Forking Software LLC
+
+MIT License
+
+See the LICENSE file in this repository.

about/faq.rst

@@ -30,6 +30,7 @@ custom domain.
 
 Other uses:
 
+* as a developer, to test that your application is sending email
 * avoid spam by keeping your real email address private
 * create an account on a website without disclosing your real email address
 * give it out to strangers
@@ -38,7 +39,6 @@ Other uses:
 * use it when you (legally) want to receive email without disclosing your identity
 * send to an email address or multiple email addresses without needing to
   create them
-* as a developer, to test that your application is sending email
 
 .. _faq-messages-not-received:
 
@@ -108,8 +108,8 @@ You can use `POP3 <https://mailsac.com/docs/fetch-messages-with-pop3>`_ to
 download messages on a private address or custom domain. Responses can be sent
 from non-mailsac accounts you have configured your email client to use.
 
-When does API Call Usage Reset?
--------------------------------
+When does Ops/Operations/API Call Usage Reset?
+-----------------------------------------------
 
 :ref:`doc_api_calls` usage resets on the first of the Month UTC.
 

help/account_management/account_management.rst

@@ -1,7 +1,7 @@
 .. _Dashboard: https://mailsac.com/dashboard
 .. _`Manage Account Details`: https://mailsac.com/account
 .. _`REST API`: https://mailsac.com/api
-.. _`API Use`: https://mailsac.com/usage
+.. _`Ops Usage`: https://mailsac.com/usage
 .. _`Sub-Account User Login`: https://mailsac.com/login-api-key
 
 .. _doc_account_management:
@@ -17,21 +17,22 @@ on the Dashboard_:
 - :ref:`Password Change <sec_password_change>`
 - :ref:`Account Deletion <sec_account_deletion>`
 
-API Usage
+Ops Usage
 ---------
 
-API calls are calculated based on the following service usage:
+Operations (Ops, formerly "api calls") are calculated based on the following
+service usage:
 
 - `REST API`_ calls
 - Messages sent to the :ref:`Email Capture Service <doc_email_capture>`
 - Messages forwarded to :ref:`Slack <sec_forward_to_slack>`
 - Messages forwarded to a :ref:`Webhook <sec_webhook_forwarding>`
 - Messages forwarded to a :ref:`WebSocket <sec_websocket_forwarding>`
 
-View API Usage
+View Usage
 ^^^^^^^^^^^^^^
 
-API Usage can be viewed by selecting `API Usage`_ from the Dashboard_. Current
+Usage can be viewed by selecting `Ops Usage`_ from the Dashboard_. Current
 month usage and historical usage is available. Breakdown by API Key and service
 is visible by hovering the mouse over the bar graph in Monthly API Usage.
 
@@ -51,7 +52,7 @@ Message Statistics
 ------------------
 
 Monthly summaries of the following statistics are available per custom domain
-and account. Message statistics can be viewed by selecting `API Usage`_ from the
+and account. Message statistics can be viewed by selecting `Ops Usage`_ from the
 Dashboard_.
 
 - Inbound Message Counts

services/api_calls/api_calls.rst

@@ -1,18 +1,28 @@
 .. _`REST API`: https://mailsac.com/api
-.. _`API Usage`: https://mailsac.com/usage
+.. _`Ops Usage`: https://mailsac.com/usage
 
 .. _doc_api_calls:
 
-API Calls
-=========
+Ops (Operations) Usage
+======================
 
-API Calls are used to meter usage of the Mailsac service. API Call
-usage resets on the first of the month UTC.
+*Ops* or *Operations* are used to meter usage of the Mailsac service.
 
-What Counts as an API Call?
+A Mailsac account's subscription (or free plan) provides a certain number
+of allowed operations. Ops are allocated on a monthly basis. Ops usage
+resets on the first of the month UTC.
+
+If an account performs more Ops than are allocated, Mailsac will send
+warning emails before disabling API access for the remainder of the month.
+This "soft limit" allows additional time to upgrade or adjust usage.
+
+Ops were referred to as "api calls" until November 2021. The name was changed
+to *Ops* because not all tracked operations are REST API calls.
+
+What Counts as an Op?
 ---------------------------
 
-The following actions count as an API call:
+The following actions count as one Op:
 
 - API call to the `REST API`_
 - Inbound message to a :ref:`private address <doc_private_addresses>`
@@ -21,82 +31,82 @@ The following actions count as an API call:
 - Publish message to :ref:`Webhook <doc_webhook_setup>`
 - Publish message to :ref:`Slack <doc_slack_webhook>`
 
-The following actions **do not** count as an API call:
+The following actions **do not** count as an Op:
 
-- Viewing messages via the Website
+- Viewing messages via the website
 - Deleting messages via the website
-- Forwarding Mail to another
+- Forwarding (re-routing) mail internally to another
   :ref:`Mailsac address <sec_forward_to_another_mailsac_address>`
 
-Monitor API Usage
+Monitor Ops Usage
 -----------------
 
-API usage can be monitored via `API Usage`_. The API Usage page includes
-current month, past usage by month, and all time API calls.
+Ops usage can be monitored via the `Ops Usage`_ page. The page includes
+current month, past usage by month, and all time usage.
 
-API Usage is not updated in real time. The metrics are calculated
+Usage is not updated in real time. The metrics are calculated
 periodically throughout the day.
 
-Calculating API Usage
+Calculating Ops Usage
 ---------------------
 
-API calls can be calculated by summing the number of calls to the
+Ops are calculated by summing the number of calls to the
 `REST API`_,  messages published to WebSockets, Webhooks, and Slack, and
-messages sent to a private domain.
+messages sent to a custom domain.
 
-Inbound Message API Calls
+Inbound Message Ops
 -------------------------
 
-Inbound messages are tracked as an API call. The first forward of the
+Inbound messages are tracked as Ops. The first forward of the
 message to Slack, Webhook, or WebSocket does not count as an additional
-API call. Second and third forwards will count as additional API calls.
+Op. Second and third forwards will count as additional Ops.
 
-Public Domain API Calls
+Public Domain Ops
 -----------------------
 
 Validated :ref:`doc_custom_domains` can be set as public. API calls to
 the domain, its addresses or messages will be tracked on the domain
-owners account.
+owners account, not necessarily the account which performs the action.
 
-Example API Calculation - Fetch Messages and Body of an Email
+Example Ops Calculation - Fetch Messages and Body of an Email
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Viewing the body of a message via the `REST API`_ requires 2 API calls.
 
-1. The first call is used to
+1. The first Op is used to
    `list all the messages in the inbox <https://mailsac.com/docs/api#tag/Email-Messages-API/paths/~1addresses~1{email}~1messages/get>`_.
-2. The second call is used to
+2. The second Op is used to
    `retrieve the plaintext body of a specific message <https://mailsac.com/docs/api#tag/Email-Messages-API/paths/~1text~1{email}~1{messageId}/get>`_.
 
-Example API Calculation - Forward Message from Private Domain to Slack
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example Ops Calculation - Forward Message from Custom Domain to Slack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Receiving a message and publishing to Slack requires 1 API calls.
+Receiving a message and publishing to Slack requires 1 Op.
 
-1. The first call is to receive the message in a private domain.
+1. The Op is to receive the message in a custom domain.
 
 The first forward of an inbound message to Slack, Webhook, or WebSocket
-does not count as an additional API call.
+does not count as an additional Op.
 
-Example API Calculation - Forward Message from Private Domain to Multiple Destinations
+Example Ops Calculation - Forward Message from Custom Domain to Multiple Destinations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Receiving a message and publishing to Slack and a WebSocket
-requires 2 API calls.
+requires 2 Ops.
 
-1. The first call is to receive the message in a private domain.
-2. The second call is for the second message forward.
+1. The first Op is to receive the message in a custom domain.
+2. The second Op is for the second message forward.
 
 The first forward of an inbound message to Slack, Webhook, or WebSocket
-does not count as an additional API call.
+does not count as an additional Op.
 
-Example API Calculation - Forward message to a Private Domain Catch-All
+Example Ops Calculation - Forward message to a Custom Domain Catch-All
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Receiving a message and forwarding to a Private Domain Catch-All
-requires one API call.
+Receiving a message and forwarding to a Custom Domain Catch-All
+requires one Op.
 
-1. Receive message in a private domain.
+1. Receive message in a custom domain.
 
 Catch-All addresses are considered Mailsac addresses, and internal
-forwarding is not counted as an additional API call.
+forwarding is not counted as an additional Op.

services/custom_domains/custom_domains.rst

@@ -253,9 +253,9 @@ Public Custom Domains
 
 Custom domains can be set as public. API calls for the domain,
 its addresses, or messages will be tracked on the domain owner's
-account. Viewing message via the website do not count as an API call.
+account. Viewing message via the website do not count as an Op.
 
-See :ref:`doc_api_calls` for additional details about API call usage.
+See :ref:`doc_api_calls` for additional details about Ops usage.
 
 .. _sec_mx_record_links:
 

services/email_capture/email_capture.rst

@@ -140,7 +140,7 @@ Considerations
 - All email sent will be public (Unless sent to a :ref:`custom domain
   <doc_custom_domains>` or configured to be
   :ref:`private <sec_private_captured_email>`)
-- Each message sent will count as an API call
+- Each message sent will count as an Operation (Op)
 
 Email Capture Use Cases
 -----------------------