meeng-sdk 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- meeng_sdk-0.1.0/.gitignore +4 -0
- meeng_sdk-0.1.0/PKG-INFO +204 -0
- meeng_sdk-0.1.0/README.md +192 -0
- meeng_sdk-0.1.0/examples/add_domain.py +22 -0
- meeng_sdk-0.1.0/examples/schedule_email.py +37 -0
- meeng_sdk-0.1.0/examples/send_batch.py +28 -0
- meeng_sdk-0.1.0/examples/send_email.py +29 -0
- meeng_sdk-0.1.0/examples/verify_webhook.py +40 -0
- meeng_sdk-0.1.0/pyproject.toml +23 -0
- meeng_sdk-0.1.0/src/meeng/__init__.py +88 -0
- meeng_sdk-0.1.0/src/meeng/_client.py +225 -0
- meeng_sdk-0.1.0/src/meeng/_core.py +32 -0
- meeng_sdk-0.1.0/src/meeng/_errors.py +78 -0
- meeng_sdk-0.1.0/src/meeng/_services.py +246 -0
- meeng_sdk-0.1.0/src/meeng/_version.py +13 -0
- meeng_sdk-0.1.0/src/meeng/models.py +613 -0
- meeng_sdk-0.1.0/src/meeng/py.typed +0 -0
- meeng_sdk-0.1.0/src/meeng/webhooks.py +250 -0
- meeng_sdk-0.1.0/tests/test_contract.py +128 -0
- meeng_sdk-0.1.0/tests/test_meeng.py +299 -0
meeng_sdk-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: meeng-sdk
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Meeng.dev's SDK for Python: emails, domains, contacts, contact books, campaigns, analytics and webhooks.
|
|
5
|
+
Project-URL: Homepage, https://meeng.dev
|
|
6
|
+
Project-URL: Repository, https://github.com/meeng-dev/sdk
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: Typing :: Typed
|
|
10
|
+
Requires-Python: >=3.11
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
|
|
13
|
+
# meeng-sdk (Python)
|
|
14
|
+
|
|
15
|
+
SDK do Meeng.dev para Python 3.11 ou mais novo: e-mails, domínios, contatos, listas de contatos, campanhas, analytics e webhooks. Sem dependências além da biblioteca padrão.
|
|
16
|
+
|
|
17
|
+
Gerado pelo `sdk/generator` a partir do contrato da API do Meeng.dev (versão 1.0.0); não edite à mão.
|
|
18
|
+
|
|
19
|
+
## Começando
|
|
20
|
+
|
|
21
|
+
```python
|
|
22
|
+
from meeng import Meeng
|
|
23
|
+
|
|
24
|
+
meeng = Meeng("mg_123")
|
|
25
|
+
|
|
26
|
+
data, _ = meeng.emails.send({
|
|
27
|
+
"from": "contato@acme.com.br",
|
|
28
|
+
"to": "ana@example.com",
|
|
29
|
+
"subject": "Olá",
|
|
30
|
+
"html": "<p>Olá!</p>",
|
|
31
|
+
})
|
|
32
|
+
print(data["emailId"])
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Toda chamada devolve `(data, error)`. Por padrão uma recusa da API levanta `MeengHTTPError` (com `status_code` e `error`, que é `{"code", "message"}`) e `error` volta sempre `None`; com `Meeng("mg_123", raise_on_error=False)` a chamada devolve `(None, error)`.
|
|
36
|
+
|
|
37
|
+
Os corpos e as respostas são dicionários com as chaves da API, em camelCase (`contactBookId`, `scheduledAt`). Os tipos estão em `meeng.types` (`meeng.types.EmailsSendParams`, `meeng.types.Domain`…) e funcionam com o `mypy --strict`.
|
|
38
|
+
|
|
39
|
+
Sem argumentos, `Meeng()` lê a chave de `MEENG_API_KEY` e o endereço do app de `MEENG_BASE_URL`. O segundo argumento é o endereço do app (para instalações próprias), sem `/api/v1`; ele precisa ser https, e http só vale para `localhost`, `127.0.0.0/8` e `::1`, para a chave nunca viajar em texto puro. O transporte padrão usa `urllib` e não segue redirecionamentos.
|
|
40
|
+
|
|
41
|
+
## Recursos
|
|
42
|
+
|
|
43
|
+
### `meeng.emails`
|
|
44
|
+
|
|
45
|
+
- `send`: envia um e-mail, agora ou em `scheduledAt`.
|
|
46
|
+
- `batch`: envia até 100 e-mails numa requisição.
|
|
47
|
+
- `get`: lê um e-mail com os seus eventos.
|
|
48
|
+
- `list`: lista e-mails, do mais novo ao mais velho, com período e domínio opcionais.
|
|
49
|
+
- `update`: reagenda um e-mail que ainda não saiu.
|
|
50
|
+
- `cancel`: cancela um e-mail agendado.
|
|
51
|
+
|
|
52
|
+
### `meeng.domains`
|
|
53
|
+
|
|
54
|
+
- `list`: lista os domínios de envio do time.
|
|
55
|
+
- `create`: adiciona um domínio de envio e devolve os registros DNS a publicar.
|
|
56
|
+
- `verify`: pede para conferir de novo os registros DNS do domínio.
|
|
57
|
+
- `get`: lê um domínio com os seus registros DNS.
|
|
58
|
+
- `delete`: remove um domínio.
|
|
59
|
+
|
|
60
|
+
### `meeng.contacts`
|
|
61
|
+
|
|
62
|
+
- `create`: adiciona um contato a uma lista de contatos.
|
|
63
|
+
- `list`: lista os contatos de uma lista, com filtro opcional por e-mail ou id.
|
|
64
|
+
- `get`: lê um contato.
|
|
65
|
+
- `update`: muda só os campos enviados de um contato.
|
|
66
|
+
- `upsert`: cria o contato, ou o substitui quando ele já existe.
|
|
67
|
+
- `delete`: remove um contato.
|
|
68
|
+
- `bulk_create`: adiciona vários contatos a uma lista numa requisição.
|
|
69
|
+
- `bulk_delete`: remove vários contatos de uma lista numa requisição.
|
|
70
|
+
|
|
71
|
+
### `meeng.contact_books`
|
|
72
|
+
|
|
73
|
+
- `list`: lista as listas de contatos do time.
|
|
74
|
+
- `create`: cria uma lista de contatos.
|
|
75
|
+
- `get`: lê uma lista de contatos.
|
|
76
|
+
- `update`: muda só os campos enviados de uma lista de contatos.
|
|
77
|
+
- `delete`: remove uma lista de contatos e os seus contatos.
|
|
78
|
+
|
|
79
|
+
### `meeng.campaigns`
|
|
80
|
+
|
|
81
|
+
- `create`: cria uma campanha, e a envia agora quando `sendNow` é verdadeiro.
|
|
82
|
+
- `list`: lista campanhas, com filtro opcional por status ou texto.
|
|
83
|
+
- `get`: lê uma campanha com os seus contadores.
|
|
84
|
+
- `delete`: remove uma campanha.
|
|
85
|
+
- `schedule`: agenda uma campanha, ou a envia agora quando não há horário.
|
|
86
|
+
- `pause`: pausa uma campanha em andamento ou agendada.
|
|
87
|
+
- `resume`: retoma uma campanha pausada.
|
|
88
|
+
|
|
89
|
+
### `meeng.analytics`
|
|
90
|
+
|
|
91
|
+
- `email_time_series`: conta e-mails por dia nos últimos 7 ou 30 dias.
|
|
92
|
+
- `reputation_metrics`: lê as taxas de rejeição e de reclamação da reputação de envio.
|
|
93
|
+
|
|
94
|
+
`emails.create` é outro nome de `emails.send`, `campaigns.get_all` de `campaigns.list`, e `meeng.contactBooks` de `meeng.contact_books`.
|
|
95
|
+
|
|
96
|
+
Os filtros de listagem são argumentos nomeados em snake_case (`start_date`, `domain_id`); uma lista em `domain_id` vira um `domainId` por valor. `emails.send` e `emails.batch` aceitam `options={"idempotency_key": "pedido-1"}`: a mesma chave com o mesmo corpo devolve o primeiro resultado.
|
|
97
|
+
|
|
98
|
+
## Arquivos: use links, não anexos
|
|
99
|
+
|
|
100
|
+
O Meeng.dev não anexa, não guarda e não repassa arquivos, e por isso nenhum SDK tem o campo `attachments`. Hospede o arquivo onde preferir (seu armazenamento, um link assinado com prazo) e ponha o link no corpo do e-mail:
|
|
101
|
+
|
|
102
|
+
```html
|
|
103
|
+
<p>Sua fatura está pronta: <a href="https://exemplo.com.br/faturas/1042?token=...">baixar a fatura (PDF)</a></p>
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Se um pedido chegar à API com `attachments` e itens, ela responde `400` (`ZodError`) com a mensagem `Attachments are not supported. Include links to your files in the email body.`; uma lista vazia passa. Para um documento sensível, use um link que expira.
|
|
107
|
+
|
|
108
|
+
## Configuração
|
|
109
|
+
|
|
110
|
+
A API do Meeng.dev fica em `https://meeng.dev/api`. O cliente recebe o endereço do app, `https://meeng.dev` (o padrão), e acrescenta `/api/v1` a cada chamada. Crie uma chave em [Configurações > Chaves](https://meeng.dev/configuracoes/chaves); ela tem a forma `mg_<id>_<segredo>`.
|
|
111
|
+
|
|
112
|
+
- A chave vem do argumento ou de `MEENG_API_KEY`; o endereço, do argumento ou de `MEENG_BASE_URL`.
|
|
113
|
+
- Só `https` é aceito. `http` vale para `localhost`, `127.0.0.0/8` e `::1` (um servidor local), para a chave nunca viajar em texto puro. Nenhum cliente segue redirecionamento.
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
meeng = Meeng("mg_...", "https://meeng.dev", timeout=10, max_retries=3, retry_delay=1.0)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Exemplos
|
|
120
|
+
|
|
121
|
+
A pasta [`examples/`](examples) tem programas que rodam: enviar um e-mail, enviar em lote, agendar (remarcar e cancelar), adicionar um domínio (com os registros DNS) e verificar um webhook.
|
|
122
|
+
|
|
123
|
+
| Exemplo | Arquivo | Rode com |
|
|
124
|
+
|---|---|---|
|
|
125
|
+
| Enviar um e-mail | `examples/send_email.py` | `PYTHONPATH=src python3 examples/send_email.py` |
|
|
126
|
+
| Enviar em lote | `examples/send_batch.py` | `PYTHONPATH=src python3 examples/send_batch.py` |
|
|
127
|
+
| Agendar, remarcar e cancelar | `examples/schedule_email.py` | `PYTHONPATH=src python3 examples/schedule_email.py` |
|
|
128
|
+
| Adicionar um domínio | `examples/add_domain.py` | `PYTHONPATH=src python3 examples/add_domain.py` |
|
|
129
|
+
| Verificar um webhook | `examples/verify_webhook.py` | `PYTHONPATH=src python3 examples/verify_webhook.py` |
|
|
130
|
+
|
|
131
|
+
Todos leem `MEENG_API_KEY` e, se quiser apontar para outro app, `MEENG_BASE_URL`; o de webhook roda sem chave, com uma requisição montada no próprio programa.
|
|
132
|
+
|
|
133
|
+
## Paginação
|
|
134
|
+
|
|
135
|
+
As listagens de e-mails, contatos e campanhas são paginadas por `page` (a partir de 1) e, nas duas primeiras, `limit`. `emails.list` devolve `count`, o total de e-mails; `campaigns.list` devolve `totalPage`, o total de páginas; `contacts.list` devolve a lista sem total, e a última página é a que vem com menos de `limit` contatos.
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
todos, page = [], 1
|
|
139
|
+
while True:
|
|
140
|
+
lista, _ = meeng.emails.list(page=page, limit=100)
|
|
141
|
+
todos += lista["data"]
|
|
142
|
+
if len(todos) >= lista["count"] or not lista["data"]:
|
|
143
|
+
break
|
|
144
|
+
page += 1
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Erros
|
|
148
|
+
|
|
149
|
+
Por padrão uma recusa da API levanta `MeengHTTPError`, com `status_code` e `error` (`{"code", "message"}`):
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
from meeng import MeengHTTPError
|
|
153
|
+
|
|
154
|
+
try:
|
|
155
|
+
meeng.emails.get("em_123")
|
|
156
|
+
except MeengHTTPError as erro:
|
|
157
|
+
if erro.error["code"] == "NOT_FOUND":
|
|
158
|
+
... # o e-mail não existe, ou é de outro time
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Com `Meeng(..., raise_on_error=False)` a chamada devolve `(None, error)` em vez de levantar.
|
|
162
|
+
|
|
163
|
+
Os códigos que a API devolve: `UNAUTHORIZED` (sem chave), `FORBIDDEN` (chave inválida ou sem permissão), `NOT_FOUND`, `NOT_UNIQUE` (a mesma chave de idempotência com outro corpo, ou ainda em andamento), `RATE_LIMITED`, `BAD_REQUEST`, `METHOD_NOT_ALLOWED`, `NOT_IMPLEMENTED` e `INTERNAL_SERVER_ERROR`. Uma validação recusada vira o código `ZodError`, e a mensagem é a primeira falha (`from: Required`).
|
|
164
|
+
|
|
165
|
+
## Tentativas automáticas
|
|
166
|
+
|
|
167
|
+
O cliente repete sozinho a chamada que pode ser repetida, até `max_retries` vezes depois da primeira tentativa (2 por padrão; 0 envia cada chamada uma vez só):
|
|
168
|
+
|
|
169
|
+
| Resposta | Repete? |
|
|
170
|
+
|---|---|
|
|
171
|
+
| 429 (limite de requisições por segundo) | Sempre: a chamada não foi processada, então qualquer uma pode ser repetida. |
|
|
172
|
+
| 500, 502, 503, 504 ou falha de conexão | Só quando repetir não faz o trabalho duas vezes: uma leitura (`GET`), um `PUT`, um `DELETE`, ou uma chamada com chave de idempotência. Um envio sem chave não é repetido. |
|
|
173
|
+
| 409 e qualquer outra recusa | Nunca. |
|
|
174
|
+
|
|
175
|
+
A primeira repetição espera `retry_delay` (500 ms por padrão), cada uma seguinte espera o dobro, até 30 segundos, e o `Retry-After` que a API devolve vale no lugar dessa espera. Esgotadas as tentativas, a última resposta é o erro.
|
|
176
|
+
|
|
177
|
+
## Webhooks
|
|
178
|
+
|
|
179
|
+
```python
|
|
180
|
+
webhooks = meeng.webhooks("whsec_xxx")
|
|
181
|
+
|
|
182
|
+
# Flask: request.data; Django: request.body; FastAPI: await request.body().
|
|
183
|
+
event = webhooks.construct_event(request.data, headers=request.headers)
|
|
184
|
+
|
|
185
|
+
if event["type"] == "email.delivered":
|
|
186
|
+
print(event["data"]["to"])
|
|
187
|
+
elif event["type"] == "email.bounced":
|
|
188
|
+
print(event["data"]["bounce"]["type"])
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
`verify(body, headers=...)` só confere a assinatura e devolve `True` ou `False`. `construct_event` confere e devolve o evento, ou levanta `WebhookVerificationError` com um `code`: `MISSING_SIGNATURE`, `MISSING_TIMESTAMP`, `INVALID_SIGNATURE_FORMAT`, `INVALID_TIMESTAMP`, `TIMESTAMP_OUT_OF_RANGE`, `SIGNATURE_MISMATCH`, `INVALID_BODY` ou `INVALID_JSON`.
|
|
192
|
+
|
|
193
|
+
A assinatura é `v1=` mais o HMAC-SHA256, em hexadecimal, de `{timestamp}.{corpo}` com o segredo do webhook; o timestamp vem em milissegundos. A tolerância padrão é de 5 minutos (`tolerance`, em milissegundos; `-1` desliga a checagem; `secret` troca o segredo de uma checagem). Os cabeçalhos são `X-Meeng-Signature`, `X-Meeng-Timestamp`, `X-Meeng-Event` e `X-Meeng-Call`.
|
|
194
|
+
|
|
195
|
+
Eventos: `contact.created`, `contact.updated`, `contact.deleted`, `domain.created`, `domain.verified`, `domain.updated`, `domain.deleted`, `email.queued`, `email.sent`, `email.delivery_delayed`, `email.delivered`, `email.rejected`, `email.rendering_failure`, `email.complained`, `email.cancelled`, `email.bounced`, `email.clicked`, `email.failed`, `email.opened`, `email.suppressed`, `webhook.test`.
|
|
196
|
+
|
|
197
|
+
## Desenvolvimento
|
|
198
|
+
|
|
199
|
+
```sh
|
|
200
|
+
PYTHONPATH=src python3 -m unittest discover -s tests
|
|
201
|
+
mypy --strict --python-version 3.11 src/meeng examples
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
O `./check.sh` da raiz do repositório sobe uma API de mentira gerada do contrato (`go run ./cmd/fakeapi`), que recusa o que o contrato não permite, e roda contra ela o teste de contrato (cada método do SDK é chamado, e nenhuma operação pode ficar de fora) e os exemplos.
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
# meeng-sdk (Python)
|
|
2
|
+
|
|
3
|
+
SDK do Meeng.dev para Python 3.11 ou mais novo: e-mails, domínios, contatos, listas de contatos, campanhas, analytics e webhooks. Sem dependências além da biblioteca padrão.
|
|
4
|
+
|
|
5
|
+
Gerado pelo `sdk/generator` a partir do contrato da API do Meeng.dev (versão 1.0.0); não edite à mão.
|
|
6
|
+
|
|
7
|
+
## Começando
|
|
8
|
+
|
|
9
|
+
```python
|
|
10
|
+
from meeng import Meeng
|
|
11
|
+
|
|
12
|
+
meeng = Meeng("mg_123")
|
|
13
|
+
|
|
14
|
+
data, _ = meeng.emails.send({
|
|
15
|
+
"from": "contato@acme.com.br",
|
|
16
|
+
"to": "ana@example.com",
|
|
17
|
+
"subject": "Olá",
|
|
18
|
+
"html": "<p>Olá!</p>",
|
|
19
|
+
})
|
|
20
|
+
print(data["emailId"])
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Toda chamada devolve `(data, error)`. Por padrão uma recusa da API levanta `MeengHTTPError` (com `status_code` e `error`, que é `{"code", "message"}`) e `error` volta sempre `None`; com `Meeng("mg_123", raise_on_error=False)` a chamada devolve `(None, error)`.
|
|
24
|
+
|
|
25
|
+
Os corpos e as respostas são dicionários com as chaves da API, em camelCase (`contactBookId`, `scheduledAt`). Os tipos estão em `meeng.types` (`meeng.types.EmailsSendParams`, `meeng.types.Domain`…) e funcionam com o `mypy --strict`.
|
|
26
|
+
|
|
27
|
+
Sem argumentos, `Meeng()` lê a chave de `MEENG_API_KEY` e o endereço do app de `MEENG_BASE_URL`. O segundo argumento é o endereço do app (para instalações próprias), sem `/api/v1`; ele precisa ser https, e http só vale para `localhost`, `127.0.0.0/8` e `::1`, para a chave nunca viajar em texto puro. O transporte padrão usa `urllib` e não segue redirecionamentos.
|
|
28
|
+
|
|
29
|
+
## Recursos
|
|
30
|
+
|
|
31
|
+
### `meeng.emails`
|
|
32
|
+
|
|
33
|
+
- `send`: envia um e-mail, agora ou em `scheduledAt`.
|
|
34
|
+
- `batch`: envia até 100 e-mails numa requisição.
|
|
35
|
+
- `get`: lê um e-mail com os seus eventos.
|
|
36
|
+
- `list`: lista e-mails, do mais novo ao mais velho, com período e domínio opcionais.
|
|
37
|
+
- `update`: reagenda um e-mail que ainda não saiu.
|
|
38
|
+
- `cancel`: cancela um e-mail agendado.
|
|
39
|
+
|
|
40
|
+
### `meeng.domains`
|
|
41
|
+
|
|
42
|
+
- `list`: lista os domínios de envio do time.
|
|
43
|
+
- `create`: adiciona um domínio de envio e devolve os registros DNS a publicar.
|
|
44
|
+
- `verify`: pede para conferir de novo os registros DNS do domínio.
|
|
45
|
+
- `get`: lê um domínio com os seus registros DNS.
|
|
46
|
+
- `delete`: remove um domínio.
|
|
47
|
+
|
|
48
|
+
### `meeng.contacts`
|
|
49
|
+
|
|
50
|
+
- `create`: adiciona um contato a uma lista de contatos.
|
|
51
|
+
- `list`: lista os contatos de uma lista, com filtro opcional por e-mail ou id.
|
|
52
|
+
- `get`: lê um contato.
|
|
53
|
+
- `update`: muda só os campos enviados de um contato.
|
|
54
|
+
- `upsert`: cria o contato, ou o substitui quando ele já existe.
|
|
55
|
+
- `delete`: remove um contato.
|
|
56
|
+
- `bulk_create`: adiciona vários contatos a uma lista numa requisição.
|
|
57
|
+
- `bulk_delete`: remove vários contatos de uma lista numa requisição.
|
|
58
|
+
|
|
59
|
+
### `meeng.contact_books`
|
|
60
|
+
|
|
61
|
+
- `list`: lista as listas de contatos do time.
|
|
62
|
+
- `create`: cria uma lista de contatos.
|
|
63
|
+
- `get`: lê uma lista de contatos.
|
|
64
|
+
- `update`: muda só os campos enviados de uma lista de contatos.
|
|
65
|
+
- `delete`: remove uma lista de contatos e os seus contatos.
|
|
66
|
+
|
|
67
|
+
### `meeng.campaigns`
|
|
68
|
+
|
|
69
|
+
- `create`: cria uma campanha, e a envia agora quando `sendNow` é verdadeiro.
|
|
70
|
+
- `list`: lista campanhas, com filtro opcional por status ou texto.
|
|
71
|
+
- `get`: lê uma campanha com os seus contadores.
|
|
72
|
+
- `delete`: remove uma campanha.
|
|
73
|
+
- `schedule`: agenda uma campanha, ou a envia agora quando não há horário.
|
|
74
|
+
- `pause`: pausa uma campanha em andamento ou agendada.
|
|
75
|
+
- `resume`: retoma uma campanha pausada.
|
|
76
|
+
|
|
77
|
+
### `meeng.analytics`
|
|
78
|
+
|
|
79
|
+
- `email_time_series`: conta e-mails por dia nos últimos 7 ou 30 dias.
|
|
80
|
+
- `reputation_metrics`: lê as taxas de rejeição e de reclamação da reputação de envio.
|
|
81
|
+
|
|
82
|
+
`emails.create` é outro nome de `emails.send`, `campaigns.get_all` de `campaigns.list`, e `meeng.contactBooks` de `meeng.contact_books`.
|
|
83
|
+
|
|
84
|
+
Os filtros de listagem são argumentos nomeados em snake_case (`start_date`, `domain_id`); uma lista em `domain_id` vira um `domainId` por valor. `emails.send` e `emails.batch` aceitam `options={"idempotency_key": "pedido-1"}`: a mesma chave com o mesmo corpo devolve o primeiro resultado.
|
|
85
|
+
|
|
86
|
+
## Arquivos: use links, não anexos
|
|
87
|
+
|
|
88
|
+
O Meeng.dev não anexa, não guarda e não repassa arquivos, e por isso nenhum SDK tem o campo `attachments`. Hospede o arquivo onde preferir (seu armazenamento, um link assinado com prazo) e ponha o link no corpo do e-mail:
|
|
89
|
+
|
|
90
|
+
```html
|
|
91
|
+
<p>Sua fatura está pronta: <a href="https://exemplo.com.br/faturas/1042?token=...">baixar a fatura (PDF)</a></p>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Se um pedido chegar à API com `attachments` e itens, ela responde `400` (`ZodError`) com a mensagem `Attachments are not supported. Include links to your files in the email body.`; uma lista vazia passa. Para um documento sensível, use um link que expira.
|
|
95
|
+
|
|
96
|
+
## Configuração
|
|
97
|
+
|
|
98
|
+
A API do Meeng.dev fica em `https://meeng.dev/api`. O cliente recebe o endereço do app, `https://meeng.dev` (o padrão), e acrescenta `/api/v1` a cada chamada. Crie uma chave em [Configurações > Chaves](https://meeng.dev/configuracoes/chaves); ela tem a forma `mg_<id>_<segredo>`.
|
|
99
|
+
|
|
100
|
+
- A chave vem do argumento ou de `MEENG_API_KEY`; o endereço, do argumento ou de `MEENG_BASE_URL`.
|
|
101
|
+
- Só `https` é aceito. `http` vale para `localhost`, `127.0.0.0/8` e `::1` (um servidor local), para a chave nunca viajar em texto puro. Nenhum cliente segue redirecionamento.
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
meeng = Meeng("mg_...", "https://meeng.dev", timeout=10, max_retries=3, retry_delay=1.0)
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Exemplos
|
|
108
|
+
|
|
109
|
+
A pasta [`examples/`](examples) tem programas que rodam: enviar um e-mail, enviar em lote, agendar (remarcar e cancelar), adicionar um domínio (com os registros DNS) e verificar um webhook.
|
|
110
|
+
|
|
111
|
+
| Exemplo | Arquivo | Rode com |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| Enviar um e-mail | `examples/send_email.py` | `PYTHONPATH=src python3 examples/send_email.py` |
|
|
114
|
+
| Enviar em lote | `examples/send_batch.py` | `PYTHONPATH=src python3 examples/send_batch.py` |
|
|
115
|
+
| Agendar, remarcar e cancelar | `examples/schedule_email.py` | `PYTHONPATH=src python3 examples/schedule_email.py` |
|
|
116
|
+
| Adicionar um domínio | `examples/add_domain.py` | `PYTHONPATH=src python3 examples/add_domain.py` |
|
|
117
|
+
| Verificar um webhook | `examples/verify_webhook.py` | `PYTHONPATH=src python3 examples/verify_webhook.py` |
|
|
118
|
+
|
|
119
|
+
Todos leem `MEENG_API_KEY` e, se quiser apontar para outro app, `MEENG_BASE_URL`; o de webhook roda sem chave, com uma requisição montada no próprio programa.
|
|
120
|
+
|
|
121
|
+
## Paginação
|
|
122
|
+
|
|
123
|
+
As listagens de e-mails, contatos e campanhas são paginadas por `page` (a partir de 1) e, nas duas primeiras, `limit`. `emails.list` devolve `count`, o total de e-mails; `campaigns.list` devolve `totalPage`, o total de páginas; `contacts.list` devolve a lista sem total, e a última página é a que vem com menos de `limit` contatos.
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
todos, page = [], 1
|
|
127
|
+
while True:
|
|
128
|
+
lista, _ = meeng.emails.list(page=page, limit=100)
|
|
129
|
+
todos += lista["data"]
|
|
130
|
+
if len(todos) >= lista["count"] or not lista["data"]:
|
|
131
|
+
break
|
|
132
|
+
page += 1
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Erros
|
|
136
|
+
|
|
137
|
+
Por padrão uma recusa da API levanta `MeengHTTPError`, com `status_code` e `error` (`{"code", "message"}`):
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
from meeng import MeengHTTPError
|
|
141
|
+
|
|
142
|
+
try:
|
|
143
|
+
meeng.emails.get("em_123")
|
|
144
|
+
except MeengHTTPError as erro:
|
|
145
|
+
if erro.error["code"] == "NOT_FOUND":
|
|
146
|
+
... # o e-mail não existe, ou é de outro time
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Com `Meeng(..., raise_on_error=False)` a chamada devolve `(None, error)` em vez de levantar.
|
|
150
|
+
|
|
151
|
+
Os códigos que a API devolve: `UNAUTHORIZED` (sem chave), `FORBIDDEN` (chave inválida ou sem permissão), `NOT_FOUND`, `NOT_UNIQUE` (a mesma chave de idempotência com outro corpo, ou ainda em andamento), `RATE_LIMITED`, `BAD_REQUEST`, `METHOD_NOT_ALLOWED`, `NOT_IMPLEMENTED` e `INTERNAL_SERVER_ERROR`. Uma validação recusada vira o código `ZodError`, e a mensagem é a primeira falha (`from: Required`).
|
|
152
|
+
|
|
153
|
+
## Tentativas automáticas
|
|
154
|
+
|
|
155
|
+
O cliente repete sozinho a chamada que pode ser repetida, até `max_retries` vezes depois da primeira tentativa (2 por padrão; 0 envia cada chamada uma vez só):
|
|
156
|
+
|
|
157
|
+
| Resposta | Repete? |
|
|
158
|
+
|---|---|
|
|
159
|
+
| 429 (limite de requisições por segundo) | Sempre: a chamada não foi processada, então qualquer uma pode ser repetida. |
|
|
160
|
+
| 500, 502, 503, 504 ou falha de conexão | Só quando repetir não faz o trabalho duas vezes: uma leitura (`GET`), um `PUT`, um `DELETE`, ou uma chamada com chave de idempotência. Um envio sem chave não é repetido. |
|
|
161
|
+
| 409 e qualquer outra recusa | Nunca. |
|
|
162
|
+
|
|
163
|
+
A primeira repetição espera `retry_delay` (500 ms por padrão), cada uma seguinte espera o dobro, até 30 segundos, e o `Retry-After` que a API devolve vale no lugar dessa espera. Esgotadas as tentativas, a última resposta é o erro.
|
|
164
|
+
|
|
165
|
+
## Webhooks
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
webhooks = meeng.webhooks("whsec_xxx")
|
|
169
|
+
|
|
170
|
+
# Flask: request.data; Django: request.body; FastAPI: await request.body().
|
|
171
|
+
event = webhooks.construct_event(request.data, headers=request.headers)
|
|
172
|
+
|
|
173
|
+
if event["type"] == "email.delivered":
|
|
174
|
+
print(event["data"]["to"])
|
|
175
|
+
elif event["type"] == "email.bounced":
|
|
176
|
+
print(event["data"]["bounce"]["type"])
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
`verify(body, headers=...)` só confere a assinatura e devolve `True` ou `False`. `construct_event` confere e devolve o evento, ou levanta `WebhookVerificationError` com um `code`: `MISSING_SIGNATURE`, `MISSING_TIMESTAMP`, `INVALID_SIGNATURE_FORMAT`, `INVALID_TIMESTAMP`, `TIMESTAMP_OUT_OF_RANGE`, `SIGNATURE_MISMATCH`, `INVALID_BODY` ou `INVALID_JSON`.
|
|
180
|
+
|
|
181
|
+
A assinatura é `v1=` mais o HMAC-SHA256, em hexadecimal, de `{timestamp}.{corpo}` com o segredo do webhook; o timestamp vem em milissegundos. A tolerância padrão é de 5 minutos (`tolerance`, em milissegundos; `-1` desliga a checagem; `secret` troca o segredo de uma checagem). Os cabeçalhos são `X-Meeng-Signature`, `X-Meeng-Timestamp`, `X-Meeng-Event` e `X-Meeng-Call`.
|
|
182
|
+
|
|
183
|
+
Eventos: `contact.created`, `contact.updated`, `contact.deleted`, `domain.created`, `domain.verified`, `domain.updated`, `domain.deleted`, `email.queued`, `email.sent`, `email.delivery_delayed`, `email.delivered`, `email.rejected`, `email.rendering_failure`, `email.complained`, `email.cancelled`, `email.bounced`, `email.clicked`, `email.failed`, `email.opened`, `email.suppressed`, `webhook.test`.
|
|
184
|
+
|
|
185
|
+
## Desenvolvimento
|
|
186
|
+
|
|
187
|
+
```sh
|
|
188
|
+
PYTHONPATH=src python3 -m unittest discover -s tests
|
|
189
|
+
mypy --strict --python-version 3.11 src/meeng examples
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
O `./check.sh` da raiz do repositório sobe uma API de mentira gerada do contrato (`go run ./cmd/fakeapi`), que recusa o que o contrato não permite, e roda contra ela o teste de contrato (cada método do SDK é chamado, e nenhuma operação pode ficar de fora) e os exemplos.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"""Adds a sending domain, prints the DNS records to publish and asks for them to
|
|
2
|
+
be checked.
|
|
3
|
+
|
|
4
|
+
MEENG_API_KEY=mg_xxx PYTHONPATH=src python3 examples/add_domain.py
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from meeng import Meeng, MeengHTTPError
|
|
8
|
+
|
|
9
|
+
meeng = Meeng()
|
|
10
|
+
|
|
11
|
+
try:
|
|
12
|
+
domain, _ = meeng.domains.create({"name": "acme.com.br", "region": "us-east-1"})
|
|
13
|
+
assert domain is not None
|
|
14
|
+
print("publique estes registros no DNS de", domain["name"])
|
|
15
|
+
for record in domain["dnsRecords"]:
|
|
16
|
+
print(f" {record['type']:<5} {record['name']:<40} {record['value']}")
|
|
17
|
+
|
|
18
|
+
meeng.domains.verify(domain["id"])
|
|
19
|
+
checked, _ = meeng.domains.get(domain["id"])
|
|
20
|
+
print("situação:", checked["status"] if checked else None)
|
|
21
|
+
except MeengHTTPError as error:
|
|
22
|
+
raise SystemExit(f"{error.status_code} {error.error['code']}: {error.error['message']}")
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""Schedules an e-mail, moves it to another time and cancels it.
|
|
2
|
+
|
|
3
|
+
MEENG_API_KEY=mg_xxx PYTHONPATH=src python3 examples/schedule_email.py
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from datetime import datetime, timedelta, timezone
|
|
7
|
+
|
|
8
|
+
from meeng import Meeng, MeengHTTPError
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def in_hours(hours: int) -> str:
|
|
12
|
+
return (datetime.now(timezone.utc) + timedelta(hours=hours)).strftime("%Y-%m-%dT%H:%M:%SZ")
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
meeng = Meeng()
|
|
16
|
+
|
|
17
|
+
try:
|
|
18
|
+
sent, _ = meeng.emails.send(
|
|
19
|
+
{
|
|
20
|
+
"from": "Acme <contato@acme.com.br>",
|
|
21
|
+
"to": "ana@example.com",
|
|
22
|
+
"subject": "Lembrete: sua reunião é amanhã",
|
|
23
|
+
"html": "<p>Nos vemos às 10h.</p>",
|
|
24
|
+
"scheduledAt": in_hours(24),
|
|
25
|
+
}
|
|
26
|
+
)
|
|
27
|
+
assert sent is not None
|
|
28
|
+
email_id = sent["emailId"]
|
|
29
|
+
print("agendado:", email_id)
|
|
30
|
+
|
|
31
|
+
meeng.emails.update(email_id, {"scheduledAt": in_hours(48)})
|
|
32
|
+
print("remarcado")
|
|
33
|
+
|
|
34
|
+
meeng.emails.cancel(email_id)
|
|
35
|
+
print("cancelado")
|
|
36
|
+
except MeengHTTPError as error:
|
|
37
|
+
raise SystemExit(f"{error.status_code} {error.error['code']}: {error.error['message']}")
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""Sends up to 100 e-mails in one request.
|
|
2
|
+
|
|
3
|
+
MEENG_API_KEY=mg_xxx PYTHONPATH=src python3 examples/send_batch.py
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from meeng import Meeng, MeengHTTPError
|
|
7
|
+
|
|
8
|
+
meeng = Meeng()
|
|
9
|
+
people = [("Ana", "ana@example.com"), ("Bruno", "bruno@example.com"), ("Carla", "carla@example.com")]
|
|
10
|
+
|
|
11
|
+
try:
|
|
12
|
+
sent, _ = meeng.emails.batch(
|
|
13
|
+
[
|
|
14
|
+
{
|
|
15
|
+
"from": "Acme <contato@acme.com.br>",
|
|
16
|
+
"to": email,
|
|
17
|
+
"subject": "Seu extrato de novembro",
|
|
18
|
+
"html": f"<p>Olá, {name}! Seu extrato está disponível.</p>",
|
|
19
|
+
}
|
|
20
|
+
for name, email in people
|
|
21
|
+
],
|
|
22
|
+
options={"idempotency_key": "extrato-2026-11"},
|
|
23
|
+
)
|
|
24
|
+
except MeengHTTPError as error:
|
|
25
|
+
raise SystemExit(f"{error.status_code} {error.error['code']}: {error.error['message']}")
|
|
26
|
+
|
|
27
|
+
for number, email in enumerate(sent["data"] if sent else [], start=1):
|
|
28
|
+
print(f"{number}: {email['emailId']}")
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""Sends one e-mail. The key comes from MEENG_API_KEY and, to point the client at
|
|
2
|
+
another app, the address from MEENG_BASE_URL.
|
|
3
|
+
|
|
4
|
+
MEENG_API_KEY=mg_xxx PYTHONPATH=src python3 examples/send_email.py
|
|
5
|
+
|
|
6
|
+
In your own project the import is the same: ``from meeng import Meeng``.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from meeng import Meeng, MeengHTTPError
|
|
10
|
+
|
|
11
|
+
meeng = Meeng()
|
|
12
|
+
|
|
13
|
+
try:
|
|
14
|
+
sent, _ = meeng.emails.send(
|
|
15
|
+
{
|
|
16
|
+
"from": "Acme <contato@acme.com.br>",
|
|
17
|
+
"to": "ana@example.com",
|
|
18
|
+
"subject": "Bem-vinda à Acme",
|
|
19
|
+
"html": "<p>Olá, Ana! Sua conta está pronta.</p>",
|
|
20
|
+
"text": "Olá, Ana! Sua conta está pronta.",
|
|
21
|
+
},
|
|
22
|
+
# A key makes the send safe to repeat: the same key with the same body
|
|
23
|
+
# answers the first result again, and nothing is sent twice.
|
|
24
|
+
options={"idempotency_key": "boas-vindas-ana-2026-11-20"},
|
|
25
|
+
)
|
|
26
|
+
except MeengHTTPError as error:
|
|
27
|
+
raise SystemExit(f"{error.status_code} {error.error['code']}: {error.error['message']}")
|
|
28
|
+
|
|
29
|
+
print("e-mail na fila:", sent["emailId"] if sent else None)
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""Checks a webhook the way an endpoint does: the signature and the time are
|
|
2
|
+
verified against the raw body, and then the event is read.
|
|
3
|
+
The request here is made in the program; a real endpoint reads the body and the
|
|
4
|
+
headers of the request it receives, and the secret from its settings.
|
|
5
|
+
|
|
6
|
+
PYTHONPATH=src python3 examples/verify_webhook.py
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import hashlib
|
|
10
|
+
import hmac
|
|
11
|
+
import json
|
|
12
|
+
import time
|
|
13
|
+
|
|
14
|
+
from meeng import Meeng, WebhookVerificationError
|
|
15
|
+
|
|
16
|
+
secret = "whsec_exemplo"
|
|
17
|
+
body = json.dumps(
|
|
18
|
+
{
|
|
19
|
+
"id": "call_1",
|
|
20
|
+
"type": "email.delivered",
|
|
21
|
+
"version": "2026-01-18",
|
|
22
|
+
"createdAt": "2026-11-20T12:00:00Z",
|
|
23
|
+
"teamId": 7,
|
|
24
|
+
"attempt": 1,
|
|
25
|
+
"data": {"id": "em_1", "status": "DELIVERED", "from": "contato@acme.com.br", "to": ["ana@example.com"], "occurredAt": "2026-11-20T12:00:00Z"},
|
|
26
|
+
}
|
|
27
|
+
)
|
|
28
|
+
timestamp = str(int(time.time() * 1000))
|
|
29
|
+
signature = hmac.new(secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
|
|
30
|
+
headers = {"x-meeng-signature": f"v1={signature}", "x-meeng-timestamp": timestamp}
|
|
31
|
+
|
|
32
|
+
try:
|
|
33
|
+
event = Meeng("mg_exemplo").webhooks(secret).construct_event(body, headers=headers)
|
|
34
|
+
except WebhookVerificationError as error:
|
|
35
|
+
raise SystemExit(f"{error.code}: {error}")
|
|
36
|
+
|
|
37
|
+
if event["type"] == "email.delivered":
|
|
38
|
+
print("e-mail", event["data"]["id"], "entregue a", ", ".join(event["data"]["to"]))
|
|
39
|
+
else:
|
|
40
|
+
print("evento", event["type"])
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.33"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "meeng-sdk"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Meeng.dev's SDK for Python: emails, domains, contacts, contact books, campaigns, analytics and webhooks."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
dependencies = []
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Programming Language :: Python :: 3",
|
|
15
|
+
"Typing :: Typed",
|
|
16
|
+
]
|
|
17
|
+
|
|
18
|
+
[project.urls]
|
|
19
|
+
Homepage = "https://meeng.dev"
|
|
20
|
+
Repository = "https://github.com/meeng-dev/sdk"
|
|
21
|
+
|
|
22
|
+
[tool.hatch.build.targets.wheel]
|
|
23
|
+
packages = ["src/meeng"]
|