Documentação da API de integração @MediaPost

Início

Introdução

A interface de serviços da @MediaPost provê uma API RESTFul para efetuar operações e consultas na sua conta facilitando a integração com as mais diversas aplicações.

A API possui um sistema de autenticação e toda operação é registrada para maior segurança e rastreabilidade.

Aqui você encontrará todas as informações necessárias para integrar seu sistema com sua conta @MediaPost.


Chaves de Acesso

Para conectar-se à sua conta através da API precisará das 4 chaves abaixo:

  • Consumer Key
  • Consumer Secret
  • Token
  • Token Secret

A solicitação destas deve ser realizada através da Cental de Chamados na própria conta.

Se for cliente, acesse sua conta, clique no menu Suporte, depois em Meus chamados e, por último, clique no botão Novo chamado. Através dele solicite as chaves de integração via API.


Autenticação

A API utiliza o OAuth 1.0 para efetuar a autenticação de clientes, por ser um formato aberto, de ampla utilização e mais seguro do que o Basic-Auth do HTTP.

A autenticação será feita utilizando uma consumer key, consumer secret, token e token secret que serão fornecidos no momento da solicitação das credenciais.

Utilizamos autenticação OAuth com o suporte a assinatura HMAC-SHA1, neste caso o cliente do serviço deve enviar na requisição os parâmetros oauth_signature e oauth_signature_method, conforme a especificação do protocolo.

Mais informações sobre o protocolo OAuth poderão ser encontradas no site oauth.net (inglês)


Formato das respostas

Todos os recursos suportam o envio de respostas nos formatos JSON e XML, sendo JSON o formato padrão. Para obter a resposta basta enviar na requisição HTTP um cabeçalho Accept:

  • Para formato JSON:
Accept: application/json
  • Para formato XML:
Accept: application/xml
  • Para formato PHP (serializado):
Accept: application/php

Resposta padrão

Toda resposta possui um bloco response padrão com os campos:

  • status → Código do status HTTP retornado
  • messagem → Uma mensagem legível sobre a resposta
  • erro → Pode ser true ou false, indicando se a resposta é um erro ou não (valor true indica erro)
  • cod_erro → Código do erro ocorrido, caso o campo erro seja igual a true

Para operações de criação/alteração de informações é sempre retornada uma resposta num formato padrão:

  • JSON
{
	"response" :
		{ 
			"status" : 200,
			"message" : "Mensagem",
			"error" : false
		},
	"usuarios": [
		{"codigo": 1, "nome": "Zé" },
		{"codigo": 2, "nome": "Felipe" },
	]
}
  • XML
<iso_response>
	<response>
		<status>200</status>
		<message>Mensagem</status>
		<error>false</error>
		<cod_erro>0</cod_erro>
	</response> 
</iso_response>

Em adição ao bloco response podem ser retornados outros blocos, que estarão especificados na documentação dos produtos.


Lista de valores

Diversos métodos de consultas costumam retornar listas de valores. Isto pode causar algumas diferenças dependendo do formato de resposta solicitado. Conforme mostrado a seguir.

  • JSON

No JSON os valores que são listas de itens são encodados como arrays, como no exemplo abaixo:

{
	"response" :
		{
			"status" : 200,
			"message" : "Mensagem",
			"error" : false
		},
	"usuarios": [
		{"codigo": 1, "nome": "Zé" },
		{"codigo": 2, "nome": "Felipe" },
	]
}
  • XML

No XML as listas tem um comportamento um pouco diferente, elas são encapsuladas numa tag list [nome_campo] que contém X blocos [nome_campo], assim:

<iso_response> 
	<response> 
		<status>200</status> 
		<message>Mensagem</status>
		<error>false</error>
	</response>
	<list_usuario>
		<usuario>
			<codigo>1</codigo>
			<nome>Zé</nome>
		</usuario>
		<usuario>
			<codigo>2</codigo>
			<nome>Felipe</nome>
		</usuario>
	</list_usuario>
</iso_response>

Datas

As datas e intervalos de tempo utilizados (tanto em requisições quanto em respostas) devem estar no formato ISO-8601, por exemplo, uma ordem efetuada em 25 de maio de 2010 será retornada como:

  • 2010-05-25

Para um valor que seja retornado como data e hora, temos:

  • 2010-05-25T04:08:15

Para intervalos na norma ISO-8601, temos:

  • 2010-05-25T04:08:15/2011-05-25T15:16:23

Recursos

Conta

Abaixo você encontrará todos os recursos disponíveis para gerenciar sua conta:

Saldo da conta

Este recurso retorna o saldo disponível para envios da conta

Este saldo pode alterar caso existam envios agendados ou em andamento

  • URL:
https://api.mediapost.com.br/envio/limite
  • Método:
GET
  • Exemplo de requisição (PHP):
try { 
	$arrResult = $mapi->get("envio/limite");
	echo "</pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [saldo] => 298684
    [banda] => 7467100
    [str_saldo] => 298.684 envios
    [str_banda] => 7.292,09 Mb
)

Parâmetros obrigatórios

  • Este recurso não possui parâmetros obrigatórios

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Saldo do usuário

Este recurso retorna o saldo disponível para envios do usuário

Este saldo pode alterar caso existam envios agendados ou em andamento

  • URL:
https://api.mediapost.com.br/envio/limite/usuario/[_usuario_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$usuario = 1; // Pode ser o ID ou Username

try { 
	$arrResult = $mapi->get("envio/limite/usuario/".$usuario);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [id_usuario] => 1
    [saldo] => 6000
)

Parâmetros obrigatórios

  • usuário → ID ou nome do usuário (username)

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Contato

Abaixo você encontrará todos os recursos disponíveis para gerenciar os contatos de sua conta:

Buscar campos

Este recurso retorna todos os campos disponíveis para um contato

  • URL:
https://api.mediapost.com.br/contato/campos
  • Método:
GET
  • Exemplo de requisição (PHP):
try { 
	$arrResult = $mapi->get("contato/campos");
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [sexo] => Sexo
    [endereco] => Logradouro
    [cep] => CEP
    [telefone] => Telefone
    [celular] => Celular
    [nome] => Nome
    [email] => E-Mail
    [estado] => Estado
    [data_nascimento] => Data de Nascimento
    [cidade] => Cidade
    [bairro] => Bairro
    [empresa] => Empresa
    [cargo] => Cargo
    [livre1] => Campo Livre 1
    [livre2] => Campo Livre 2
    [livre3] => Campo Livre 3
    [livre4] => Campo Livre 4
    [livre5] => Campo Livre 5
    [livre6] => Campo Livre 6
    [livre7] => Campo Livre 7
    [livre8] => Campo Livre 8
)

Parâmetros obrigatórios

  • Este recurso não possui parâmetros obrigatórios

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Buscar contato pelo código

Este recurso retorna as informações de um contato baseado no código (ID)

  • URL:
https://api.mediapost.com.br/contato/cod/[_cod_contato_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$cod_contato = 1;

try { 
	$arrResult = $mapi->get("contato/cod/".$cod_contato);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [cod] => 1
    [nome] => Pedro
    [email] => pedro@dominio.com.br
    [livre1] => Livre 1
    [livre2] => Livre 2
    [livre3] => Livre 3
    [livre4] => Livre 4
    [livre5] => Livre 5
    [livre6] => Livre 6
    [livre7] => Livre 7
    [livre8] => Livre 8
    [bairro] => Pinheiros
    [cargo] => Programador
    [celular] => 11922358413
    [cep] => 05415012
    [cidade] => São Paulo
    [data_nascimento] => 1980-01-01
    [empresa] => MediaPost
    [endereco] => Rua Joaquim Antunes, 767
    [estado] => São Paulo
    [fax] => 1130693939
    [observacao] => Observação do contato
    [pais] => Brasil
    [ramo_atividade] => Serviços de Internet
    [sexo] => M
    [tel_comercial] => 1130693939
    [telefone] => 1130693939
)

Parâmetros obrigatórios

  • cod_contato → ID do contato na ferramenta @MediaPost

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Buscar contato pelo e-mail

Este recurso retorna as informações de um contato baseado no endereço de e-mail

  • URL:
https://api.mediapost.com.br/contato/email/[_email_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$email_contato = "pedro@dominio.com.br";

try { 
	$arrResult = $mapi->get("contato/email/".$email_contato);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [cod] => 1
    [nome] => Pedro
    [email] => pedro@dominio.com.br
    [livre1] => Livre 1
    [livre2] => Livre 2
    [livre3] => Livre 3
    [livre4] => Livre 4
    [livre5] => Livre 5
    [livre6] => Livre 6
    [livre7] => Livre 7
    [livre8] => Livre 8
    [bairro] => Pinheiros
    [cargo] => Programador
    [celular] => 11922358413
    [cep] => 05415012
    [cidade] => São Paulo
    [data_nascimento] => 1980-01-01
    [empresa] => MediaPost
    [endereco] => Rua Joaquim Antunes, 767
    [estado] => São Paulo
    [fax] => 1130693939
    [observacao] => Observação do contato
    [pais] => Brasil
    [ramo_atividade] => Serviços de Internet
    [sexo] => M
    [tel_comercial] => 1130693939
    [telefone] => 1130693939
)

Parâmetros obrigatórios

  • email_contato → Endereço de e-mail do contato na ferramenta @MediaPost

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Buscar múltiplos contatos pelo e-mail

Este recurso retorna as informações de múltiplos contatos baseado no endereço de e-mail

Caso o contato não exista, será retornado o valor false

  • URL:
https://api.mediapost.com.br/contato/fetch
  • Método:
POST
  • Exemplo de requisição (PHP):
$array_emails = array(
	'email' => http_build_query(
		array(
			'pedro@dominio.com.br',
			'inexistente@dominio.com.br'
		), '', '&'
	)
);

try { 
	$arrResult = $mapi->post("contato/fetch",$array_emails);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [pedro@dominio.com.br] => Array
        (
            [cod] => 64
            [nome] => Pedro
            [email] => pedro@dominio.com.br
            [livre1] => 
            [livre2] => 
            [livre3] => 
            [livre4] => 
            [livre5] => 
            [livre6] => 
            [livre7] => 
            [livre8] => 
            [bairro] => 
            [cargo] => 
            [celular] => 
            [cep] => 
            [cidade] => 
            [data_nascimento] => 
            [empresa] => 
            [endereco] => 
            [estado] => 
            [fax] => 
            [observacao] => 
            [pais] => 
            [ramo_atividade] => 
            [sexo] => 
            [tel_comercial] => 
            [telefone] => 
        )
    [inexistente@email.com] => 
)

Parâmetros obrigatórios

  • email → Endereços de e-mail que deseja buscar na ferramenta @MediaPost

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Salvar contato

Este recurso grava um contato na ferramenta @MediaPost

É recomentado que essa operação seja feita em lotes de no máximo 500 contatos por vez para que a conexão não atinga o tempo limite

  • URL:
https://api.mediapost.com.br/contato/salvar
  • Método:
PUT
  • Exemplo de requisição (PHP):
$arrContato = array();
					
$arrContato['lista'] = 576;
$arrContato['contato'][0]['email'] = "pedro@dominio.com.br";
$arrContato['contato'][0]['uidcli'] = 1;
$arrContato['contato'][0]['nome'] = "Pedro";

try { 
	$arrResult = $mapi->put("contato/salvar", $arrContato);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [0] => Array
        (
            [uidcli] => 1
            [cod] => 187424
            [nome] => Pedro
            [email] => pedro@dominio.com.br
        )

)

Parâmetros obrigatórios

  • lista → ID da lista onde o contato está ser salvo na ferramenta @MediaPost
  • contato/email → Endereço de e-mail do contato (max. 100 caracteres)

Parâmetros opcionais

  • contato/uidcli → ID do contato em seu sistema (max. 19 caracteres)
  • contato/nome → Nome do contato (max. 100 caracteres)
  • contato/bairro → Bairro do contato (max. 50 caracteres)
  • contato/cargo → Cargo do contato (max. 100 caracteres)
  • contato/celular → Número do celular do contato (max. 30 caracteres)
  • contato/fax → Número do FAX do contato (max. 30 caracteres)
  • contato/tel_comercial → Número do telefone comercial do contato (max. 30 caracteres)
  • contato/telefone → Número do telefone do contato (max. 30 caracteres)
  • contato/cep → CEP do contato (max. 10 caracteres)
  • contato/cidade → Cidade do contato (max. 50 caracteres)
  • contato/estado → Estado do contato (UF)
  • contato/pais → País do contato (max. 50 caracteres)
  • contato/data_nascimento → Data de nascimento do contato (AAAA-MM-DD)
  • contato/empresa → Empresa do contato (max. 100 caracteres)
  • contato/endereco → Endereço do contato (max. 255 caracteres)
  • contato/ramo_atividade → Ramo de atividade do contato (max. 100 caracteres)
  • contato/sexo → Sexo do contato (F ou M)
  • contato/observacao → Observações do contato (max. 1000 caracteres)
  • contato/livre1 → Campo livre 1 (max. 255 caracteres)
  • contato/livre2 → Campo livre 2 (max. 255 caracteres)
  • contato/livre3 → Campo livre 3 (max. 255 caracteres)
  • contato/livre4 → Campo livre 4 (max. 255 caracteres)
  • contato/livre5 → Campo livre 5 (max. 255 caracteres)
  • contato/livre6 → Campo livre 6 (max. 255 caracteres)
  • contato/livre7 → Campo livre 7 (max. 255 caracteres)
  • contato/livre8 → Campo livre 8 (max. 255 caracteres)

Alterar contato

Este recurso atualiza o cadastro de um contato na ferramenta @MediaPost

A atualização é baseada no endereço de e-mail do contato

É recomentado que essa operação seja feita em lotes de no máximo 500 contatos por vez para que a conexão não atinga o tempo limite

  • URL:
https://api.mediapost.com.br/contato/salvar
  • Método:
PUT
  • Exemplo de requisição (PHP):
$arrContato = array();
					
$arrContato['lista'] = 576;
$arrContato['contato'][0]['email'] = "pedro@dominio.com.br";
$arrContato['contato'][0]['uidcli'] = 1;
$arrContato['contato'][0]['nome'] = "Pedro Silva";
$arrContato['contato'][0]['telefone'] = "11 3069-3939";

try { 
	$arrResult = $mapi->put("contato/salvar", $arrContato);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [0] => Array
        (
            [uidcli] => 1
            [cod] => 187424
            [nome] => Pedro Silva
            [email] => pedro@dominio.com.br
        )

)

Parâmetros obrigatórios

  • lista → ID da lista onde o contato está ser salvo na ferramenta @MediaPost
  • contato/email → Endereço de e-mail do contato (max. 100 caracteres)

Parâmetros opcionais

  • contato/uidcli → ID do contato em seu sistema (max. 19 caracteres)
  • contato/nome → Nome do contato (max. 100 caracteres)
  • contato/bairro → Bairro do contato (max. 50 caracteres)
  • contato/cargo → Cargo do contato (max. 100 caracteres)
  • contato/celular → Número do celular do contato (max. 30 caracteres)
  • contato/fax → Número do FAX do contato (max. 30 caracteres)
  • contato/tel_comercial → Número do telefone comercial do contato (max. 30 caracteres)
  • contato/telefone → Número do telefone do contato (max. 30 caracteres)
  • contato/cep → CEP do contato (max. 10 caracteres)
  • contato/cidade → Cidade do contato (max. 50 caracteres)
  • contato/estado → Estado do contato (UF)
  • contato/pais → País do contato (max. 50 caracteres)
  • contato/data_nascimento → Data de nascimento do contato (AAAA-MM-DD)
  • contato/empresa → Empresa do contato (max. 100 caracteres)
  • contato/endereco → Endereço do contato (max. 255 caracteres)
  • contato/ramo_atividade → Ramo de atividade do contato (max. 100 caracteres)
  • contato/sexo → Sexo do contato (F ou M)
  • contato/observacao → Observações do contato (max. 1000 caracteres)
  • contato/livre1 → Campo livre 1 (max. 255 caracteres)
  • contato/livre2 → Campo livre 2 (max. 255 caracteres)
  • contato/livre3 → Campo livre 3 (max. 255 caracteres)
  • contato/livre4 → Campo livre 4 (max. 255 caracteres)
  • contato/livre5 → Campo livre 5 (max. 255 caracteres)
  • contato/livre6 → Campo livre 6 (max. 255 caracteres)
  • contato/livre7 → Campo livre 7 (max. 255 caracteres)
  • contato/livre8 → Campo livre 8 (max. 255 caracteres)

Excluir contato

Este recurso remove o vínculo do contato com todas as listas existentes na ferramenta @MediaPost

O contato permanecerá no banco de dados da conta sem vínculo com as listas e deixará de ser exibido na interface da ferramenta

  • URL:
https://api.mediapost.com.br/contato/cod/[_cod_contato_]
  • Método:
DELETE
  • Exemplo de requisição (PHP):
$cod_contato = 187424;

try { 
	$arrResult = $mapi->delete("contato/cod/".$cod_contato);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
O contato 187424 foi excluído!

Parâmetros obrigatórios

  • cod_contato → ID do contato na ferramenta @MediaPost

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Lista

Abaixo você encontrará todos os recursos disponíveis relacionados às listas de contatos:

Buscar todas as listas

Este recurso retorna todas listas existentes em sua conta @MediaPost

  • URL:
https://api.mediapost.com.br/lista/all
  • Método:
GET
  • Exemplo de requisição (PHP):
try { 
	$arrResult = $mapi->get("lista/all");
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(

    [0] => Array
        (
            [cod] => 573
            [nome] => Contatos Especiais
            [total] => 2119
            [total_ativo] => 2096
            [total_inativo] => 23
        )

    [1] => Array
        (
            [cod] => 576
            [nome] => Testes API
            [total] => 1
            [total_ativo] => 1
            [total_inativo] => 0
        )

)

Parâmetros obrigatórios

  • Este recurso não possui parâmetros obrigatórios

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Buscar lista

Este recurso retorna as informações de uma lista existente em sua conta @MediaPost

  • URL:
https://api.mediapost.com.br/lista/cod/[_cod_lista_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$cod_lista = 573;

try { 
	$arrResult = $mapi->get("lista/cod/".$cod_lista);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [cod] => 573
    [nome] => Contatos Especiais
    [total] => 2119
    [total_ativo] => 2096
    [total_inativo] => 23
)

Parâmetros obrigatórios

  • cod_lista → ID da lista na ferramenta @MediaPost

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Salvar lista

Este recurso cria uma nova lista de contatos em sua conta @MediaPost

  • URL:
https://api.mediapost.com.br/lista/salvar
  • Método:
POST
  • Exemplo de requisição (PHP):
$arrLista['nome'] = 'Minha lista de contatos';
$arrLista['id_usuario'] = '1';
					

try { 
	$arrResult = $mapi->post("lista/salvar", $arrLista);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [cod] => 577
    [nome] => Minha lista de contatos
    [total] => 
    [total_ativo] => 
    [total_inativo] => 
)

Parâmetros obrigatórios

  • nome → Nome da lista que deve ser salva na ferramenta @MediaPost

Parâmetros opcionais

  • id_usuario → ID do usuário que poderá ter acesso à lista na ferramenta @MediaPost

Mensagem

Abaixo você encontrará todos os recursos disponíveis relacionados às mensagens:

Criar mensagem

Este recurso cria uma nova mensagem em sua conta @MediaPost

  • URL:
https://api.mediapost.com.br/mensagem/salvar
  • Método:
PUT
  • Exemplo de requisição (PHP):
$arrMensagem['uidcli'] = 1;
					
$arrMensagem['remetente']['nome'] = "Pedro Silva";
$arrMensagem['remetente']['email'] = "pedro@dominio.com.br";

$arrMensagem['pasta'] = "API"; // Ou $arrMensagem['id_campanha'] = 38;

$arrMensagem['mensagem']['ganalytics'] = "CampanhaAPI";
$arrMensagem['mensagem']['assunto'] = "Insira aqui o assunto de sua mensagem";
$arrMensagem['mensagem']['html'] = 'Insira aqui todo o código HTML de sua mensagem';
$arrMensagem['mensagem']['texto'] = "Insira aqui a versão de apenas texto (sem tags HTML) de sua mensagem";


try { 
	$arrResult = $mapi->put("mensagem/salvar", $arrMensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [0] => Array
        (
            [cod] => 7508
        )

    [1] => Array
        (
            [uidcli] => 897
        )

)

Parâmetros obrigatórios

  • remetente/nome → Nome do remetente da mensagem
  • remetente/email → Endereço de e-mail do remetente da mensagem
  • mensagem/assunto → Assunto da mensagem
  • mensagem/html → Código HTML da mensagem
  • pasta ou id_campanha → Campanha (Pasta) onde a mensagem deve ser salva na ferramenta @MediaPost

Parâmetros opcionais

  • uidcli → Código de seu sistema
  • mensagem/ganalytics → Texto para integração com Google Analytics
  • mensagem/texto → Versão em texto puro da mensagem

Alterar mensagem

Este recurso altera as informações e conteúdo de uma mensagem salva em sua conta @MediaPost

  • URL:
https://api.mediapost.com.br/mensagem/salvar
  • Método:
PUT
  • Exemplo de requisição (PHP):
$arrMensagem['uidcli'] = 1;
					
$arrMensagem['cod'] = 7508;
					
$arrMensagem['remetente']['nome'] = "Pedro Silva";
$arrMensagem['remetente']['email'] = "pedro@dominio.com.br";

$arrMensagem['pasta'] = "API";

$arrMensagem['mensagem']['ganalytics'] = "CampanhaAPI";
$arrMensagem['mensagem']['assunto'] = "Insira aqui o assunto de sua mensagem";
$arrMensagem['mensagem']['html'] = 'Insira aqui todo o código HTML de sua mensagem';
$arrMensagem['mensagem']['texto'] = "Insira aqui a versão de apenas texto (sem tags HTML) de sua mensagem";

try { 
	$arrResult = $mapi->put("mensagem/salvar", $arrMensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [0] => Array
        (
            [cod] => 7508
        )

    [1] => Array
        (
            [uidcli] => 897
        )

)

Parâmetros obrigatórios

  • cod → ID da mensagem à ser alterada
  • remetente/nome → Nome do remetente da mensagem
  • remetente/email → Endereço de e-mail do remetente da mensagem
  • mensagem/assunto → Assunto da mensagem
  • mensagem/html → Código HTML da mensagem
  • pasta → Pasta onde a mensagem deve ser salva na ferramenta @MediaPost

Parâmetros opcionais

  • uidcli → Código de seu sistema
  • mensagem/ganalytics → Texto para integração com Google Analytics
  • mensagem/texto → Versão em texto puro da mensagem

Listar mensagens

Este recurso lista todas as mensagens criadas em sua conta @MediaPost

  • URL:
https://api.mediapost.com.br/mensagem/listar
  • Método:
POST
  • Exemplo de requisição (PHP):
try { 
	$arrResult = $mapi->post("mensagem/listar");
	echo "</pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [7508] => Array
        (
            [cod] => 7508
            [status] => 1
            [status_nome] => Aguardando Envio
            [nome] => Alterada
            [titulo] => Alterada
            [data] => 
            [codPasta] => 37
        )

    [7507] => Array
        (
            [cod] => 7507
            [status] => 4
            [status_nome] => Enviada
            [nome] => 11/01/2016 - Saiba quantos dos seus e-mails chegam na caixa de entrada
            [titulo] => Saiba quantos dos seus e-mails chegam na caixa de entrada
            [data] => 2016-01-11 13:29:18
            [codPasta] => 35
        )
)

Parâmetros obrigatórios

  • Este recurso não possui parâmetros obrigatórios

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Buscar mensagem

Este recurso retorna as informações de uma mensagem, inclusive, data e hora de envio, caso ela já tenha sido disparada

  • URL:
https://api.mediapost.com.br/mensagem/cod/[_cod_mensagem_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$id_mensagem = 7507;

try { 
	$arrResult = $mapi->get("mensagem/cod/".$id_mensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [cod] => 7507
    [cod_estado] => 4
    [desc_estado] => Enviada
    [nome] => 11/01/2016 - Saiba quantos dos seus e-mails chegam na caixa de entrada
    [titulo] => Saiba quantos dos seus e-mails chegam na caixa de entrada
    [remetente] => "Ademir Diniz - Email Marketing com Resultado" 
    [data] => 2016-01-11 13:29:18
    [codPasta] => 35
    [enviada] => 1
    [consolidada] => 1
)

Parâmetros obrigatórios

  • id_mensagem → ID da mensagem à ser buscada

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Envio

Abaixo você encontrará todos os recursos disponíveis para gerenciar os envios:

Realizar envio

Este recurso realiza o envio de uma mensagem imediatamente

Você pode definir filtros e enviar sua mensagem para um público específico de suas listas de contatos

  • URL:
https://api.mediapost.com.br/envio/cod/[_cod_mensagem_]
  • Método:
PUT
  • Exemplo de requisição (PHP):
$arrEnvio['lista'][] = 749;

$cod_mensagem = 398;

$arrEnvio['filtro']['dominio'][] = "gmail.com, hotmail.com";
$arrEnvio['filtro']['sexo'][] = "M";
$arrEnvio['filtro']['mes_aniversario'][] = "3";

try { 
	$arrResult = $mapi->put("envio/cod/".$cod_mensagem, $arrEnvio);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [cod_agenda] => 401858
)

Parâmetros obrigatórios

  • lista → IDs das listas para quais a mensagem será enviada
  • cod_mensagem → ID da mensagem que será enviada

Parâmetros opcionais

  • id_usuario → ID do usuário que será responsável pelo envio. Os créditos consumidos no envio serão debitados do saldo deste usuário, caso tenha.
  • filtro/dominio → Domínios que devem participar do envio
  • filtro/dominio_not → Domínios que não devem participar do envio
  • filtro/dia_aniversario → Dia de aniversário (DD) Ex.: 01, 02, 03 ... 31
  • filtro/mes_aniversario → Mês de aniversário (MM) Ex.: 01, 02, 03 ... 12
  • filtro/dia_mes_aniversario → Dia e Mês de aniversário (DD/MM) Ex.: 01/01, 05/04, 15/12
  • filtro/ano_nascimento → Ano de nascimento (AAAA) Ex.: 1995, 2000, 2005
  • filtro/data_nascimento → Data de nascimento (DD/MM/AAAA) Ex.: 18/01/2017
  • filtro/sexo → Sexo (F ou M)
  • filtro/bairro → Bairro
  • filtro/cidade → Cidade
  • filtro/estado → Estado
  • filtro/ramo_atividade → Ramo de atividade
  • filtro/empresa → Empresa
  • filtro/cargo → Cargo
  • filtro/livre1 → Campo livre 1
  • filtro/livre2 → Campo livre 2
  • filtro/livre3 → Campo livre 3
  • filtro/livre4 → Campo livre 4
  • filtro/livre5 → Campo livre 5
  • filtro/livre6 → Campo livre 6
  • filtro/livre7 → Campo livre 7
  • filtro/livre8 → Campo livre 8
  • filtro/engajado → Contatos que engajaram nos últimos X dias (número)
    Para o sistema @MediaPost um contato é engajado quando fica com uma mensagem aberta ao menos 10 segundos ou clica em algum link dela

Agendar envio

Este recurso agenda o envio de uma mensagem para uma data e hora definidas

Você pode definir filtros e enviar sua mensagem para um público específico de suas listas de contatos

  • URL:
https://api.mediapost.com.br/envio/cod/[_cod_mensagem_]
  • Método:
PUT
  • Exemplo de requisição (PHP):
$arrEnvio['lista'][] = 749;
$cod_mensagem = 398;
$arrEnvio['datahora_envio'] = "2018-01-01 10:00:00";

$arrEnvio['filtro']['dominio'][] = "gmail.com, hotmail.com";
$arrEnvio['filtro']['sexo'][] = "M";
$arrEnvio['filtro']['mes_aniversario'][] = "3";

try { 
	$arrResult = $mapi->put("envio/cod/".$cod_mensagem, $arrEnvio);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [cod_agenda] => 401858
)

Parâmetros obrigatórios

  • lista → IDs das listas para quais a mensagem será enviada
  • cod_mensagem → ID da mensagem que será enviada
  • datahora_envio → Data e hora em que o envio deve ser realizado

Parâmetros opcionais

  • id_usuario → ID do usuário que será responsável pelo envio. Os créditos consumidos no envio serão debitados do saldo deste usuário, caso tenha.
  • filtro/dominio → Domínios que devem participar do envio
  • filtro/dominio_not → Domínios que não devem participar do envio
  • filtro/dia_aniversario → Dia de aniversário (DD) Ex.: 01, 02, 03 ... 31
  • filtro/mes_aniversario → Mês de aniversário (MM) Ex.: 01, 02, 03 ... 12
  • filtro/dia_mes_aniversario → Dia e Mês de aniversário (DD/MM) Ex.: 01/01, 05/04, 15/12
  • filtro/ano_nascimento → Ano de nascimento (AAAA) Ex.: 1995, 2000, 2005
  • filtro/data_nascimento → Data de nascimento (DD/MM/AAAA) Ex.: 18/01/2017
  • filtro/sexo → Sexo (F ou M)
  • filtro/bairro → Bairro
  • filtro/cidade → Cidade
  • filtro/estado → Estado
  • filtro/ramo_atividade → Ramo de atividade
  • filtro/empresa → Empresa
  • filtro/cargo → Cargo
  • filtro/livre1 → Campo livre 1
  • filtro/livre2 → Campo livre 2
  • filtro/livre3 → Campo livre 3
  • filtro/livre4 → Campo livre 4
  • filtro/livre5 → Campo livre 5
  • filtro/livre6 → Campo livre 6
  • filtro/livre7 → Campo livre 7
  • filtro/livre8 → Campo livre 8
  • filtro/engajado → Contatos que engajaram nos últimos X dias (número)
    Para o sistema @MediaPost um contato é engajado quando fica com uma mensagem aberta ao menos 10 segundos ou clica em algum link dela

Cancelar envio

Este recurso cancela o envio de uma mensagem

Ele também pode ser utilizado para cancelar o envio de uma mensagem agendada, porém não será possível reenviar a mesma mensagem após cancelada

  • URL:
https://api.mediapost.com.br/envio/cancelar/cod/[_cod_mensagem_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$cod_mensagem = 7509;

try { 
	$arrResult = $mapi->get("envio/cancelar/cod/".$cod_mensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
O envio da mensagem 7509 foi cancelado!

Parâmetros obrigatórios

  • cod_mensagem → ID da mensagem cujo o envio deve ser cancelado

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Envio de teste

Este recurso realiza um envio de teste de uma mensagem ainda não disparada/agendada

  • URL:
https://api.mediapost.com.br/envio/teste/cod/[_cod_mensagem_]
  • Método:
PUT
  • Exemplo de requisição (PHP):
$cod_mensagem = 7510;

$emails["email"] = array("pedro@dominio.com.br","lucas@dominio.com.br");

try { 
	$arrResult = $mapi->put("envio/teste/cod/".$cod_mensagem, $emails);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [cod_agenda] => 402119
)

Parâmetros obrigatórios

  • cod_mensagem → ID da mensagem
  • email → Endereços de e-mail que devem receber o envio de teste

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Resultados

Abaixo você encontrará todos os recursos disponíveis para buscar os resultados de seus envios:

Resumo do envio

Este recurso retorna o status de um envio e seus números

  • URL:
https://api.mediapost.com.br/resultado/cod/[_cod_mensagem_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$cod_mensagem = 7507;

try { 
	$arrResult = $mapi->get("resultado/cod/".$cod_mensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [estat] => Array
        (
            [id_cons_mensagem] => 694
            [id_mensagem] => 7507
            [qtde_abertura] => 135
            [qtde_abertura_unico] => 84
            [qtde_clique] => 33
            [qtde_clique_unico] => 15
            [qtde_encaminhado] => 0
            [qtde_atualizado] => 0
            [qtde_cancelado] => 1
            [qtde_devolvido] => 72
            [qtde_entregue] => 2045
            [ret_anti_spam] => 24
            [ret_caixa_cheia] => 5
            [ret_dominio_inexistente] => 0
            [ret_tempo_entrega] => 16
            [ret_usuario_inexistente] => 23
            [ret_padrao] => 4
            [tempo_total] => 00:57:40
            [tempo_abertura] => 00:00:25
            [tempo_contato] => 00:00:41
            [datahora] => 2016-01-27 01:54:23
            [qtde_agendado] => 2159
            [qtde_enviado] => 2117
            [qtde_bloqueado] => 42
            [qtde_credito] => 0
            [qtde_banda] => 72860920
            [qtde_abertura_qualificada] => 73
            [qtde_spam] => 0
            [qtde_sem_interacao] => 2045
        )

    [envio] => Array
        (
            [qtde_agendado] => 2159
            [qtde_enviado] => 2117
            [qtde_banda] => 72860920
            [qtde_bloqueado] => 42
            [qtde_selecionado] => 2159
            [qtde_cancelado] => 42
            [qtde_sem_interacao] => 2045
            [qtde_entregue] => 2045
        )

)

Parâmetros obrigatórios

  • cod_mensagem → ID da mensagem

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Aberturas

Este recurso retorna a lista de contatos que abriram a mensagem

  • URL:
https://api.mediapost.com.br/resultado/abertura/cod/[_cod_mensagem_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$cod_mensagem = 7507;

try { 
	$arrResult = $mapi->get("resultado/abertura/cod/".$cod_mensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [estat] => Array
        (
            [qtde_abertura] => 2406
            [qtde_abertura_unico] => 1321
        )

    [abertura] => Array
        (
            [0] => Array
                (
                    [cod] => 244597
                    [email] => pedro@dominio.com.br
                    [datahora] => 2016-04-19 06:49:47
                    [ip] => 192.168.4.1
                    [tempo] => 12
                )

            [1] => Array
                (
                    [cod] => 79762
                    [email] => lucas@dominio.com.br
                    [datahora] => 2016-04-19 06:50:58
                    [ip] => 192.168.4.2
                    [tempo] => 21
                )
	)
)

Parâmetros obrigatórios

  • cod_mensagem → ID da mensagem

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Cliques

Este recurso retorna a lista de contatos que clicaram em algum link da mensagem

  • URL:
https://api.mediapost.com.br/resultado/clique/cod/[_cod_mensagem_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$cod_mensagem = 7507;

try { 
	$arrResult = $mapi->get("resultado/clique/cod/".$cod_mensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [estat] => Array
        (
            [qtde_clique] => 218
            [qtde_clique_unico] => 192
        )

    [clique] => Array
        (
            [0] => Array
                (
                    [cod] => 309779
                    [email] => pedro@dominio.com.br
                    [datahora] => 2016-04-19 06:51:39
                    [ip] => 192.168.4.1
                    [url] => https://www.mediapost.com.br/planos
                )

            [1] => Array
                (
                    [cod] => 83168
                    [email] => lucas@dominio.com.br
                    [datahora] => 2016-04-19 06:56:14
                    [ip] => 192.168.4.2
                    [url] => https://www.mediapost.com.br/login
                )
	)
)

Parâmetros obrigatórios

  • cod_mensagem → ID da mensagem

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Devoluções

Este recurso retorna a relação de todos os e-mails que foram devolvidos pelo servidor de destino separados por motivo

  • URL:
https://api.mediapost.com.br/resultado/devolvido/cod/[_cod_mensagem_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$cod_mensagem = 7507;

try { 
	$arrResult = $mapi->get("resultado/devolvido/cod/".$cod_mensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [estat] => Array
        (
            [qtde_devolvido] => 247
            [ret_anti_spam] => 30
            [ret_caixa_cheia] => 15
            [ret_dominio_inexistente] => 10
            [ret_tempo_entrega] => 29
            [ret_usuario_inexistente] => 118
            [ret_padrao] => 45
        )

    [ret_padrao] => Array
        (
            [0] => Array
                (
                    [cod] => 81046
                    [email] => pedro@dominio.com.br
                    [datahora] => 2016-04-19 06:48:57
                    [tipo] => padrao
                )

        )

    [ret_anti_spam] => Array
        (
            [0] => Array
                (
                    [cod] => 81085
                    [email] => lucas@dominio.com.br
                    [datahora] => 2016-04-19 06:48:57
                    [tipo] => anti_spam
                )

        )

    [ret_usuario_inexistente] => Array
        (
            [0] => Array
                (
                    [cod] => 81161
                    [email] => paulo@dominio.com.br
                    [datahora] => 2016-04-19 06:48:57
                    [tipo] => usuario_inexistente
                )

        )

    [ret_tempo_entrega] => Array
        (
            [0] => Array
                (
                    [cod] => 79780
                    [email] => miguel@dominio.com.br
                    [datahora] => 2016-04-19 06:48:57
                    [tipo] => tempo_entrega
                )

        )

    [ret_caixa_cheia] => Array
        (
            [0] => Array
                (
                    [cod] => 76673
                    [email] => marcos@dominio.com.br
                    [datahora] => 2016-04-19 06:48:57
                    [tipo] => caixa_cheia
                )

        )

    [ret_dominio_inexistente] => Array
        (
            [0] => Array
                (
                    [cod] => 80776
                    [email] => daniel@dominio.com.br
                    [datahora] => 2016-04-19 06:51:58
                    [tipo] => dominio_inexistente
                )

        )

)

Parâmetros obrigatórios

  • cod_mensagem → ID da mensagem

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Atualizações

Este recurso retorna a lista de contatos que atualizaram o cadastro

  • URL:
https://api.mediapost.com.br/resultado/atualizado/cod/[_cod_mensagem_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$cod_mensagem = 7507;

try { 
	$arrResult = $mapi->get("resultado/atualizado/cod/".$cod_mensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [estat] => Array
        (
            [qtde_atualizado] => 3
        )

    [atualizado] => Array
        (
            [0] => Array
                (
                    [cod] => 78662
                    [email] => pedro@dominio.com.br
                    [datahora] => 2016-04-13 12:16:18
                    [ip] => 192.168.4.1
                )

        )

)

Parâmetros obrigatórios

  • cod_mensagem → ID da mensagem

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Cancelamentos

Este recurso retorna a lista de contatos que cancelaram o cadastro (Opt Out)

  • URL:
https://api.mediapost.com.br/resultado/cancelado/cod/[_cod_mensagem_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$cod_mensagem = 7507;

try { 
	$arrResult = $mapi->get("resultado/cancelado/cod/".$cod_mensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [estat] => Array
        (
            [qtde_cancelado] => 8
        )

    [cancelamento] => Array
        (
            [0] => Array
                (
                    [cod] => 467711
                    [email] => pedro@dominio.com.br
                    [datahora] => 2016-04-15 07:49:08
                    [ip] => 192.168.4.1
                )

            [1] => Array
                (
                    [cod] => 467492
                    [email] => lucas@dominio.com.br
                    [datahora] => 2016-04-15 08:18:16
                    [ip] => 192.168.4.2
				)
	)
)

Parâmetros obrigatórios

  • cod_mensagem → ID da mensagem

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Encaminhamentos

Este recurso retorna a lista de contatos que encaminharam a mensagem e para quem ela foi encaminhada

  • URL:
https://api.mediapost.com.br/resultado/encaminhado/cod/[_cod_mensagem_]
  • Método:
GET
  • Exemplo de requisição (PHP):
$cod_mensagem = 7507;

try { 
	$arrResult = $mapi->get("resultado/encaminhado/cod/".$cod_mensagem);
	echo "<pre>".print_r($arrResult, true)."</pre>";die;
} catch (MapiException $e){
	throw $e; 
}
  • Exemplo de resposta:
Array
(
    [estat] => Array
        (
            [qtde_encaminhado] => 1
        )

    [encaminhado] => Array
        (
            [0] => Array
                (
                    [cod] => 221562
                    [email] => pedro@dominio.com.br
                    [datahora] => 2016-03-02 17:38:56
                    [ip] => 192.168.4.1
                    [cod_origem] => 221562
                    [email_origem] => lucas@dominio.com.br
                )

        )

)

Parâmetros obrigatórios

  • cod_mensagem → ID da mensagem

Parâmetros opcionais

  • Este recurso não possui parâmetros opcionais

Códigos de erro

Abaixo você encontrará uma lista com todos os códigos e descrições dos erros que a API pode retornar:

Código Mensagem
1 URL não encontrada
2 Cliente não reconhecido
3 Resposta inválida
100 Erro desconhecido
125 Conta não encontrada
126 Dados fora do padrão JSON
127 Contato não encontrado
231 Lista não informada
232 Lista informada não existe
233 Nenhuma lista não foi encontrada
234 Informe um nome para a lista
235 Erro ao criar a lista
341 Não foi possível encontrar a pasta informada
342 Você deve informar uma pasta
343 O remetente não pode ser usado
344 Não foi possível gravar o remetente
345 Mensagem sem assunto
346 Mensagem sem um texto em formato HTML
347 Não foi possível salvar a mensagem
451 Informe ao menos uma lista para envio
452 A mensagem foi excluída e não pode ser enviada.
453 A mensagem já foi enviada anteriormente
454 A mensagem não possui um remetente configurado
455 Com essa configuração de envio nenhum e-mail será enviado
456 Você não possui créditos suficientes para realizar esse envio
457 Erro ao agendar a mensagem
458 Informe o código da mensagem que deseja enviar
459 Erro ao cancelar o envio
480 Usuário ou senha inválidos

Arquivos de exemplo (PHP)

Baixe o client e exemplos de uso de cada recurso da API em PHP

Baixar exemplos

Atualizações da API

Datas e observações das atualizações da API ou documentação:

Data Tipo Descrição
10/06/2016 Atualização Inclusão do parâmetro id_usuário nos recursos de envio
01/06/2016 Inclusão Agora é possível consultar o saldo de um usuário com o recurso Saldo do usuário

Em caso de dúvidas, erros ou informações adicionais, envie um e-mail para suporte@mediapost.com.br