SAPO Mail, API de acesso ao Webmail

1. SAPO Mail - Webservices
14 de Novembro 2007
•Nuno Loureiro <nuno@co.sapo.pt>
•Carlos Pires <acmpires@co.sapo.pt>
•André Luís <aluis@co.sapo.pt>

2. SAPO Mail - Webservices
Arquitectura
Aspectos Gerais
Credenciais
Mail
Contactos
Exemplos Práticos

3. Arquitectura do Webmail

4. SAPO Mail - Webservices
Arquitectura
Aspectos Gerais
Credenciais
Mail
Contactos
Exemplos Práticos

5. Mail Webservices - Aspectos Gerais
Operações disponíveis:
Mail:
GetStatus;
GetLastMails;
GetMailbox;
Contactos:
ListAllContacts;
GetContact;
AddContact;
DeleteContact;
SearchContacts;
SetContact.

6. Mail Webservices - Aspectos Gerais
End-Point:
http://services.sapo.pt/Mail
WSDL:
http://services.sapo.pt/Metadata/Contract/Mail
Namespace:
http://services.sapo.pt/definitions
Exemplo Prático:
http://services.mail.sapo.pt/codebits
Operator (Firefox):
http://addons.mozilla.org/en-US/firefox/addon/4106
User-script para Operator (Firefox):
http://services.mail.sapo.pt/operator/js/sapomail.js

7. SAPO Mail - Webservices
Arquitectura
Aspectos Gerais
Credenciais
Mail
Contactos
Exemplos Práticos

8. Mail Webservices - Credenciais - Objecto ESBCredentials
1
ESBCredentials
• ESBUsername
• ESBPassword
Usado para a autenticação nos webservices do mail;
Todas as operações dos webservices do mail requerem a definição
de um SOAP Header com as credenciais do utilizador.
class ESBCredentials {
public $ESBUsername; //string
public $ESBPassword; //string
}

9. SAPO Mail - Webservices
Arquitectura
Aspectos Gerais
Credenciais
Mail
Contactos
Exemplos Práticos

10. Mail Webservices - Mail - Objectos
1
Mailbox
• Status
• ArrayOfLastMail
ArrayOfLastMail
• PageInfo
• LastMail
Status PageInfo LastMail
• Total • PageNumber • MessageId • Recent
• Unseen • RecordsCount • FromName • Answered
• Recent • MaxRecords • FromEMail • Deleted
• Subject • Flagged
• Date • Size (in bytes)
• Seen

11. Mail Webservices - Mail - Operações (1)
GetStatus
GetStatus
class Status {
public $Total; //int
public $Unseen; //int
public $Recent; //int
}

12. Mail Webservices - Mail - Operações (2)
GetLastMails
GetLastMails • page (1 by default)
• limit (10 by default, max 50)
 Headers das mensagens pedidas;
 Ordenação: ARRIVAL DATE DESC
class ArrayOfLastMail {
public $PageInfo;
public $LastMail = array(); class LastMail {
} public $MessageId; //int (imap uid)
public $FromName; //string
public $FromEMail; //string
public $Subject; //string
public $Date; //string
class PageInfo { public $Seen; //boolean
public $PageNumber; //int public $Recent; //boolean
public $RecordsCount; //int public $Answered; //boolean
public $MaxRecords; //int public $Deleted; //boolean
} public $Flagged; //booelan
public $Size; //int (in bytes)
}

13. Mail Webservices - Mail - Operações (3)
GetMailbox
GetMailbox • page (1 by default)
• limit (10 by default, max 50)
class Mailbox {
public $Status;
public $ArrayOfLastMail;
class ArrayOfLastMail {
} public $PageInfo; //PageInfo
public $LastMail = array(); //LastMail
}
class Status {
public $Total; //int
 Headers das mensagens pedidas;
public $Unseen; //int
public $Recent; //int
 Ordenação: ARRIVAL DATE DESC
}

14. Mail Webservices - Mail

15. SAPO Mail - Webservices
Arquitectura
Aspectos Gerais
Credenciais
Mail
Contactos
Exemplos Práticos

16. Mail Webservices - Contactos - Objectos
1
ArrayOfContact
• ContactInfo
• Contact
ContactInfo
Contact
• ContactId • CellPhone • RecordsCount
• Name • Fax • SearchExpression (opcional)
• Alias • Title
• Email • Company
• HomeAddress • Notes
• WorkAddress • PGPPublicKey
• HomePhone • SMimePublicKey
• WorkPhone • FreeBusyURL

17. Mail Webservices - Contactos - Operações (1)
ListAllContacts
ListAllContacts
class Contact {
public $ContactId; //string
public $Name; //string
class ArrayOfContact {
public $Alias; //string
public $ContactInfo;
public $Email; //string
public $Contact = array(); public $HomeAddress; //string
} public $WorkAddress; //string
public $HomePhone; //string
public $WorkPhone; //string
public $CellPhone; //string
public $Fax; //string
public $Title; //string
class ContactInfo {
public $Company; //string
public $RecordsCount; //int
public $Notes; //string
public $SearchExpression; //string
public $PGPPublicKey; //string
}
public $SMimePublicKey; //string
public $FreeBusyURL; //string
}

18. Mail Webservices - Contactos - Operações (2)
GetContact
GetContact • ContactID (string)
class Contact {
public $ContactId; //string
public $Name; //string
public $Alias; //string
public $Email; //string
public $HomeAddress; //string
public $WorkAddress; //string
public $HomePhone; //string
public $WorkPhone; //string
public $CellPhone; //string
public $Fax; //string
public $Title; //string
public $Company; //string
public $Notes; //string
public $PGPPublicKey; //string
public $SMimePublicKey; //string
public $FreeBusyURL; //string
}

19. Mail Webservices - Contactos - Operações (3)
AddContact
AddContact • Contact (object)
 Campo gerado pelo webservice:
 ContactId;
 Obrigatório:
 Name.
057259c0271b5cf71bb8e9be7ace49e2
ContactId (hash md5)

20. Mail Webservices - Contactos - Operações (4)
SetContact
SetContact • ContactID (string)
• Contact (object)
 Campo ignorado pelo webservice:
 ContactId;
true false
Sucesso Erro

21. Mail Webservices - Contactos - Operações (5)
SearchContact
SearchContact • SearchExpression (string != ‘’)  Nome
 E-mail
class Contact {
class ArrayOfContact {
public $ContactId; //string
public $ContactInfo; public $Name; //string
public $Contact = array(); public $Alias; //string
} public $Email; //string
public $HomeAddress; //string
public $WorkAddress; //string
public $HomePhone; //string
public $WorkPhone; //string
public $CellPhone; //string
class ContactInfo {
public $Fax; //string
public $RecordsCount; //int
public $Title; //string
public $SearchExpression; //string
public $Company; //string
}
public $Notes; //string
public $PGPPublicKey; //string
public $SMimePublicKey; //string
public $FreeBusyURL; //string
}

22. Mail Webservices - Contactos - Operações (6)
DeleteContact
DeleteContact • ContactID (string)
true false
Sucesso Erro

23. Mail Webservices - Contactos

24. Mail Webservices - Contactos

25. SAPO Mail - Webservices
Arquitectura
Aspectos Gerais
Credenciais
Mail
Contactos
Exemplos Práticos

26. Mail Webservices - Exemplos Práticos - SOAP Request
<?xml version=quot;1.0quot; encoding=quot;UTF-8quot;?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV=quot;http://schemas.xmlsoap.org/soap/envelope/quot;
xmlns:ns1=quot;http://services.sapo.pt/definitionsquot;>
<SOAP-ENV:Header>
<ns1:ESBCredentials>
<ns1:ESBUsername>someuser@sapo.pt</ns1:ESBUsername>
<ns1:ESBPassword>somepass</ns1:ESBPassword>
</ns1:ESBCredentials>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns1:GetMailbox>
<ns1:page>1</ns1:page>
<ns1:limit>10</ns1:limit>
</ns1:GetMailbox>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

27. Mail Webservices - Exemplos Práticos - SOAP Request
<?xml version=quot;1.0quot; encoding=quot;UTF-8quot;?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV=quot;http://schemas.xmlsoap.org/soap/envelope/quot;
xmlns:ns1=quot;http://services.sapo.pt/definitionsquot;>
<SOAP-ENV:Header>
<ns1:ESBCredentials>
<ns1:ESBUsername>someuser@sapo.pt</ns1:ESBUsername>
<ns1:ESBPassword>somepass</ns1:ESBPassword>
</ns1:ESBCredentials>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns1:ListAllContacts/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

28. Mail Webservices - Exemplos Práticos - PHP5 Client Example
<?php
require_once dirname(__FILE__) . '/Mail_client_conf.php'; // Config
require_once dirname(__FILE__) . '/Mail_types.php'; // Class types
$user = 'someuser@sapo.pt';
$pass = 'somepass';
$ESBC = new ESBCredentials_t();
$ESBC->ESBUsername = $user;
$ESBC->ESBPassword = $pass;
$GetMailbox = new GetMailbox_t();
$GetMailbox->page = 1;
$GetMailbox->limit = 10;
$paramMailbox = (isset($GetMailbox))
? array('parameters' => $GetMailbox)
: array();
// [ ---> Continua ]

29. Mail Webservices - Exemplos Práticos - PHP5 Client Example (2)
$client = new SoapClient(
/* This should be local, avoid one network call */
'http://services.sapo.pt/Metadata/Contract/Mail',
array('location' => quot;http://services.sapo.pt/Mailquot;,
'classmap' => $classmap)
);
$header = new SoapHeader('http://services.sapo.pt/definitions',
'ESBCredentials', $ESBC);
try {
$response = $client->__soapCall('GetMailbox', $paramMailbox, null,
$header);
/* Your Code Here */
} catch (SoapFault $e) {
$text = (!$e->getMessage()) ? $e->faultstring : $e->getMessage();
echo quot;SOAP FAULT: $textnquot;;
}
?>

30. Mail Webservices - Exemplos Práticos - PHP CodeGenerator
<?php
require_once dirname(__FILE__) . '/Mail_client_conf.php';
require_once dirname(__FILE__) . '/Mail_client.php';
$client = new Mail_client($conf);
$client->makeHeader('someuser@sapo.pt', 'somepass');
/* GetMailbox(page, limit) */
$response = $client->GetMailbox(1, 10);
/* ListAllContacts */
//$response = $client->ListAllContacts();
/* AddContact(Contact) */
//$Contact = new Contact_t();
//$Contact->Name = 'somename';
// ...
//$response = $client->AddContact($Contact);
/* Your Code Here */
?>

31. Mail Webservices - Exemplos Práticos - Em Acção (1)
Agora é tempo de ver tudo isto em acção:
Listagem de Mails e Contactos:
Webservices:
GetMailbox;
ListAllContacts;
Importação de contactos para o webmail:
Webservices:
AddContact;
Ferramentas:
Microformatos;
Operator (extensão Firefox);

32. Mail Webservices - Exemplos Práticos - Em Acção (2)
Screencasts de demos de utilização:
ListAllContacts:
http://services.mail.sapo.pt/codebits/swf/ListAllContacts.swf
GetMailbox:
http://services.mail.sapo.pt/codebits/swf/GetMailbox.swf
Screencast de instalação e uso de um user-script para a extensão
para Firefox Operator:
Adicionar hCard de uma página ao webmail do SAPO:
http://services.mail.sapo.pt/codebits/swf/Operator.swf

33. http://mail.blogs.sapo.pt/