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.
@@ -0,0 +1,4 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ dist/
4
+ .venv/
@@ -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"]