Docs v1.0

README.md

@@ -1,2 +1,19 @@
-# docs-and-examples
-QUEUEMAIL.DEV docs & examples
+# QUEUEMAIL.DEV
+
+QUEUEMAIL.DEV allows you to send emails via API using one or more SMTP servers in order to ensure deliverability and avoid SMTP stress.
+
+Some sample features:
+
+- You can program sending emails in a synchronous or asynchronous way: With [logs endpoint](api-logs.md) you can check send status for every email sent. 
+
+- Also, with [webhooks](features-webhooks.md), you can run processes when an event (like email sucessfully sent) occurs for a complete integration.
+
+- With [sending email endpoint](api-mails.md) you can discard sending errors before you start a SMTP session.
+
+- Track opened emails and clicked email links with [tracking endpoint](api-tracking.md).
+
+- ...and much more at [docs](https://docs.queuemail.dev).
+
+Free tier does not support Queuemail professional SMTP servers. So you must to configure [free SMTP servers](other-freesmtps.md) or your custom SMTP server.
+
+

_sidebar.md

@@ -1,8 +1,31 @@
-* [API reference](api.md "API reference")
-** [Login](login.md)
-** [Apps](apps.md)
-** [SMTPs](smtps.md)
-** [Mails](mails.md)
-** [Blacklists](blacklists.md)
-** [Logs](logs.md)
-** [Tracking](tracking.md)
+###   Features:
+* [Fault tolerance strategies](features-smtpstrategies.md)
+* [Loging activity and erros](features-loging.md)
+* [Blacklists](features-blacklists.md)
+* [Webhooks](features-webhooks.md)
+* [Limit origin](features-limitorigin.md)
+* [Data retention](features-dataretention.md)
+
+
+###   API Reference:
+* [API limitations](api-limitations.md)
+* [API access](api-access.md)
+* [Login](api-login.md)
+* [Apps](api-apps.md)
+* [SMTP servers](api-smtps.md)
+* [Mails](api-mails.md)
+* [Blacklists](api-blacklists.md)
+* [Logs](api-logs.md)
+* [Tracking](api-tracking.md)
+
+
+###   Other:
+* [FAQs](other-faqs.md)
+* [Free SMTP servers](other-freesmtps.md)
+
+
+###   Legal:
+* [Private policy](legal-privatepolicy.md)
+
+
+

api-access.md

@@ -0,0 +1,15 @@
+
+
+
+For accessing QUEUEMAIL API you need to [register here](signup.md). Then, with your username and password, you can [login](api-login.md) and get a token you will use in all API operations.
+
+Token expiration = 24 hours.
+
+### API endpoint base URL:
+
+https://api.queuemail.dev/api 
+
+
+
+
+

apps.md → api-apps.md

@@ -1,5 +1,3 @@
-
-
 You need to create at least an app to use QUEUEMAIL. 
 
 Each app should correspond to a project or project part which has different behaviour.
@@ -17,8 +15,9 @@ Each app should correspond to a project or project part which has different beha
 |---------|-----------|--------|---------|
 |idapp | App id | Yes for editing, No for creating |  |
 |name | App name  | Yes for creating, No for editing |  |
+|retaindata | If this app must preserve subject, body and url attachments | No | No |
 |strategy | RANDOM / PRIORITY  | No  | RANDOM |
-|origindomain | If set, just requests from this domain work  | No  |
+|originserver | If set, you can make calls just from this servers/IPs (comma separated for multiple values) | No  |
 |defaultfromemail | Default from email when sending emails | No | User's email |
 |defaultfromname | Default from name when sending emails | No | User's email |
 |testemail | Recipient email for testing emails  | No | User's email |
@@ -30,7 +29,6 @@ Each app should correspond to a project or project part which has different beha
 |webhook_tracking_opened | URL called when mail is opened  | No |
 |webhook_tracking_clicked | URL called when when link in email is clicked | No |
 |webhook_blacklisted_added | URL called when mail address is added to blacklist | No |
-|webhook_mailing_finished | URL called when mailing is finished  | No |
 
 **STATUS CODES:**
 
@@ -48,6 +46,7 @@ Specific errors:
 1. Already exists an APP with the same name
 2. App not found
 3. Must provide a name
+4. You can choose between setting originserver (backend apps) or setting origindomain (frontend apps)
 
 
 
@@ -158,7 +157,7 @@ You will get a JSON response like this:
 Field **content** is a list containing all the existing apps for the logged account.
 
 
-<!-- tab:List an app -->
+<!-- tab:App info -->
 
 
 

api-limitations.md

@@ -0,0 +1,21 @@
+
+#### You must consider our **API free-tier** has the following limitations:
+
+- You can send up to 1,000 emails per month. This is quite a bit for most of small to medium projects.
+- You can only use your SMTP servers or 3rd party SMTP servers (Google, Outlook, etc.). No access to Queuemail.dev professional SMTP severs.
+- Logs (if activated) are removed by 30 days.
+- Data are hosted in our data infraestructure. No access to configure your own infraestructure (database).
+- Normal queue processing (no priority for send email faster).
+
+
+#### For **professional use** we can offer a custom solution removing these limits:
+
+- More emails per month.
+- Access to Queuemail.dev professional SMTP servers (including option for sending with your own domain).
+- No limit for logs retention.
+- Host all your data in your own database (only you can access these data).
+- Acelerated queue processing (emails are sent faster).
+
+If your are intested in a professional custom solution, please, contact <a href="info@queuemail.dev">info@queuemail.dev</a>.
+
+

logs.md → api-logs.md

@@ -1,6 +1,6 @@
 
 
-Using these endpoint you can manage email logs.
+Using these endpoint you can get email logs.
 
 <!-- tabs:start -->
 

mails.md → api-mails.md

@@ -16,7 +16,7 @@ Using these endpoint you can send (queue up) emails, get emails send information
 |---------|-----------|--------|---------|
 |idapp | App id | Yes |  |
 |from | Email from address | No | App default from email |
-|fromname | Name from address | No | App default from name (for no system SMTPs) |
+|fromname | Name from address | No | App default from name  |
 |tos | Recipients email addresses (comma separeted)  | Yes  |  |
 |tonames | Recipients names (comma separated) | No | Recipients email addresses  |
 |ccs | Carbon copy recipients email addresses (comma separated) | No |  |
@@ -46,7 +46,8 @@ Using these endpoint you can send (queue up) emails, get emails send information
 Specific errors:
 
 1. App not found
-2. Remote host not allowed (App origin domain does not match)
+2. Remote server not allowed: xxxx
+3. Remote domain not allowed: xxxx
 3. No active SMTP for App
 4. Sender domain does not exist
 5. Cannot use includetracking=true if you provide CCS or BCCS. Please, use includetracking=false or remove CCS and BCCS email addressses
@@ -57,6 +58,8 @@ Specific errors:
 11. *replyto* domain has not MX records
 12. All TO recipients are invalid
 13. All TO recipients are blacklisted
+14. For use URL type in attachments your app must be configured with retaindata=true
+15. Emails limit per month exceeded.
 
 
 

smtps.md → api-smtps.md

@@ -1,14 +1,7 @@
 
+You can define one or more SMTP servers asociated to an app. 
 
-You can define one or more SMTPs asociated to an App. 
-
-If you are using *FREE TIER* you must to create at least a SMTP.
-
-If you are using a *PAID PLAN* you don't need to create a SMTP because you can use SYSTEM SMTPs.
-
-With *FREE TIER* SMTP servers you define are been used in RANDOM order.
-
-With a *PAID PLAN* you can define a RANDOM or PRIORITY based strategy for SMTP use.
+If you don't have an own SMTP server you can [get a free SMTP server here](other-freesmtps.md).
 
 <!-- tabs:start -->
 
@@ -77,7 +70,7 @@ You will get a JSON response like this:
 }
 ```
 
-<!-- tab:List SMTPs by app -->
+<!-- tab:List SMTP servers by app -->
 
 
 
@@ -240,7 +233,11 @@ Specific errors:
 
 <!-- tab:Check a SMTP -->
 
-Sends a email to app test email for checking correct SMTP configuration.
+Sends a email to app test email for checking correct SMTP configuration. 
+
+If you receive 200 status SMTP is working correctly. If this SMTP was disabled, it is enabled at this time.
+
+If you receive 406 status SMTP has errors. If this SMTP was enabled, it is disabled at this time.
 
 **REQUEST:** 
 
@@ -267,6 +264,8 @@ Specific errors:
 1. SMTP not found
 2. App not found
 
+... Other errors related with SMTP working.
+
 
 **RESPONSE:**
 

tracking.md → api-tracking.md

@@ -1,6 +1,6 @@
 
 
-Using these endpoint you can manage email tracking: opened emails and email link clicks.
+Using this endpoint you can manage email tracking: opened emails and email link clicks.
 
 <!-- tabs:start -->
 

features-blacklists.md

@@ -0,0 +1,17 @@
+Blacklists feature let recipients to include their email addresses in a blacklist in order to block future email sendings from app asociated to that blacklist.
+
+Also, the system can include a email address in a auto-blacklist when it detects that email address has permanent errors.
+
+That is, each app can contain a blacklist and an auto-blacklist. 
+
+For activating blacklist feature you must use *useblacklist=true* when [creating/editing your app](api-apps.md).
+
+For activating auto-blacklist feature you must use *useautoblacklist=true* when [creating/editing your app](api-apps.md).
+
+
+
+
+
+
+
+

features-dataretention.md

@@ -0,0 +1,15 @@
+Apps, by default, retain subject and body data **until email is sucessfully sent**. Then, these data are permanently removed.
+
+If you want to retain these data permanently, you must use *retaindata=true* when [creating/editing your app](api-apps.md).
+
+If you want to use *attachmenttype=URL* when you [send an email](api-mails.md), you must use *retaindata=true* in your app.
+
+Whether you use *retaindata=true* or not you can call [/private/mails/remove](api-mails.md) endpoint to remove all data and logs of finished emails.
+
+Due to traceability reasons, we do not remove any email address.
+
+Please, read our [private policy](legal-privatepolicy.md) for more info about data privacy. 
+
+
+
+

features-limitorigin.md

@@ -0,0 +1,21 @@
+When [creating/editing your app](api-apps.md) optionally you can set a origin server or IP in order to limit servers/IPs from which [call to send emails](api-mails.md) can be made.
+
+If you don't set this parameter your app can be used from any IP without checking request origin.
+
+For specify origin server you must use *originserver* parameter with values like "*myserver.com*" or "*192.168.0.1*". 
+
+Also, you can specify multiple servers/IPs with comma separated values: "*myserver.com,192.168.0.1*"
+
+If you are using this feature, when sending emails, you will receive error if the origin email does not match with *originserver* specified in your app. At the error description you will get received server/IP as origin of your request. Thus, you can fix *originserver* whith the correct value.
+
+
+
+
+
+
+
+
+
+
+
+

features-loging.md

@@ -0,0 +1,21 @@
+Apps always log email activity and errors. 
+
+Log entries can be related with:
+
+- Emails sucessfully sent.
+- SMTP errors.
+- Erros related with domain/MX DNS zones.
+- Apps/users deactivated.
+- Blacklist/auto-blacklist email addresses.
+
+... and more.
+
+These log entries are deleted by 30 days, but you can use [get email logs](api-logs.md) call for saving pemanent them in your own database.
+
+
+
+
+
+
+
+

features-smtpstrategies.md

@@ -0,0 +1,25 @@
+You can improve app fault tolerance if you define several SMTP servers. 
+
+Thus, if a SMTP fails, then the app will retry to send emails with another one.
+
+When [creating/editing your app](apps.md), you can choose beetween RANDOM and PRIORITY strategies for SMTP selection. 
+
+If you don't specify *strategy* parameter, RANDOM strategy is assumed by default.
+
+If you specify *strategy=PRIORITY*, in each mail sending SMTP server with higher priority will be use at first. In case of error, next SMTP with higher priority will be used, and so on.
+
+You can define priority for each SMTP when [creating/editing your SMTP servers](api-smtps.md).
+
+With *strategy=RANDOM* also any SMTP server are used in case of error using the previous one, but they are randomly selected.
+
+
+
+
+
+
+
+
+
+
+
+

features-webhooks.md

@@ -0,0 +1,17 @@
+Webhooks feature let you to configure your own URLs in order to run processes when an event occurs at queuemail.dev.
+
+There are the following webhook events:
+
+- *sending_finished*: URL is called with param *qm_idsending* (id of sent mail) when email is sucessfully sent.
+- *sending_error*: URL is called with param *qm_idsending* (id of sent mail) when email send fails.
+- *tracking_opened*: URL is called with params *qm_idsending* (id of sent mail) and *qm_email* (recipient email) when email is opened.
+- *tracking_clicked*: URL is called with params *qm_idsending* (id of sent mail), *qm_email* (recipient email) and *qm_url* (url clicked) when recipient clicks a link email (qm_url).
+- *blacklisted_added*: URL is called with params *qm_idsending* (id of sent mail) and *qm_email* (email address to blacklist) when an email address is added to blacklist.
+
+You can configure your webhooks URLs when [creating/editing your app](api-apps.md).
+
+
+
+
+
+