API questions

msantillo

We have some follow-up questions on the API --

 

Follow ups in orange below

 

·         Is there a rate limit on any of the APIs?

·         JobDeliveryStatus mentions that it can be used to query multiple jobs at once, but that it should be limited to a few at a time (https://apiforums.easylink.com/emapidocs/26/JobDeliveryStatus/JobDeliveryStatus.html). Why and what is meant by “a few”? Is there another API that can be used to query, say, 100 jobs at once?

`               Generally, 10 jobs may be a safe limit that would not be subject to timeouts.  Scheduled Reports can run every 15 minutes if the customer has the need.

[SM] Given the situation where we have 1000 jobs outstanding what is the most efficient way to query their statuses, so we can report SUCCESS\FAILURE\IN-PROGRESS to our users?

·         JobState in JobDeliveryStatus lists many possible states

·         Which are the terminal states?

The terminal states are:

4 Error

5 Cancelled

8 Expired

[SM] What are the “success” terminal states?

·         For the Error state, where can we find the error reason\description?

The Error Code and Message will be returned.

[SM] Where in the response is the Error Code and Message? Is there a link you can point me to in the documentation?

·         Is there any way to query all completed jobs (API and mail2fax) by specifying completed time?

JobList can be used to get a list of jobs (all kinds) that completed within a  given period (using JobCompleteWindow).

This will return the job status, not their delivery status. If delivery status is needed, individual status would need to be requested. Also, the job completion time will not match final delivery time.

[SM] Can you explain this further? What is the difference between job status and delivery status? Is job status enough if we just care about reporting SUCCESS\FAILURE\IN-PROGRESS?

 

 

Thanks

tgargiulo

 

We have some follow-up questions on the API --

 

Follow-ups in orange below

[SM]Is there a rate limit on any of the APIs?

 

There
is no automatically enforced rate limit on the APIs. Because of the
highly variable data and performance characteristics, we are not able to
impose a universal rate that would satisfy all customers and still
protect our system. However, if we detect customer activity that does
endanger the service in general (and examples from the past include
making excessive status queries) we may contact the customer and request
changes, or even in some cases temporarily disable or block them.

 

  

[SM]Given the situation where we have 1000 jobs outstanding what is the most efficient way to query their statuses, so we can report SUCCESS\FAILURE\IN-PROGRESS to our users?

 

It really depends on the application. The most *efficient*
way overall to do this is to have a job delivery report pushed to them
(via webservice, ftp, even email) – the report will be sent as soon as
the job is done and can contain all the delivery information.

 

The methods available via the API for destination delivery

status are JobDeliveryStatus and JobDetail. (JobSummary is appropriate
in some circumstances, but it only provides counts, not delivery
details.) Applications that rely on these rather than reports should try
to make as few requests overall as possible – these functions are not
intended to support rapid polling to obtain near-real-time status (and a
pushed report is likely to better satisfy that sort of requirement.) A
well-behaved application would wait a reasonable amount of time to allow
delivery (say a couple of minutes in the case of fax, possibly more if
large documents or many destinations are involved), retry at well-spaced
intervals (and possibly increasing intervals)

if the deliveries are not complete, and stop asking for status once the job is done.

 

If an application has 1000 jobs outstanding (which would

actually be pretty exceptional), and must use JobDeliveryStatus to
collect the status, it would be best to schedule multiple
JobDeliveryStatus requests – possibly aggregating them into small
batches (say, 10) – and then use a small pool of requesters (to limit
the number of concurrent requests) to submit them.

 

 

[SM]What are the “success” terminal states?

 

SENT is the only successful state. In the case of email and sms, that only means we sent it out, not that it was received.

 

From
the point of view of a user application, the “terminal” job states are
usually those that indicate that all the delivery attempts have been
completed – these include Posted, Delivered, Complete, Cancelled,
Purged. For fax jobs, it usually makes little sense to ask again for
status once information with these states has been retrieved. For email
and sms jobs,

subsequent periodic requests to collect events like DSNs might make
sense until the Complete, Cancelled or Purged states show up.

 

There are several forum posts about this, e.g. https://apiforums.easylink.com/content/delivery-status

 

 

[SM]Where in the response is the Error Code and Message? Is there a link you can point me to in the documentation?

 

Please see the following thread and attachments for detailed error information:

https://apiforums.easylink.com/content/gamma-codes

 

Most
API requests include a top-level Status element, which usually
indicates the status of processing the API request itself. So for
instance, in a JDS (JobDeliveryStatus) request, it just means that we
understood the request, that the user was valid, and that we executed
the status requests – a “success” in this status (StatusCode == 0)
merely means that no problems were encountered in processing. If a
problem was encountered, then a non-zero StatusCode should be there (the
values are variable, so we can’t really publish a comprehensive
dictionary), and the Status element may contain an ErrorList element
with one or more Error child elements, and it’s in *those* that the ErrorCode and ErrorMessage will appear. See https://apiforums.easylink.com/emapidocs/26/Common/StatusType.html.

 

For
API functions that may contain a batch of items (like multiple
Message’s in JobSubmit, or multiple JobId’s in JobDeliveryStatus), there
is usually a batch of corresponding items (not necessarily in the same
order) in the result, and each of these may contain a status element
reflecting the processing status for that item. In a
JobDeliveryStatusResult, this is a RecStatus element, and for that type
of element (https://apiforums.easylink.com/emapidocs/26/Common/StatusType.html) there
is a code numeric attribute, and a text value. Again, this reflects the
status of processing the request, not (in the case of JDS) anything to
do with the job being asked about, other than possibly that the job is
not found.

 

For job status, the next level of status information is about

the switch’s processing of the job, e.g. JobState.

 

The
status that most people are ultimately interested in is the delivery
status, right at the bottom of all this. In a JobDeliveryStatusResult,
this is the DeliveryDetail/State element (https://apiforums.easylink.com/emapidocs/26/JobDeliveryStatus/JobDeliveryStatusResult.html#LN106 ),
which contains a text value along with numeric code and gammacode
attributes. The “code” attribute reflects the state of the job’s
processing of the delivery (e.g. 7 for sent, 4 for error or failure to
deliver, 5 for cancelled). The gammacode value is only returned if we
have a non-zero

code from the processing, and is only the numeric value. We don’t return
the text descriptions for gammacodes in API results, but the tables in
the post in the forum contain what we have.

 

[SM]Can
you explain this further? What is the difference between job status and
delivery status? Is job status enough if we just care about reporting
SUCCESS\FAILURE\IN-PROGRESS?

 

See
above. A job might be a single destination or a broadcast to many
destinations, so it has a state all its own which is distinct from the
state of any particular destination, even if there is only one.